Rdoc 4.0.0.preview2

rdoc version 4.0.0.preview2 has been released!

RDoc produces HTML and command-line documentation for Ruby projects.
RDoc
includes the +rdoc+ and +ri+ tools for generating and displaying
documentation
from the command-line.

Changes:

=== 4.0.0.preview2

As a preview release, please file bugs for any problems you have with
rdoc at

RDoc 4.0 includes several new features and several breaking changes.
The
changes should not affect users of rdoc or ri.

Notable feature additions are markdown support and an WEBrick servlet
that can
serve HTML from an ri store. (This means that RubyGems 2.0+ no longer
needs
to build HTML documentation when installing gems.)

  • Breaking changes
    • The default output encoding for RDoc is now UTF-8. Previously RDoc
      used
      the default external encoding which was determined from your locale.
      Issue #106 by Justin Baker.

    • RDoc::RI::Store is now RDoc::Store so ri data generated by RDoc 4
      cannot
      be read by earlier versions of RDoc. RDoc::RI::Store exists as an
      alias
      of RDoc::Store so ri data from older versions can still be read.
      RDoc::RI::Store will be removed in RDoc 5.

      Tests that create RDoc::CodeObjects on the fly without wiring them
      into
      the documentation tree (did not use add_class, add_method, etc.)
      must be
      updated to use these methods. The documentation tree automatically
      attaches them to the store instance which allows lookups to work
      correctly. Additionally, a new method RDoc::Store#add_file must be
      used
      instead of RDoc::TopLevel.new. The latter will not be attached to
      the
      documentation tree.

    • RDoc generators must accept an RDoc::Store and an RDoc::Options in
      initialize. RDoc no longer passes an Array of RDoc::TopLevel
      objects to
      #generate. Use RDoc::Store#all_files instead.

    • Some markup formatters (RDoc::Markup::To*) now accept an
      RDoc::Options
      instance as the first argument. Notably, the base class Formatter
      and
      ToHtml*. (This is not universal due to the difficult at accessing
      the
      user’s options instance deep inside RDoc. A future major release
      may
      remedy this.)

    • Added new markup nodes and specials that RDoc::Markup::Formatter
      subclasses must handle. If you’re using
      RDoc::Markup::FormatterTestCase
      the new methods you need to add should be readily apparent.

    • Removed RDoc::RI::Paths::SYSDIR and ::SITEDIR. These were hidden
      constants so no breakage is expected. Use
      RDoc::RI::Paths::system_dir
      and ::site_dir instead.

    • RDoc::RI::Store#modules has been renamed to RDoc::Store#module_names
      to avoid confusion with RDoc::Store#all_modules imported from
      RDoc::TopLevel.

    • RDoc::RDocError has been removed. It was deprecated throughout RDoc

  • ri -f html is no longer supported.

  • Comment definitions in C comments are now only discovered from the
    first
    line. A colon on a subsequent line won’t trigger definition
    extraction.
    Issue #103, see also
    http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/42942

  • Fixed :stopdoc: for class A::B where A has not been seen. Issue #95
    by
    Ryan D.

  • RDoc::ClassModule#each_ancestor no longer yields itself if there is
    circular ancestry

  • Major enhancements

    • ri can now show pages (README, etc.)

      ri rdoc:README

      Will show the README for the latest version of RDoc. You can
      specify
      exact gem versions such as “rdoc-4.0:README” or view pages from the
      standard library documentation with “ruby:README”.

      RDoc 3 did not save pages in ri data so you will need to regenerate
      documentation from your gems to use this feature.

    • Added Markdown as a supported format. The markdown format can be
      set on a
      per-file or per-comment basis with the +:markdown:+ directive like
      the rd
      and tomdoc formats and on a per-project basis with
      rdoc --markup markdown --write-options

    • Removed global state from RDoc. RDoc::Store holds the documentation
      tree
      and connects the driver to the parsers and generator. This also
      allows
      documentation parsing and generation for multiple instances, but the
      rdoc
      command-line tool does not support this.

      Due to this change RDoc::RDoc.current and RDoc::RDoc.reset no longer
      exist.

  • Minor enhancements

    • Added --root for building documentation from outside the source dir.
    • Added a table of contents to the sidebar.
    • RDoc markup format merges adjacent labels in a label or note list
      into a
      single definition list item for output.
    • RDoc now tracks use of extend. Pull request #118 by Michael
      Granger.
    • RDoc now tracks methods that use super. Pull request #116 by Erik
      Hollensbe.
    • Added methods ::system_dir, ::site_dir, ::home_dir and ::gem_dir to
      fetch
      the components of RDoc::RI::Paths.path individually.
    • Added support for rb_file_const.
    • RDoc now processes files in sorted order. Issue #71 by Vt Ondruch
    • RDoc now warns with --verbose when methods are duplicated. Issue
      #71 by
      Vt Ondruch
    • ri will display documentation for all methods in a class if -a is
      given.
      Issue #57 by casper
    • The RDoc coverage report will report line information for
      attributes,
      constants and methods missing documentation. Issue #121 by Zachary
      Scott
    • RDoc now reports a warning for files that are unreadable due to
      permissions problems.
    • RDoc controls documentation generation for RubyGems 2.0+
  • Bug fixes

    • A word that is directly followed by a multi-word tidy link label no
      longer
      disappears. (Like text{link}[http://example])
    • Fixed legacy template support. Pull Request #107 by Justin Baker.
    • An HTML class in a verbatim section no longer triggers ruby parsing.
      Issue #92 by Vijay D.
    • Improved documentation for setting the default documentation format
      for
      your ruby project. Issue #94 by Henrik H.
    • Fixed handling of LANG in the RDoc::Options tests. Issue #99 by Vt
      Ondruch
    • RDoc no longer quits when given an entry that is not a file or
      directory.
      Issue #101 by Charles Nutter
    • Fixed bug in syntax-highlighting that would corrupt regular
      expressions.
      Ruby Bug #6488 by Benny Lyne Amorsen.
    • “class Object” no longer appears in the coverage report if all its
      methods
      are documented. This suppresses a false positive for libraries that
      add
      toplevel methods. Pull Request #128 by Zachary S…
    • Fixed test_gen_url test name in TestRDocMarkupToHtml. Pull Request
      #130
      by Zachary S…
    • Comment-defined methods ahead of define_method are now discovered.
      Issue
      #133 by eclectic923
    • Fixed detection of define_method documentation. Issue #138 by
      Marvin
      Glker.
    • Fixed lexing of character syntax (?z). Reported by
      Xavier
      Noria.
    • Add license to gem spec. Issue #144 by pivotalcommon
    • Fixed comment selection for classes. Pull request #146 by pioz
    • Fixed parsing of def self.&() end. Issue #148 by
      Michael
      Lucy
    • Generated RD parser files are now included in the gem. Issue #145
      by
      Marvin G.
    • Class and module aliases now create new classes to avoid duplicate
      names
      in the class list. Issue #143 by Richard S., Rails Issue
      #2839
    • RDoc::Markup::Parser now correctly matches indentation of lists when
      multibyte characters are used in the list labels. Issue #140 by
      burningTyger
    • Fixed mangling of email addresses that look like labels. Issue #129
      by
      Tobias Koch
    • Classes and modules in a C file may now be created in any order.
      Issue
      #124 by Su Zhang
    • A metaprogrammed method supports the :args: directive. Issue #100
    • A metaprogrammed method supports the :yields: directive.
    • RDoc will now look for directives up to the end of the line. For
      example,
      class B < A; end # :nodoc:
      will now hide documentation of B. Issue #125 by Zachary S.
    • Fixed tokenization of % when it is not followed by a $-string type
    • Fixed display of END in documentation examples in HTML output
    • Fixed tokenization of reserved words used as new-style hash keys
    • RDoc now handles class << $gvar by ignoring the body
    • Fixed parsing of class A:: B.
    • Worked around bug in RDoc::RubyLex where tokens won’t be
      reinterpreted
      after unget_tk.
    • Fixed class << ::Foo writing documentation to /Foo.html
    • Fixed class ::A referencing itself from inside its own namespace.

Notable feature additions are markdown support and an WEBrick servlet that
can
serve HTML from an ri store. (This means that RubyGems 2.0+ no longer
needs
to build HTML documentation when installing gems.)

Nice! I had a gem that did that, but it was quite the hack, so it was
never
very useful. But I always seemed like a good idea. So I am pleased to
see
that RDoc can now do it right out of the box.

Quick questions:

  1. Can it browse multiple gems at once, or just one at a time?
  2. Can it take advantage of custom formats?

Thanks.

On Dec 1, 2012, at 15:07, Intransition [email protected] wrote:

Notable feature additions are markdown support and an WEBrick servlet that can
serve HTML from an ri store. (This means that RubyGems 2.0+ no longer needs
to build HTML documentation when installing gems.)

Nice! I had a gem that did that, but it was quite the hack, so it was never very
useful. But I always seemed like a good idea. So I am pleased to see that RDoc can
now do it right out of the box.

Quick questions:

  1. Can it browse multiple gems at once, or just one at a time?

Multiple gems at once. At the top level you can type to filter on
installed gems.

  1. Can it take advantage of custom formats?

Currently it uses the darkish generator. Due to lack of time I haven’t
investigated alternate output templates. Allowing alternate output
formats is possible before RDoc 4 final. The feature is rather coupled
to darkish so I’m unsure what work would be needed for alternate
generators. I’d rather delay that for a future release than rush it.

REMOVE [email protected]

does not work here anymore.

On Saturday, December 1, 2012 8:08:03 PM UTC-5, Eric H. wrote:

Multiple gems at once. At the top level you can type to filter on
installed gems.

Awesome!

Currently it uses the darkish generator. Due to lack of time I haven’t
investigated alternate output templates. Allowing alternate output formats
is possible before RDoc 4 final. The feature is rather coupled to darkish
so I’m unsure what work would be needed for alternate generators. I’d
rather delay that for a future release than rush it.

Yea, no need to rush. At least it’s something to look forward to in a
future version :slight_smile:

You’ve done a really great job with RDoc, Eric. I had drifted away into
YARD territory, but now I am felling all torn. RDoc has improved so much
over the last few years. Really great work.

This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.

| Privacy Policy | Terms of Service | Remote Ruby Jobs