diff options
Diffstat (limited to 'vendor/gems/rdoc-2.4.3/lib/rdoc.rb')
| -rw-r--r-- | vendor/gems/rdoc-2.4.3/lib/rdoc.rb | 398 |
1 files changed, 398 insertions, 0 deletions
diff --git a/vendor/gems/rdoc-2.4.3/lib/rdoc.rb b/vendor/gems/rdoc-2.4.3/lib/rdoc.rb new file mode 100644 index 000000000..bb085ec15 --- /dev/null +++ b/vendor/gems/rdoc-2.4.3/lib/rdoc.rb @@ -0,0 +1,398 @@ +$DEBUG_RDOC = nil + +# :main: README.txt + +## +# = \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. It works similarly +# to JavaDoc, parsing the source, and extracting the definition for classes, +# modules, and methods (along with includes and requires). It associates with +# these optional documentation contained in the immediately preceding comment +# block, and then renders 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::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 +# +# == Summary +# +# Once installed, you can create documentation using the +rdoc+ command +# +# % rdoc [options] [names...] +# +# For an up-to-date option summary, type +# % rdoc --help +# +# 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 +.rbw+ 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. +# +# == \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. +# +# == 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. + +module RDoc + + ## + # Exception thrown by any rdoc error. + + class Error < RuntimeError; end + + RDocError = Error # :nodoc: + + ## + # RDoc version you are using + + VERSION = '2.4.3' + + ## + # Name of the dotfile that contains the description of files to be processed + # in the current directory + + DOT_DOC_FILENAME = ".document" + + GENERAL_MODIFIERS = %w[nodoc].freeze + + CLASS_MODIFIERS = GENERAL_MODIFIERS + + ATTR_MODIFIERS = GENERAL_MODIFIERS + + CONSTANT_MODIFIERS = GENERAL_MODIFIERS + + METHOD_MODIFIERS = GENERAL_MODIFIERS + + %w[arg args yield yields notnew not-new not_new doc] + +end + |