rdoc 2.5.11 → 3.0

data/.document

@@ -1,4 +1,5 @@
 History.txt
+LICENSE.txt
 README.txt
 RI.txt
 lib

data/History.txt

@@ -1,3 +1,98 @@
+=== 3.0 / 2010-12-19
+
+Special thanks to Thierry Lambert for massive improvements to RDoc.
+
+* Major enhancements
+  * Ruby 1.8.6 is no longer supported by RDoc.
+  * RDoc now converts input files to a single encoding specified by
+    <tt>--encoding</tt>.  See RDoc::RDoc and RDoc::Options#encoding.
+    <tt>--encoding</tt> is now preferred over <tt>--charset</tt>
+  * RDoc now supports a <tt>--coverage-report</tt> flag (also <tt>-C</tt> and
+    <tt>--dcov</tt>) that outputs a report on items lacking documentation.
+  * Templates (<tt>rdoc -T</tt>) are now checked for existence in
+    RDoc::Options.  Generator authors can now use RDoc::Options#template_dir
+    which is the full path to the template directory.
+  * Added support for class aliases.  Patch by Thierry Lambert.
+  * Improved merging of classes and modules across multiple files including
+    more accurate documentation statistics.  Patch by Thierry Lambert.
+  * Improved handling of method aliases.  Patch by Thierry Lambert.
+  * Improved handling of visibility of RDoc code objects.  Patch by Thierry
+    Lambert.
+  * RDoc::Attr#type is now RDoc::Attr#definition.  Patch by Thierry Lambert.
+  * Removed TimeConstantMethods
+  * RDoc now calls ::new instead of ::for on generators.
+* Minor enhancements
+  * Added rdoc arguments <tt>--dry-run</tt>, <tt>--all</tt>,
+    <tt>--visibility</tt>, <tt>--force-output</tt>, <tt>--hyperlink-all</tt>.
+    Patch by Thierry Lambert.
+  * RDoc::Markup::FormatterTestCase has been expanded.  Patch by Thierry
+    Lambert.
+  * RDoc::Markup::TextFormatterTestCase has been extracted from RDoc tests.
+    Patch by Thierry Lambert.
+  * Various RDoc::Parser::Ruby enhancements.  Patch by Thierry Lambert.
+  * Various RDoc::Markup::Parser enhancements.  Patch by Thierry Lambert.
+  * RDoc::Parser::binary? is more robust now that it uses Encoding.
+  * Deprecated rdoc arguments are now explicitly mentioned in rdoc command
+    output.  Patch by Thierry Lambert.
+  * Constant values are formatted more accurately.  Patch by Thierry Lambert.
+  * Enhanced call-seq parsing in RDoc::Parser::C.  Patch by Thierry Lambert.
+  * RDoc no longer uses kw, cmt, re or str classes for embedded source code
+    snippets.  Patch by Thierry Lambert.
+  * RDoc directives may now be escaped with a leading '\\'.  Patch by Thierry
+    Lambert.
+  * RDoc note lists (<tt>label::</tt>) now generate a table with class
+    "rdoc-list".  Patch by Thierry Lambert.
+  * RDoc markup documentation has been moved to RDoc::Markup including notes
+    on how to document source code.
+  * An RDoc::Require is now always listed at the file level.  Patch by Thierry
+    Lambert.
+  * RDoc::CodeObjects now know which file they were defined in.
+  * RDoc::Options calls ::setup_options on the generator class specified by
+    <tt>--format</tt>.  See RDoc::Options::setup_generator.
+  * rdoc gives an error when multiple formats are given.
+  * Files with erb inside will no longer trip RDoc::Parser::binary?
+  * Last <tt>--title</tt> wins.  Patch by Thierry Lambert.
+  * Better block params handling.  Patch by Thierry Lambert.
+  * Moved rdoc/tokenstream.rb to rdoc/token_stream.rb.
+  * Moved rdoc/markup/preprocess.rb to rdoc/markup/pre_process.rb.
+  * Removed "':' not followed by operator or identifier" warning for new Hash
+    syntax.
+  * rb_attr() is now supported for attributes.
+  * RDoc::Parser::C now supports yields, doc, and args directives like
+    RDoc::Parser::Ruby.
+  * Moved RDoc::Parser::PerlPOD to the rdoc-perl_pod gem.
+* Bug fixes
+  * RDoc::Generator tests no longer require any installed RDoc on Ruby 1.9
+  * Load existing cache before generating ri.  Ruby r27749 by NAKAMURA Usaku.
+  * RDoc now handles BOM.  Ruby r28062 by Nobuyoshi Nakada.
+  * Use proper XML encoding for darkfish classpage.  Ruby r28083 by NARUSE,
+    Yui.
+  * Fix ri output when special characters are inside html tags.  Patch by Tomo
+    Kazahaya, Ruby Bug #3512.
+  * Don't bother checking if the pager exists, it's already done.  Ruby r28842
+    by NAKAMURA Usaku.
+  * RDoc::Parser::Ruby now ignores non-constant-named singleton classes.  Ruby
+    r29140 by Nobuyoshi Nakada.  Ruby Bug #3759.
+  * RDoc::Parser::Ruby call args no longer include assignment.  Ruby r29141 by
+    Nobuyoshi Nakada.  Ruby Bug #3759
+  * Handle $HOME being unset in ri.  Ruby r29272 by Nobuyoshi Nakada.
+  * uniq ancestors and modules too.  Ruby r29312 by Nobuyoshi Nakada.
+  * RDoc now knows about Encoding by default.  Ruby r29356 by Nobuyoshi
+    Nakada.
+  * ri now defaults to the backspace formatter when piped.  Use RI environment
+    variable or options to override. Ruby r28455 by Yusuke Endoh.
+  * __send__ and friends no longer get their underscores removed.  Patch by
+    Thierry Lambert.
+  * The C parser now makes new public when promoting initialize.
+  * Fix crash in #markup_code for TkUnknownChar.
+  * Fix crash in RDoc::Parser::C when aliasing methods with Regexp special
+    characters.
+  * Fix crash when various operators are used as a name as in
+    <tt>alias * compose</tt>.
+  * Fix warning with some dynamic use of <tt>attr_*</tt>
+  * Methods added to true, false and nil are now documented.
+  * Remove warning for methods defined on globals.
+
 === 2.5.11 / 2010-08-20
 
 * Minor Enhancements

