« Changelog History


RDoc v4.0.0.preview2 Release Notes

Release Date: 2012-12-14 // over 11 years ago

    • 💥 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 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 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 ChangeLog parser. It automatically parses files that begin with 'ChangeLog'
      • 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.