2008-04-26 12:14:19 -04:00
|
|
|
$DEBUG_RDOC = nil
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
# :main: README.txt
|
|
|
|
|
2008-01-08 04:07:31 -05:00
|
|
|
##
|
2008-09-24 22:43:03 -04:00
|
|
|
# = \RDoc - Ruby Documentation System
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# This package contains RDoc and RDoc::Markup. RDoc is an application that
|
2008-09-24 22:43:03 -04:00
|
|
|
# produces documentation for one or more Ruby source files. It works similarly
|
2008-04-26 12:14:19 -04:00
|
|
|
# to JavaDoc, parsing the source, and extracting the definition for classes,
|
2008-09-24 22:43:03 -04:00
|
|
|
# modules, and methods (along with includes and requires). It associates with
|
2008-04-26 12:14:19 -04:00
|
|
|
# these optional documentation contained in the immediately preceding comment
|
2008-09-24 22:43:03 -04:00
|
|
|
# block, and then renders the result using a pluggable output formatter.
|
2008-04-26 12:14:19 -04:00
|
|
|
# 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.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# == Roadmap
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# * If you want to use RDoc to create documentation for your Ruby source files,
|
2010-12-19 22:22:49 -05:00
|
|
|
# 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.
|
2010-04-01 03:45:16 -04:00
|
|
|
# * If you want to generate documentation for extensions written in C, see
|
|
|
|
# RDoc::Parser::C
|
2008-06-04 05:37:38 -04:00
|
|
|
# * If you want to drive RDoc programmatically, see RDoc::RDoc.
|
2010-12-19 22:22:49 -05:00
|
|
|
# * 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.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# == Summary
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-09-24 22:43:03 -04:00
|
|
|
# Once installed, you can create documentation using the +rdoc+ command
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# % rdoc [options] [names...]
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-09-24 22:43:03 -04:00
|
|
|
# For an up-to-date option summary, type
|
2010-04-01 03:45:16 -04:00
|
|
|
#
|
2008-09-24 22:43:03 -04:00
|
|
|
# % rdoc --help
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# A typical use might be to generate documentation for a package of Ruby
|
2008-09-24 22:43:03 -04:00
|
|
|
# source (such as RDoc itself).
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# % rdoc
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# This command generates documentation for all the Ruby and C source
|
|
|
|
# files in and below the current directory. These will be stored in a
|
2008-09-24 22:43:03 -04:00
|
|
|
# documentation tree starting in the subdirectory +doc+.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# 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
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2010-12-19 22:22:49 -05:00
|
|
|
# % rdoc --main README.txt
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# You'll find information on the various formatting tricks you can use
|
|
|
|
# in comment blocks in the documentation this generates.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# RDoc uses file extensions to determine how to process each file. File names
|
2008-09-24 22:43:03 -04:00
|
|
|
# ending +.rb+ and +.rbw+ are assumed to be Ruby source. Files
|
2008-04-26 12:14:19 -04:00
|
|
|
# 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.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-09-24 22:43:03 -04:00
|
|
|
# == Other stuff
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2010-12-19 22:22:49 -05:00
|
|
|
# RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net>.
|
2008-04-26 12:14:19 -04:00
|
|
|
#
|
|
|
|
# Dave Thomas <dave@pragmaticprogrammer.com> is the original author of RDoc.
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# == Credits
|
2008-07-17 20:46:16 -04:00
|
|
|
#
|
2008-04-26 12:14:19 -04:00
|
|
|
# * 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.
|
2008-01-08 04:07:31 -05:00
|
|
|
|
|
|
|
module RDoc
|
|
|
|
|
2008-01-13 22:34:05 -05:00
|
|
|
##
|
|
|
|
# Exception thrown by any rdoc error.
|
|
|
|
|
|
|
|
class Error < RuntimeError; end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def self.const_missing const_name # :nodoc:
|
|
|
|
if const_name.to_s == 'RDocError' then
|
|
|
|
warn "RDoc::RDocError is deprecated"
|
|
|
|
return Error
|
|
|
|
end
|
|
|
|
|
|
|
|
super
|
|
|
|
end
|
2008-01-13 22:34:05 -05:00
|
|
|
|
2008-01-08 04:07:31 -05:00
|
|
|
##
|
|
|
|
# RDoc version you are using
|
|
|
|
|
2010-12-28 17:08:56 -05:00
|
|
|
VERSION = '3.1'
|
2010-12-19 22:22:49 -05:00
|
|
|
|
|
|
|
##
|
|
|
|
# Method visibilities
|
|
|
|
|
|
|
|
VISIBILITIES = [:public, :protected, :private]
|
2008-01-08 04:07:31 -05:00
|
|
|
|
|
|
|
##
|
|
|
|
# Name of the dotfile that contains the description of files to be processed
|
|
|
|
# in the current directory
|
|
|
|
|
|
|
|
DOT_DOC_FILENAME = ".document"
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# General RDoc modifiers
|
|
|
|
|
2008-01-13 22:34:05 -05:00
|
|
|
GENERAL_MODIFIERS = %w[nodoc].freeze
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# RDoc modifiers for classes
|
|
|
|
|
2008-01-13 22:34:05 -05:00
|
|
|
CLASS_MODIFIERS = GENERAL_MODIFIERS
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# RDoc modifiers for attributes
|
|
|
|
|
|
|
|
ATTR_MODIFIERS = GENERAL_MODIFIERS
|
|
|
|
|
|
|
|
##
|
|
|
|
# RDoc modifiers for constants
|
2008-01-13 22:34:05 -05:00
|
|
|
|
|
|
|
CONSTANT_MODIFIERS = GENERAL_MODIFIERS
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# RDoc modifiers for methods
|
|
|
|
|
2008-01-13 22:34:05 -05:00
|
|
|
METHOD_MODIFIERS = GENERAL_MODIFIERS +
|
|
|
|
%w[arg args yield yields notnew not-new not_new doc]
|
|
|
|
|
2008-01-08 04:07:31 -05:00
|
|
|
end
|
|
|
|
|