data/Manifest.txt

@@ -18,6 +18,8 @@ lib/rdoc/code_object.rb
 lib/rdoc/code_objects.rb
 lib/rdoc/constant.rb
 lib/rdoc/context.rb
+lib/rdoc/encoding.rb
+lib/rdoc/erbio.rb
 lib/rdoc/gauntlet.rb
 lib/rdoc/generator.rb
 lib/rdoc/generator/darkfish.rb
@@ -67,9 +69,10 @@ lib/rdoc/markup/list.rb
 lib/rdoc/markup/list_item.rb
 lib/rdoc/markup/paragraph.rb
 lib/rdoc/markup/parser.rb
-lib/rdoc/markup/preprocess.rb
+lib/rdoc/markup/pre_process.rb
 lib/rdoc/markup/raw.rb
 lib/rdoc/markup/rule.rb
+lib/rdoc/markup/text_formatter_test_case.rb
 lib/rdoc/markup/to_ansi.rb
 lib/rdoc/markup/to_bs.rb
 lib/rdoc/markup/to_html.rb
@@ -78,12 +81,12 @@ lib/rdoc/markup/to_rdoc.rb
 lib/rdoc/markup/to_test.rb
 lib/rdoc/markup/verbatim.rb
 lib/rdoc/meta_method.rb
+lib/rdoc/method_attr.rb
 lib/rdoc/normal_class.rb
 lib/rdoc/normal_module.rb
 lib/rdoc/options.rb
 lib/rdoc/parser.rb
 lib/rdoc/parser/c.rb
