kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

Import RDoc r101.

Browse source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@18121 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain 2008-07-18 00:46:16 +00:00
parent 0af4a490b4
commit fd25f74d64
45 changed files with 6952 additions and 4397 deletions
Download patch file Download diff file Expand all files Collapse all files

134
lib/rdoc.rb
View file

@ -1,8 +1,8 @@
$DEBUG_RDOC = nil
##
# = RDOC - Ruby Documentation System
#
# 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,
@ -12,12 +12,12 @@ $DEBUG_RDOC = nil
# 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
# * If you want to include extensions written in C, see RDoc::Parser::C
# * For information on the various markups available in comment blocks, see
# RDoc::Markup.
# * If you want to drive RDoc programmatically, see RDoc::RDoc.
@ -25,63 +25,63 @@ $DEBUG_RDOC = nil
# 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).
#
# 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
# 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.
# #--
@ -92,40 +92,40 @@ $DEBUG_RDOC = nil
# 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.
#
# 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
@ -143,27 +143,27 @@ $DEBUG_RDOC = nil
# class Output
# end
# end
#
# In the above code, only class +MyModule::Input+ will be documented.
# :nodoc: is global across all files the class or module appears in, so use
# :stopdoc:/:startdoc: to only omit documentation for a particular set of
# methods, etc.
#
#
# In the above code, only class +MyModule::Input+ will be documented.The
# The :nodoc: directive is global across all files the class or module
# appears in, so use :stopdoc:/:startdoc: to only omit documentation for a
# particular set of methods, etc.
#
# [+: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
# 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:
#
#
# [<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
@ -178,66 +178,66 @@ $DEBUG_RDOC = nil
# # 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.
#
# 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.
#
#
# = Other stuff
#
#
# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>
#
# Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
#
#
# == 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.
@ -254,7 +254,7 @@ module RDoc
##
# RDoc version you are using
VERSION = "2.0.0"
VERSION = "2.1.0"
##
# Name of the dotfile that contains the description of files to be processed