added tag v1_9_0_4

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

1 files changed, 232 insertions, 0 deletions

diff --git a/trunk/lib/rdoc/README b/trunk/lib/rdoc/README
new file mode 100644
index 0000000000..f183c61f8d
--- /dev/null
+++ b/trunk/lib/rdoc/README
@@ -0,0 +1,232 @@
+= RDOC - Ruby Documentation System
+
+This package contains RDoc and RDoc::Markup.  RDoc is an application that
+produces documentation for one or more Ruby source files.  We work similarly to
+JavaDoc, parsing the source, and extracting the definition for classes,
+modules, and methods (along with includes and requires).  We associate with
+these optional documentation contained in the immediately preceding comment
+block, and then render the result using a pluggable output formatter.
+RDoc::Markup is a library that converts plain text into various output formats.
+The markup library is used to interpret the comment blocks that RDoc uses to
+document methods, classes, and so on.
+
+== Roadmap
+
+* If you want to use RDoc to create documentation for your Ruby source files,
+  read on.
+* If you want to include extensions written in C, see RDoc::C_Parser
+* For information on the various markups available in comment blocks, see
+  RDoc::Markup.
+* 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
+
+== Summary
+
+Once installed, you can create documentation using the 'rdoc' command
+(the command is 'rdoc.bat' under Windows)
+
+  % rdoc [options] [names...]
+
+Type "rdoc --help" for an up-to-date option summary.
+
+A typical use might be to generate documentation for a package of Ruby
+source (such as rdoc itself). 
+
+  % rdoc
+
+This command generates documentation for all the Ruby and C source
+files in and below the current directory.  These will be stored in a
+documentation tree starting in the subdirectory 'doc'.
+
+You can make this slightly more useful for your readers by having the
+index page contain the documentation for the primary file.  In our
+case, we could type
+
+  % rdoc --main rdoc.rb
+
+You'll find information on the various formatting tricks you can use
+in comment blocks in the documentation this generates.
+
+RDoc uses file extensions to determine how to process each file.  File names
+ending +.rb+ and <tt>.rbw</tt> are assumed to be Ruby source.  Files
+ending +.c+ are parsed as C files.  All other files are assumed to
+contain just Markup-style markup (with or without leading '#' comment markers).
+If directory names are passed to RDoc, they are scanned recursively for C and
+Ruby source files only.
+
+= Markup
+
+For information on how to make lists, hyperlinks, & etc. with RDoc, see
+RDoc::Markup.
+
+Comment blocks can be written fairly naturally, either using '#' on successive
+lines of the comment, or by including the comment in an =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 '+#--+'.
+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 '+#+++'.
+
+  ##
+  # 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, source 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.
+
+== Directives
+
+[+:nodoc:+ / +:nodoc:+ all]
+  Don't include this element in the documentation.  For classes
+  and modules, the methods, aliases, constants, and attributes
+  directly within the affected class or module will also 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 +MyModule::Input+ will be documented.
+
+[+:doc:+]
+  Force a method or attribute to be documented even if it wouldn't otherwise
+  be.  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 protected, so you won't see the
+  documentation unless you use the -a command line option.
+
+Comment blocks can contain other directives:
+
+[+:section: title+]
+  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 --title 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 --main 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.
+
+= Other stuff
+
+Author::   Dave Thomas <dave@pragmaticprogrammer.com>
+
+== Credits
+
+* 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.
+
+* Code to diagram classes and modules was written by Sergey A Yanovitsky
+  (Jah) of Enticla. 
+
+* 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.
+