-lib/rdoc/parser/perl.rb
 lib/rdoc/parser/ruby.rb
 lib/rdoc/parser/ruby_tools.rb
 lib/rdoc/parser/simple.rb
@@ -98,9 +101,12 @@ lib/rdoc/ruby_lex.rb
 lib/rdoc/ruby_token.rb
 lib/rdoc/single_class.rb
 lib/rdoc/stats.rb
+lib/rdoc/stats/normal.rb
+lib/rdoc/stats/quiet.rb
+lib/rdoc/stats/verbose.rb
 lib/rdoc/task.rb
 lib/rdoc/text.rb
-lib/rdoc/tokenstream.rb
+lib/rdoc/token_stream.rb
 lib/rdoc/top_level.rb
 test/README
 test/binary.dat
@@ -109,12 +115,15 @@ test/test.ja.rdoc
 test/test.ja.txt
 test/test.txt
 test/test_attribute_manager.rb
+test/test_rdoc_alias.rb
 test/test_rdoc_any_method.rb
 test/test_rdoc_attr.rb
 test/test_rdoc_class_module.rb
 test/test_rdoc_code_object.rb
 test/test_rdoc_constant.rb
 test/test_rdoc_context.rb
+test/test_rdoc_encoding.rb
+test/test_rdoc_generator_darkfish.rb
 test/test_rdoc_generator_ri.rb
 test/test_rdoc_include.rb
 test/test_rdoc_markup.rb
@@ -129,12 +138,12 @@ test/test_rdoc_markup_to_bs.rb
 test/test_rdoc_markup_to_html.rb
 test/test_rdoc_markup_to_html_crossref.rb
 test/test_rdoc_markup_to_rdoc.rb
+test/test_rdoc_method_attr.rb
 test/test_rdoc_normal_class.rb
 test/test_rdoc_normal_module.rb
 test/test_rdoc_options.rb
 test/test_rdoc_parser.rb
 test/test_rdoc_parser_c.rb
-test/test_rdoc_parser_perl.rb
 test/test_rdoc_parser_ruby.rb
 test/test_rdoc_parser_simple.rb
 test/test_rdoc_rdoc.rb

data/README.txt

