Comprehensive release notes for 4.0.0.rc.2.1

All updates since 3.12.1 are included in History.rdoc for 4.0.0.rc.2.1
now.

Also, History.rdoc contains 3.12.1 and missing 3.9.x releases.

Author: drbrain

History.rdoc

@@ -10,6 +10,196 @@ 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.)
 
+Changes since RDoc 3.12.1:
+
+* 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
+    <tt>rdoc --markup markdown --write-options</tt>
+  * 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 --page-dir option to give pretty names for a FAQ, guides, or other
+    documentation you write that is not stored in the project root.  For
+    example, with the following layout:
+
+      README.txt
+      guides/syntax.txt
+      guides/conversion.txt
+
+    Running `rdoc --page-dir guides` will make the files in "guides" appear to
+    be at the top level of the project.  This means they will appear to exist
+    at the top level in HTML output and you can access them with
+    `ri your_gem:syntax` and `ri your_gem:conversion`.
+  * Added --root for building documentation from outside the source dir.
+  * Added current heading and page-top links to HTML headings.
+  * 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
+  * Fixed parsing of multibyte files with incomplete characters at byte 1024.
+    Ruby bug #6393 by nobu, patch by Nobuyoshi Nakada and Yui NARUSE.
+  * Fixed rdoc -E.  Ruby Bug #6392 and (modified) patch by Nobuyoshi Nakada
+  * Added link handling to Markdown output.  Bug #160 by burningTyger.
+  * Fixed HEREDOC output for the limited case of a heredoc followed by a line
+    end.  When a HEREDOC is not followed by a line end RDoc is not currently
+    smart enough to restore the source correctly.  Bug #162 by Zachary Scott.
+  * Fixed parsing of executables with shebang and encoding comments.  Bug #161
+    by Marcus Stollsteimer
+  * RDoc now ignores methods defined on constants instead of creating a fake
+    module.  Bug #163 by Zachary Scott.
+  * Fixed ChangeLog parsing for FFI gem.  Bug #165 by Zachary Scott.
+  * RDoc now links \#=== methods.  Bug #164 by Zachary Scott.
+  * Allow [] following argument names for TomDoc.  Bug #167 by Ellis Berner.
+  * Fixed the RDoc servlet for home and site directories.  Bug #170 by Thomas
+    Leitner.
+  * Fixed references to methods in the RDoc servlet.  Bug #171 by Thomas
+    Leitner.
+  * Fixed debug message when generating the darkfish root page.  Pull Request
+    #174 by Thomas Leitner.
+  * Fixed deletion of attribute ri data when a class was loaded then saved.
+    Issue #171 by Thomas Leitner.
+  * Fully qualified names for constants declared from the top level are now
+    attached to their class or module properly.
+  * Fixed table of contents display in HTML output for classes and modules.
+  * Incremental ri builds of C files now work.  C variable names from previous
+    runs are now saved between runs.
+  * A word that is directly followed by a multi-word tidy link label no longer
+    disappears.  (Like <code>text{link}[http://example]</code>)
+  * 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 (<code>?z</code>).  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 <code>def self.&() end</code>.  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.
+
+Changes since RDoc 4.0.0.rc.2:
+
 * Bug fix
   * Templates now use the correct encoding when generating pages.  Issue #183
     by Vít Ondruch
@@ -217,6 +407,14 @@ to build HTML documentation when installing gems.)
   * Fixed class << ::Foo writing documentation to /Foo.html
   * Fixed class ::A referencing itself from inside its own namespace.
 
+=== 3.12.1 / 2013-02-05
+
+* Bug fixes
+  * Fixed an XSS exploit in darkfish.js.  This could lead to cookie disclosure
+    to third parties.  See CVE-2013-0256[rdoc-ref:CVE-2013-0256.rdoc] for full
+    details including a patch you can apply to generated RDoc documentation.
+  * Ensured that rd parser files are generated before checking the manifest.
+
 === 3.12 / 2011-12-15
 
 * Minor enhancements
@@ -359,6 +557,28 @@ to build HTML documentation when installing gems.)
     parsed.  Unless your project includes nonexistent modules this avoids
     worst-case behavior (<tt>O(n!)</tt>) of RDoc::Include#module.
 
+=== 3.9.5 / 2013-02-05
+
+* Bug fixes
+  * Fixed an XSS exploit in darkfish.js.  This could lead to cookie disclosure
+    to third parties.  See CVE-2013-0256.rdoc for full details including a
+    patch you can apply to generated RDoc documentation.
+
+=== 3.9.4 / 2011-08-26
+
+* Bug fixes
+  * Applied typo and grammar fixes from Luke Gruber.  Ruby bug #5203
+
+=== 3.9.3 / 2011-08-23
+
+* Bug fixes
+  * Add US-ASCII magic comments to work with <tt>ruby -Ku</tt>.  Issue #63 by
+    Travis D. Warlick, Jr.
+  * Image paths at HTTPS URLs are now turned into +<img>+ tags.  Pull
+    Request #60 by James Mead
+  * Markup defined by RDoc::Markup#add_special inside a <tt><tt></tt> is no
+    longer converted.
+
 === 3.9.2 / 2011-08-11
 
 * Bug fix