RDoc 4.0.0.preview2

drbrain | Sat, 01 Dec 2012 20:50:00 GMT

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

comment

Comments

Comments are disabled