@@ -1,4 +1,4 @@
-= \RDoc
+= \RDoc - Ruby Documentation System
 
 * {RDoc Project Page}[http://rubyforge.org/projects/rdoc/]
 * {RDoc Documentation}[http://rdoc.rubyforge.org/]
@@ -25,13 +25,19 @@ See RDoc for a description of RDoc's markup and basic use.
 == BUGS:
 
 If you find a bug, please report it at the RDoc project's
-tracker[http://rubyforge.org/tracker/?group_id=627] on RubyForge:
+tracker[http://rubyforge.org/tracker/?group_id=627] on RubyForge
 
 == LICENSE:
 
 RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.
-Portions (c) 2007-2009 Eric Hodel.  Portions copyright others, see individual
+Portions (c) 2007-2010 Eric Hodel.  Portions copyright others, see individual
 files for details.
 
 It is free software, and may be redistributed under the terms specified in
 LICENSE.txt.
+
+== WARRANTY:
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.

data/Rakefile

@@ -13,7 +13,7 @@ Hoe.spec 'rdoc' do
   self.remote_rdoc_dir = ''
   self.testlib = :minitest
 
-  extra_dev_deps   << ['minitest', '~> 1.3']
+  extra_dev_deps   << ['minitest', '~> 2']
   extra_rdoc_files << 'Rakefile'
   spec_extras['required_rubygems_version'] = '>= 1.3'
   spec_extras['homepage'] = 'http://rdoc.rubyforge.org'

data/lib/rdoc.rb

@@ -18,14 +18,16 @@ $DEBUG_RDOC = nil
 # == Roadmap
 #
 # * If you want to use RDoc to create documentation for your Ruby source files,
-#   read on.
+#   read the summary below, and refer to <tt>rdoc --help</tt> for command line
+#   usage, and RDoc::Markup for a detailed description of RDoc's markup.
 # * If you want to generate documentation for extensions written in C, see
 #   RDoc::Parser::C
 # * If you want to drive RDoc programmatically, see RDoc::RDoc.
-# * If you want to use the library to format text blocks into HTML, have a look
-#   at RDoc::Markup.
-# * If you want to try writing your own HTML output template, see
-#   RDoc::Generator::HTML
+# * If you want to use the library to format text blocks into HTML, look at
+#   RDoc::Markup.
+# * If you want to make an RDoc plugin such as a generator or directive
+#   handler see RDoc::RDoc.
+# * If you want to try writing your own output generator see RDoc::Generator.
 #
 # == Summary
 #
@@ -50,7 +52,7 @@ $DEBUG_RDOC = nil
 # index page contain the documentation for the primary file.  In our
 # case, we could type
 #
-#   % rdoc --main rdoc.rb
+#   % rdoc --main README.txt
 #
 # You'll find information on the various formatting tricks you can use
 # in comment blocks in the documentation this generates.
@@ -62,281 +64,9 @@ $DEBUG_RDOC = nil
 # markers).  If directory names are passed to RDoc, they are scanned
 # recursively for C and Ruby source files only.
 #
-# == \Options
-#
-# rdoc can be passed a variety of command-line options.  In addition,
-# options can be specified via the +RDOCOPT+ environment variable, which
-# functions similarly to the +RUBYOPT+ environment variable.
-#
-#   % export RDOCOPT="-S"
-#
-# will make rdoc default to inline method source code.  Command-line options
-# always will override those in +RDOCOPT+.
-#
-# Run:
-#
-#   rdoc --help
-#
-# for full details on rdoc's options.
-#
-# == Documenting Source Code
-#
-# Comment blocks can be written fairly naturally, either using <tt>#</tt> on
-# successive lines of the comment, or by including the comment in
-# a =begin/=end block.  If you use the latter form, the =begin line must be
-# flagged with an RDoc tag:
-#
-#   =begin rdoc
-#   Documentation to be processed by RDoc.
-#
-#   ...
-#   =end
-#
-# RDoc stops processing comments if it finds a comment line containing
-# a <tt>--</tt>.  This can be used to separate external from internal
-# comments, or to stop a comment being associated with a method, class, or
-# module.  Commenting can be turned back on with a line that starts with a
-# <tt>++</tt>.
-#
-#   ##
-#   # Extract the age and calculate the date-of-birth.
-#   #--
-#   # FIXME: fails if the birthday falls on February 29th
-#   #++
-#   # The DOB is returned as a Time object.
-#
-#   def get_dob(person)
-#     # ...
-#   end
-#
-# Names of classes, files, and any method names containing an
-# underscore or preceded by a hash character are automatically hyperlinked
-# from comment text to their description.
-#
-# Method parameter lists are extracted and displayed with the method
-# description.  If a method calls +yield+, then the parameters passed to yield
-# will also be displayed:
-#
-#   def fred
-#     ...
-#     yield line, address
-#
-# This will get documented as:
-#
-#   fred() { |line, address| ... }
-#
-# You can override this using a comment containing ':yields: ...' immediately
-# after the method definition
-#
-#   def fred # :yields: index, position
-#     # ...
-#
-#     yield line, address
-#
-# which will get documented as
-#
-#    fred() { |index, position| ... }
-#
-# +:yields:+ is an example of a documentation directive.  These appear
-# immediately after the start of the document element they are modifying.
-#
-# RDoc automatically cross-references words with underscores or camel-case.
-# To suppress cross-references, prefix the word with a \\ character.  To
-# include special characters like "\\n", you'll need to use two \\
-# characters like "\\\\\\n".
-#
-# == \Markup
-#
-# * The markup engine looks for a document's natural left margin.  This is
-#   used as the initial margin for the document.
-#
-# * Consecutive lines starting at this margin are considered to be a
-#   paragraph.
-#
-# * If a paragraph starts with a "*", "-", or with "<digit>.", then it is
-#   taken to be the start of a list.  The margin in increased to be the first
-#   non-space following the list start flag.  Subsequent lines should be
-#   indented to this new margin until the list ends.  For example:
-#
-#      * this is a list with three paragraphs in
-#        the first item.  This is the first paragraph.
-#
-#        And this is the second paragraph.
-#
-#        1. This is an indented, numbered list.
-#        2. This is the second item in that list
-#
-#        This is the third conventional paragraph in the
-#        first list item.
-#
-#      * This is the second item in the original list
-#
-# * You can also construct labeled lists, sometimes called description
-#   or definition lists.  Do this by putting the label in square brackets
-#   and indenting the list body:
-#
-#       [cat]  a small furry mammal
-#              that seems to sleep a lot
-#
-#       [ant]  a little insect that is known
-#              to enjoy picnics
-#
-#   A minor variation on labeled lists uses two colons to separate the
-#   label from the list body:
-#
-#       cat::  a small furry mammal
-#              that seems to sleep a lot
-#
-#       ant::  a little insect that is known
-#              to enjoy picnics
-#
-#   This latter style guarantees that the list bodies' left margins are
-#   aligned: think of them as a two column table.
-#
-# * Any line that starts to the right of the current margin is treated
-#   as verbatim text.  This is useful for code listings.  The example of a
-#   list above is also verbatim text.
-#
-# * A line starting with an equals sign (=) is treated as a
-#   heading.  Level one headings have one equals sign, level two headings
-#   have two,and so on.
-#
-# * A line starting with three or more hyphens (at the current indent)
-#   generates a horizontal rule.  The more hyphens, the thicker the rule
-#   (within reason, and if supported by the output device)
-#
-# * You can use markup within text (except verbatim) to change the
-#   appearance of parts of that text.  Out of the box, RDoc::Markup
-#   supports word-based and general markup.
-#
-#   Word-based markup uses flag characters around individual words:
-#
-#   [<tt>\*word*</tt>]  displays word in a *bold* font
-#   [<tt>\_word_</tt>]  displays word in an _emphasized_ font
-#   [<tt>\+word+</tt>]  displays word in a +code+ font
-#
-#   General markup affects text between a start delimiter and and end
-#   delimiter.  Not surprisingly, these delimiters look like HTML markup.
-#
-#   [<tt>\<b>text...</b></tt>]    displays word in a *bold* font
-#   [<tt>\<em>text...</em></tt>]  displays word in an _emphasized_ font
-#   [<tt>\<i>text...</i></tt>]    displays word in an <i>italicized</i> font
-#   [<tt>\<tt>text...\</tt></tt>] displays word in a +code+ font
-#
-#   Unlike conventional Wiki markup, general markup can cross line
-#   boundaries.  You can turn off the interpretation of markup by
-#   preceding the first character with a backslash.  This only works for
-#   simple markup, not HTML-style markup.
-#
-# * Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
-#   recognized.  An HTTP url that references an external image file is
-#   converted into an inline \<IMG..>.  Hyperlinks starting 'link:' are
-#   assumed to refer to local files whose path is relative to the --op
-#   directory.
-#
-#   Hyperlinks can also be of the form <tt>label</tt>[url], in which
-#   case the label is used in the displayed text, and +url+ is
-#   used as the target.  If +label+ contains multiple words,
-#   put it in braces: <em>{multi word label}[</em>url<em>]</em>.
-#
-#   Example hyperlinks:
-#
-#     link:RDoc.html
-#     http://rdoc.rubyforge.org
-#     mailto:user@example.com
-#     {RDoc Documentation}[http://rdoc.rubyforge.org]
-#     {RDoc Markup}[link:RDoc/Markup.html]
-#
-# == Directives
-#
-# [+:nodoc:+ / +:nodoc:+ all]
-#   This directive prevents documentation for the element from
-#   being generated.  For classes and modules, the methods, aliases,
-#   constants, and attributes directly within the affected class or
-#   module also will be omitted.  By default, though, modules and
-#   classes within that class of module _will_ be documented.  This is
-#   turned off by adding the +all+ modifier.
-#
-#     module MyModule # :nodoc:
-#       class Input
-#       end
-#     end
-#
-#     module OtherModule # :nodoc: all
-#       class Output
-#       end
-#     end
-#
-#   In the above code, only class <tt>MyModule::Input</tt> will be documented.
-#   The +:nodoc:+ directive is global across all files for the class or module
-#   to which it applies, so use +:stopdoc:+/+:startdoc:+ to suppress
-#   documentation only for a particular set of methods, etc.
-#
-# [+:doc:+]
-#   Forces a method or attribute to be documented even if it wouldn't be
-#   otherwise.  Useful if, for example, you want to include documentation of a
-#   particular private method.
-#
-# [+:notnew:+]
-#   Only applicable to the +initialize+ instance method.  Normally RDoc
-#   assumes that the documentation and parameters for +initialize+ are
-#   actually for the +new+ method, and so fakes out a +new+ for the class.
-#   The +:notnew:+ modifier stops this.  Remember that +initialize+ is private,
-#   so you won't see the documentation unless you use the +-a+ command line
-#   option.
-#
-# Comment blocks can contain other directives:
-#
-# [<tt>:section: title</tt>]
-#   Starts a new section in the output.  The title following +:section:+ is
-#   used as the section heading, and the remainder of the comment containing
-#   the section is used as introductory text.  Subsequent methods, aliases,
-#   attributes, and classes will be documented in this section.  A :section:
-#   comment block may have one or more lines before the :section: directive.
-#   These will be removed, and any identical lines at the end of the block are
-#   also removed.  This allows you to add visual cues such as:
-#
-#     # ----------------------------------------
-#     # :section: My Section
-#     # This is the section that I wrote.
-#     # See it glisten in the noon-day sun.
-#     # ----------------------------------------
-#
-# [+:call-seq:+]
-#   Lines up to the next blank line in the comment are treated as the method's
-#   calling sequence, overriding the default parsing of method parameters and
-#   yield arguments.
-#
-# [+:include:+ _filename_]
-#   \Include the contents of the named file at this point.  The file will be
-#   searched for in the directories listed by the +--include+ option, or in
-#   the current directory by default.  The contents of the file will be
-#   shifted to have the same indentation as the ':' at the start of
-#   the :include: directive.
-#
-# [+:title:+ _text_]
-#   Sets the title for the document.  Equivalent to the <tt>--title</tt>
-#   command line parameter.  (The command line parameter overrides any :title:
-#   directive in the source).
-#
-# [+:enddoc:+]
-#   Document nothing further at the current level.
-#
-# [+:main:+ _name_]
-#   Equivalent to the <tt>--main</tt> command line parameter.
-#
-# [+:stopdoc:+ / +:startdoc:+]
-#   Stop and start adding new documentation elements to the current container.
-#   For example, if a class has a number of constants that you don't want to
-#   document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the
-#   last.  If you don't specify a +:startdoc:+ by the end of the container,
-#   disables documentation for the entire class or module.
-#
-# Further directives can be found in RDoc::Parser::Ruby and RDoc::Parser::C
-#
 # == Other stuff
 #
-# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>
+# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
 #
 # Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
 #
@@ -345,24 +75,6 @@ $DEBUG_RDOC = nil
 # * The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
 #   work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
 #   parser for irb and the rtags package.
-#
-# * Charset patch from MoonWolf.
-#
-# * Rich Kilmer wrote the kilmer.rb output template.
-#
-# * Dan Brickley led the design of the RDF format.
-#
-# == License
-#
-# RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers.  It
-# is free software, and may be redistributed under the terms specified
-# in the README file of the Ruby distribution.
-#
-# == Warranty
-#
-# This software is provided "as is" and without any express or implied
-# warranties, including, without limitation, the implied warranties of
-# merchantibility and fitness for a particular purpose.
 
 module RDoc
 
@@ -383,7 +95,12 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '2.5.11'
+  VERSION = '3.0'
+
+  ##
+  # Method visibilities
+
+  VISIBILITIES = [:public, :protected, :private]
 
   ##
   # Name of the dotfile that contains the description of files to be processed