This post originated from an RSS feed registered with Ruby Buzz by Eric Hodel. Original Post: RDoc 4.0.0.preview2 Feed Title: Segment7 Feed URL: http://blog.segment7.net/articles.rss Feed Description: Posts about and around Ruby, MetaRuby, ruby2c, ZenTest and work at The Robot Co-op. Latest Ruby Buzz Posts Latest Ruby Buzz Posts by Eric Hodel Latest Posts From Segment7

rdoc version 4.0.0.preview2 has been released!

• home: github.com/rdoc/rdoc

• rdoc: docs.seattlerb.org/rdoc

• bugs: github.com/rdoc/rdoc/issues

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 github.com/rdoc/rdoc/issues

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 3.

  • 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 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 Davis

  • 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 Vít Ondruch

  • RDoc now warns with –verbose when methods are duplicated. Issue #71 by Vít 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 Dev

  • Improved documentation for setting the default documentation format for your ruby project. Issue #94 by Henrik Hodne

  • Fixed handling of LANG in the RDoc::Options tests. Issue #99 by Vít 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 Scott.

  • Fixed test_gen_url test name in TestRDocMarkupToHtml. Pull Request #130 by Zachary Scott.

  • Comment-defined methods ahead of define_method are now discovered. Issue #133 by eclectic923

  • Fixed detection of define_method documentation. Issue #138 by Marvin Gülker.

  • 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ülker

  • Class and module aliases now create new classes to avoid duplicate names in the class list. Issue #143 by Richard Schneeman, 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 Scott

  • 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.