|
1 | 1 | $DEBUG_RDOC = nil |
2 | 2 |
|
3 | 3 | ## |
4 | | -# :include: rdoc/README |
| 4 | +# = RDOC - Ruby Documentation System |
| 5 | +# |
| 6 | +# This package contains RDoc and RDoc::Markup. RDoc is an application that |
| 7 | +# produces documentation for one or more Ruby source files. We work similarly |
| 8 | +# to JavaDoc, parsing the source, and extracting the definition for classes, |
| 9 | +# modules, and methods (along with includes and requires). We associate with |
| 10 | +# these optional documentation contained in the immediately preceding comment |
| 11 | +# block, and then render the result using a pluggable output formatter. |
| 12 | +# RDoc::Markup is a library that converts plain text into various output |
| 13 | +# formats. The markup library is used to interpret the comment blocks that |
| 14 | +# RDoc uses to document methods, classes, and so on. |
| 15 | +# |
| 16 | +# == Roadmap |
| 17 | +# |
| 18 | +# * If you want to use RDoc to create documentation for your Ruby source files, |
| 19 | +# read on. |
| 20 | +# * If you want to include extensions written in C, see RDoc::C_Parser |
| 21 | +# * For information on the various markups available in comment blocks, see |
| 22 | +# RDoc::Markup. |
| 23 | +# * If you want to drive RDoc programatically, see RDoc::RDoc. |
| 24 | +# * If you want to use the library to format text blocks into HTML, have a look |
| 25 | +# at RDoc::Markup. |
| 26 | +# * If you want to try writing your own HTML output template, see |
| 27 | +# RDoc::Generator::HTML |
| 28 | +# |
| 29 | +# == Summary |
| 30 | +# |
| 31 | +# Once installed, you can create documentation using the 'rdoc' command |
| 32 | +# (the command is 'rdoc.bat' under Windows) |
| 33 | +# |
| 34 | +# % rdoc [options] [names...] |
| 35 | +# |
| 36 | +# Type "rdoc --help" for an up-to-date option summary. |
| 37 | +# |
| 38 | +# A typical use might be to generate documentation for a package of Ruby |
| 39 | +# source (such as rdoc itself). |
| 40 | +# |
| 41 | +# % rdoc |
| 42 | +# |
| 43 | +# This command generates documentation for all the Ruby and C source |
| 44 | +# files in and below the current directory. These will be stored in a |
| 45 | +# documentation tree starting in the subdirectory 'doc'. |
| 46 | +# |
| 47 | +# You can make this slightly more useful for your readers by having the |
| 48 | +# index page contain the documentation for the primary file. In our |
| 49 | +# case, we could type |
| 50 | +# |
| 51 | +# % rdoc --main rdoc.rb |
| 52 | +# |
| 53 | +# You'll find information on the various formatting tricks you can use |
| 54 | +# in comment blocks in the documentation this generates. |
| 55 | +# |
| 56 | +# RDoc uses file extensions to determine how to process each file. File names |
| 57 | +# ending +.rb+ and <tt>.rbw</tt> are assumed to be Ruby source. Files |
| 58 | +# ending +.c+ are parsed as C files. All other files are assumed to |
| 59 | +# contain just Markup-style markup (with or without leading '#' comment |
| 60 | +# markers). If directory names are passed to RDoc, they are scanned |
| 61 | +# recursively for C and Ruby source files only. |
| 62 | +# |
| 63 | +# = Markup |
| 64 | +# |
| 65 | +# For information on how to make lists, hyperlinks, etc. with RDoc, see |
| 66 | +# RDoc::Markup. |
| 67 | +# |
| 68 | +# Comment blocks can be written fairly naturally, either using '#' on |
| 69 | +# successive lines of the comment, or by including the comment in |
| 70 | +# an =begin/=end block. If you use the latter form, the =begin line must be |
| 71 | +# flagged with an RDoc tag: |
| 72 | +# |
| 73 | +# =begin rdoc |
| 74 | +# Documentation to be processed by RDoc. |
| 75 | +# |
| 76 | +# ... |
| 77 | +# =end |
| 78 | +# |
| 79 | +# RDoc stops processing comments if it finds a comment line containing |
| 80 | +# a <tt>--</tt>. This can be used to separate external from internal |
| 81 | +# comments, or to stop a comment being associated with a method, class, or |
| 82 | +# module. Commenting can be turned back on with a line that starts with a |
| 83 | +# <tt>++</tt>. |
| 84 | +# |
| 85 | +# ## |
| 86 | +# # Extract the age and calculate the date-of-birth. |
| 87 | +# #-- |
| 88 | +# # FIXME: fails if the birthday falls on February 29th |
| 89 | +# #++ |
| 90 | +# # The DOB is returned as a Time object. |
| 91 | +# |
| 92 | +# def get_dob(person) |
| 93 | +# # ... |
| 94 | +# end |
| 95 | +# |
| 96 | +# Names of classes, source files, and any method names containing an |
| 97 | +# underscore or preceded by a hash character are automatically hyperlinked |
| 98 | +# from comment text to their description. |
| 99 | +# |
| 100 | +# Method parameter lists are extracted and displayed with the method |
| 101 | +# description. If a method calls +yield+, then the parameters passed to yield |
| 102 | +# will also be displayed: |
| 103 | +# |
| 104 | +# def fred |
| 105 | +# ... |
| 106 | +# yield line, address |
| 107 | +# |
| 108 | +# This will get documented as: |
| 109 | +# |
| 110 | +# fred() { |line, address| ... } |
| 111 | +# |
| 112 | +# You can override this using a comment containing ':yields: ...' immediately |
| 113 | +# after the method definition |
| 114 | +# |
| 115 | +# def fred # :yields: index, position |
| 116 | +# # ... |
| 117 | +# |
| 118 | +# yield line, address |
| 119 | +# |
| 120 | +# which will get documented as |
| 121 | +# |
| 122 | +# fred() { |index, position| ... } |
| 123 | +# |
| 124 | +# +:yields:+ is an example of a documentation directive. These appear |
| 125 | +# immediately after the start of the document element they are modifying. |
| 126 | +# |
| 127 | +# == Directives |
| 128 | +# |
| 129 | +# [+:nodoc:+ / +:nodoc:+ all] |
| 130 | +# Don't include this element in the documentation. For classes |
| 131 | +# and modules, the methods, aliases, constants, and attributes |
| 132 | +# directly within the affected class or module will also be |
| 133 | +# omitted. By default, though, modules and classes within that |
| 134 | +# class of module _will_ be documented. This is turned off by |
| 135 | +# adding the +all+ modifier. |
| 136 | +# |
| 137 | +# module MyModule # :nodoc: |
| 138 | +# class Input |
| 139 | +# end |
| 140 | +# end |
| 141 | +# |
| 142 | +# module OtherModule # :nodoc: all |
| 143 | +# class Output |
| 144 | +# end |
| 145 | +# end |
| 146 | +# |
| 147 | +# In the above code, only class +MyModule::Input+ will be documented. |
| 148 | +# :nodoc: is global across all files the class or module appears in, so use |
| 149 | +# :stopdoc:/:startdoc: to only omit documentation for a particular set of |
| 150 | +# methods, etc. |
| 151 | +# |
| 152 | +# [+:doc:+] |
| 153 | +# Force a method or attribute to be documented even if it wouldn't otherwise |
| 154 | +# be. Useful if, for example, you want to include documentation of a |
| 155 | +# particular private method. |
| 156 | +# |
| 157 | +# [+:notnew:+] |
| 158 | +# Only applicable to the +initialize+ instance method. Normally RDoc |
| 159 | +# assumes that the documentation and parameters for #initialize are |
| 160 | +# actually for the ::new method, and so fakes out a ::new for the class. |
| 161 | +# The :notnew: modifier stops this. Remember that #initialize is protected, |
| 162 | +# so you won't see the documentation unless you use the -a command line |
| 163 | +# option. |
| 164 | +# |
| 165 | +# Comment blocks can contain other directives: |
| 166 | +# |
| 167 | +# [<tt>:section: title</tt>] |
| 168 | +# Starts a new section in the output. The title following +:section:+ is |
| 169 | +# used as the section heading, and the remainder of the comment containing |
| 170 | +# the section is used as introductory text. Subsequent methods, aliases, |
| 171 | +# attributes, and classes will be documented in this section. A :section: |
| 172 | +# comment block may have one or more lines before the :section: directive. |
| 173 | +# These will be removed, and any identical lines at the end of the block are |
| 174 | +# also removed. This allows you to add visual cues such as: |
| 175 | +# |
| 176 | +# # ---------------------------------------- |
| 177 | +# # :section: My Section |
| 178 | +# # This is the section that I wrote. |
| 179 | +# # See it glisten in the noon-day sun. |
| 180 | +# # ---------------------------------------- |
| 181 | +# |
| 182 | +# [+:call-seq:+] |
| 183 | +# Lines up to the next blank line in the comment are treated as the method's |
| 184 | +# calling sequence, overriding the default parsing of method parameters and |
| 185 | +# yield arguments. |
| 186 | +# |
| 187 | +# [+:include:+ _filename_] |
| 188 | +# \Include the contents of the named file at this point. The file will be |
| 189 | +# searched for in the directories listed by the +--include+ option, or in |
| 190 | +# the current directory by default. The contents of the file will be |
| 191 | +# shifted to have the same indentation as the ':' at the start of the |
| 192 | +# :include: directive. |
| 193 | +# |
| 194 | +# [+:title:+ _text_] |
| 195 | +# Sets the title for the document. Equivalent to the <tt>--title</tt> |
| 196 | +# command line parameter. (The command line parameter overrides any :title: |
| 197 | +# directive in the source). |
| 198 | +# |
| 199 | +# [+:enddoc:+] |
| 200 | +# Document nothing further at the current level. |
| 201 | +# |
| 202 | +# [+:main:+ _name_] |
| 203 | +# Equivalent to the <tt>--main</tt> command line parameter. |
| 204 | +# |
| 205 | +# [+:stopdoc:+ / +:startdoc:+] |
| 206 | +# Stop and start adding new documentation elements to the current container. |
| 207 | +# For example, if a class has a number of constants that you don't want to |
| 208 | +# document, put a +:stopdoc:+ before the first, and a +:startdoc:+ after the |
| 209 | +# last. If you don't specifiy a +:startdoc:+ by the end of the container, |
| 210 | +# disables documentation for the entire class or module. |
| 211 | +# |
| 212 | +# = Other stuff |
| 213 | +# |
| 214 | +# RDoc is currently being maintained by Eric Hodel <[email protected]> |
| 215 | +# |
| 216 | +# Dave Thomas <[email protected]> is the original author of RDoc. |
| 217 | +# |
| 218 | +# == Credits |
| 219 | +# |
| 220 | +# * The Ruby parser in rdoc/parse.rb is based heavily on the outstanding |
| 221 | +# work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby |
| 222 | +# parser for irb and the rtags package. |
| 223 | +# |
| 224 | +# * Code to diagram classes and modules was written by Sergey A Yanovitsky |
| 225 | +# (Jah) of Enticla. |
| 226 | +# |
| 227 | +# * Charset patch from MoonWolf. |
| 228 | +# |
| 229 | +# * Rich Kilmer wrote the kilmer.rb output template. |
| 230 | +# |
| 231 | +# * Dan Brickley led the design of the RDF format. |
| 232 | +# |
| 233 | +# == License |
| 234 | +# |
| 235 | +# RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It |
| 236 | +# is free software, and may be redistributed under the terms specified |
| 237 | +# in the README file of the Ruby distribution. |
| 238 | +# |
| 239 | +# == Warranty |
| 240 | +# |
| 241 | +# This software is provided "as is" and without any express or implied |
| 242 | +# warranties, including, without limitation, the implied warranties of |
| 243 | +# merchantibility and fitness for a particular purpose. |
5 | 244 |
|
6 | 245 | module RDoc |
7 | 246 |
|
|
0 commit comments