Import RDoc 3

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30249 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 15 insertions, 298 deletions

diff --git a/lib/rdoc.rb b/lib/rdoc.rb
index 7ce7b53a35..a453ee1039 100644
--- a/lib/rdoc.rb
+++ b/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.8'
+  VERSION = '3.0'
+
+  ##
+  # Method visibilities
+
+  VISIBILITIES = [:public, :protected, :private]
 
   ##
   # Name of the dotfile that contains the description of files to be processed