1
= RDOC - Ruby Documentation System
3
This package contains Rdoc and SimpleMarkup. Rdoc is an application
4
that produces documentation for one or more Ruby source files. We work
5
similarly to JavaDoc, parsing the source, and extracting the
6
definition for classes, modules, and methods (along with includes and
7
requires). We associate with these optional documentation contained
8
in the immediately preceding comment block, and then render the result
9
using a pluggable output formatter. (Currently, HTML is the only
10
supported format. Markup is a library that converts plain text into
11
various output formats. The Markup library is used to interpret the
12
comment blocks that Rdoc uses to document methods, classes, and so on.
14
This library contains two packages, rdoc itself and a text markup
19
* If you want to use Rdoc to create documentation for your Ruby source
21
* If you want to include extensions written in C, see rdoc/parsers/parse_c.rb.
22
* For information on the various markups available in comment
23
blocks, see markup/simple_markup.rb.
24
* If you want to drive Rdoc programatically, see RDoc::RDoc.
25
* If you want to use the library to format text blocks into HTML,
26
have a look at SM::SimpleMarkup.
27
* If you want to try writing your own HTML output template, see
32
Once installed, you can create documentation using the 'rdoc' command
33
(the command is 'rdoc.bat' under Windows)
35
% rdoc [options] [names...]
37
Type "rdoc --help" for an up-to-date option summary.
39
A typical use might be to generate documentation for a package of Ruby
40
source (such as rdoc itself).
44
This command generates documentation for all the Ruby and C source
45
files in and below the current directory. These will be stored in a
46
documentation tree starting in the subdirectory 'doc'.
48
You can make this slightly more useful for your readers by having the
49
index page contain the documentation for the primary file. In our
52
% rdoc --main rdoc/rdoc.rb
54
You'll find information on the various formatting tricks you can use
55
in comment blocks in the documentation this generates.
57
RDoc uses file extensions to determine how to process each file. File
58
names ending <tt>.rb</tt> and <tt>.rbw</tt> are assumed to be Ruby
59
source. Files ending <tt>.c</tt> are parsed as C files. All other
60
files are assumed to contain just SimpleMarkup-style markup (with or
61
without leading '#' comment markers). If directory names are passed to
62
RDoc, they are scanned recursively for C and Ruby source files only.
66
* The Ruby parser in rdoc/parse.rb is based heavily on the outstanding
67
work of Keiju ISHITSUKA of Nippon Rational Inc, who produced the Ruby
68
parser for irb and the rtags package.
70
* Code to diagram classes and modules was written by Sergey A Yanovitsky
73
* Charset patch from MoonWolf.
75
* Rich Kilmer wrote the kilmer.rb output template.
77
* Dan Brickley led the design of the RDF format.
81
RDoc is Copyright (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. It
82
is free software, and may be redistributed under the terms specified
83
in the README file of the Ruby distribution.
87
RDoc is invoked from the command line using:
89
% rdoc <options> [name...]
91
Files are parsed, and the information they contain collected, before
92
any output is produced. This allows cross references between all files
93
to be resolved. If a name is a directory, it is traversed. If no
94
names are specified, all Ruby files in the current directory (and
95
subdirectories) are processed.
99
[<tt>--accessor</tt> <i>name[,name...]</i>]
100
specifies the name(s) of additional methods that should be treated
101
as if they were <tt>attr_</tt><i>xxx</i> methods. Specifying
102
"--accessor db_opt" means lines such as
106
will get parsed and displayed in the documentation. Each name may have an
107
optional "=flagtext" appended, in which case the given flagtext will appear
108
where (for example) the 'rw' appears for attr_accessor.
111
include protected and private methods in the output (by default
112
only public methods are included)
114
[<tt>--charset</tt> _charset_]
115
Set the character set for the generated HTML.
118
include diagrams showing modules and classes. This is currently
119
an experimental feature, and may not be supported by all output
120
templates. You need dot V1.8.6 or later to use the --diagram
121
option correctly (http://www.research.att.com/sw/tools/graphviz/).
123
[<tt>--exclude</tt> <i>pattern</i>]
124
exclude files and directories matching this pattern from processing
126
[<tt>--extension</tt> <i>new=old</i>]
127
treat files ending <i>.new</i> as if they ended
128
<i>.old</i>. Saying '--extension cgi=rb' causes RDoc to treat .cgi
129
files as Ruby source.
132
Classes are put in boxes which represents files, where these
133
classes reside. Classes shared between more than one file are
134
shown with list of files that sharing them. Silently discarded if
135
--diagram is not given Experimental.
137
[<tt>--fmt</tt> _fmt_]
138
generate output in a particular format.
141
generate a usage summary.
143
[<tt>--help-output</tt>]
144
explain the various output options.
146
[<tt>--image-format</tt> <i>gif/png/jpg/jpeg</i>]
147
sets output image format for diagrams. Can be png, gif, jpeg,
148
jpg. If this option is omitted, png is used. Requires --diagram.
150
[<tt>--include</tt> <i>dir,...</i>]
151
specify one or more directories to be searched when satisfying
152
:+include+: directives. Multiple <tt>--include</tt> options may be
153
given. The directory containing the file currently being processed
156
[<tt>--inline-source</tt>]
157
By default, the source code of methods is shown in a popup. With
158
this option, it's displayed inline.
160
[<tt>line-numbers</tt>]
161
include line numbers in the source code
163
[<tt>--main</tt> _name_]
164
the class of module _name_ will appear on the index page. If you
165
want to set a particular file as a main page (a README, for
166
example) simply specifiy its name as the first on the command
170
when generating _ri_ output, if classes being processed already
171
exist in the destination directory, merge in the current details
172
rather than overwrite them.
174
[<tt>--one-file</tt>]
175
place all the output into a single file
177
[<tt>--op</tt> _dir_]
178
set the output directory to _dir_ (the default is the directory
181
[<tt>--op-name</tt> _name_]
182
set the name of the output. Has no effect for HTML.
185
[<tt>--opname</tt> _name_]
186
set the output name (has no effect for HTML).
188
[<tt>--promiscuous</tt>]
189
If a module or class is defined in more than one source file, and
190
you click on a particular file's name in the top navigation pane,
191
RDoc will normally only show you the inner classes and modules of
192
that class that are defined in the particular file. Using this
193
option makes it show all classes and modules defined in the class,
194
regardless of the file they were defined in.
197
do not display progress messages
199
[<tt>--ri</tt>, <tt>--ri-site</tt>, _and_ <tt>--ri-system</tt>]
200
generate output than can be read by the _ri_ command-line tool.
201
By default --ri places its output in ~/.rdoc, --ri-site in
202
$datadir/ri/<ver>/site, and --ri-system in
203
$datadir/ri/<ver>/system. All can be overridden with a subsequent
204
--op option. All default directories are in ri's default search
207
[<tt>--show-hash</tt>]
208
A name of the form #name in a comment is a possible hyperlink to
209
an instance method name. When displayed, the '#' is removed unless
210
this option is specified
212
[<tt>--style</tt> <i>stylesheet url</i>]
213
specifies the URL of an external stylesheet to use (rather than
214
generating one of our own)
216
[<tt>tab-width</tt> _n_]
217
set the width of tab characters (default 8)
219
[<tt>--template</tt> <i>name</i>]
220
specify an alternate template to use when generating output (the
221
default is 'standard'). This template should be in a directory
222
accessible via $: as rdoc/generators/xxxx_template, where 'xxxx'
223
depends on the output formatter.
226
display RDoc's version
228
[<tt>--webcvs</tt> _url_]
229
Specify a URL for linking to a web frontend to CVS. If the URL
230
contains a '\%s', the name of the current file will be
231
substituted; if the URL doesn't contain a '\%s', the filename will
236
A typical small Ruby program commented using RDoc might be as follows. You
237
can see the formatted result in EXAMPLE.rb and Anagram.
243
Comment blocks can be written fairly naturally, either using '#' on
244
successive lines of the comment, or by including the comment in
245
an =begin/=end block. If you use the latter form, the =begin line
246
must be flagged with an RDoc tag:
250
be processed by RDoc.
253
Paragraphs are lines that share the left margin. Text indented past
254
this margin are formatted verbatim.
256
1. Lists are typed as indented paragraphs with:
257
* a '*' or '-' (for bullet lists)
258
* a digit followed by a period for
260
* an upper or lower case letter followed
261
by a period for alpha lists.
263
For example, the input that produced the above paragraph looked like
264
1. Lists are typed as indented
266
* a '*' or '-' (for bullet lists)
267
* a digit followed by a period for
269
* an upper or lower case letter followed
270
by a period for alpha lists.
272
2. Labeled lists (sometimes called description
273
lists) are typed using square brackets for the label.
274
[cat] small domestic animal
275
[+cat+] command to copy standard input
277
3. Labeled lists may also be produced by putting a double colon
278
after the label. This sets the result in tabular form, so the
279
descriptions all line up. This was used to create the 'author'
280
block at the bottom of this description.
281
cat:: small domestic animal
282
+cat+:: command to copy standard input
284
For both kinds of labeled lists, if the body text starts on the same
285
line as the label, then the start of that text determines the block
286
indent for the rest of the body. The text may also start on the line
287
following the label, indented from the start of the label. This is
288
often preferable if the label is long. Both the following are
289
valid labeled list entries:
291
<tt>--output</tt> <i>name [, name]</i>::
292
specify the name of one or more output files. If multiple
293
files are present, the first is used as the index.
295
<tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
296
index areas, or bit ratios of units as
299
4. Headings are entered using equals signs
305
5. Rules (horizontal lines) are entered using three or
308
6. Non-verbatim text can be marked up:
310
_italic_:: \_word_ or \<em>text</em>
311
*bold*:: \*word* or \<b>text</b>
312
+typewriter+:: \+word+ or \<tt>text</tt>
314
The first form only works around 'words', where a word is a
315
sequence of upper and lower case letters and underscores. Putting a
316
backslash before inline markup stops it being interpreted, which is
317
how I created the table above:
319
_italic_:: \_word_ or \<em>text</em>
320
*bold*:: \*word* or \<b>text</b>
321
+typewriter+:: \+word+ or \<tt>text</tt>
323
7. Names of classes, source files, and any method names
324
containing an underscore or preceded by a hash
325
character are automatically hyperlinked from
326
comment text to their description.
328
8. Hyperlinks to the web starting http:, mailto:, ftp:, or www. are
329
recognized. An HTTP url that references an external image file is
330
converted into an inline <IMG..>. Hyperlinks starting 'link:' are
331
assumed to refer to local files whose path is relative to the --op
334
Hyperlinks can also be of the form <tt>label</tt>[url], in which
335
case the label is used in the displayed text, and <tt>url</tt> is
336
used as the target. If <tt>label</tt> contains multiple words,
337
put it in braces: <em>{multi word label}[</em>url<em>]</em>.
339
9. Method parameter lists are extracted and displayed with
340
the method description. If a method calls +yield+, then
341
the parameters passed to yield will also be displayed:
347
This will get documented as
349
fred() { |line, address| ... }
351
You can override this using a comment containing
352
':yields: ...' immediately after the method definition
354
def fred # :yields: index, position
358
which will get documented as
360
fred() { |index, position| ... }
363
10. ':yields:' is an example of a documentation modifier. These appear
364
immediately after the start of the document element they are modifying.
365
Other modifiers include
367
[<tt>:nodoc:</tt><i>[all]</i>]
368
don't include this element in the documentation. For classes
369
and modules, the methods, aliases, constants, and attributes
370
directly within the affected class or module will also be
371
omitted. By default, though, modules and classes within that
372
class of module _will_ be documented. This is turned off by
373
adding the +all+ modifier.
379
module Markup #:nodoc: all
384
In the above code, only class <tt>SM::Input</tt> will be
388
force a method or attribute to be documented even if it
389
wouldn't otherwise be. Useful if, for example, you want to
390
include documentation of a particular private method.
393
only applicable to the +initialize+ instance method. Normally
394
RDoc assumes that the documentation and parameters for
395
#initialize are actually for the ::new method, and so fakes
396
out a ::new for the class. THe :notnew: modifier stops
397
this. Remember that #initialize is protected, so you won't
398
see the documentation unless you use the -a command line
402
11. RDoc stops processing comments if it finds a comment
403
line containing '<tt>#--</tt>'. This can be used to
404
separate external from internal comments, or
405
to stop a comment being associated with a method,
406
class, or module. Commenting can be turned back on with
407
a line that starts '<tt>#++</tt>'.
409
# Extract the age and calculate the
412
# FIXME: fails if the birthday falls on
415
# The DOB is returned as a Time object.
420
12. Comment blocks can contain other directives:
422
[<tt>:section: title</tt>]
423
Starts a new section in the output. The title following
424
<tt>:section:</tt> is used as the section heading, and the
425
remainder of the comment containing the section is used as
426
introductory text. Subsequent methods, aliases, attributes,
427
and classes will be documented in this section. A :section:
428
comment block may have one or more lines before the :section:
429
directive. These will be removed, and any identical lines at
430
the end of the block are also removed. This allows you to add
433
# ----------------------------------------
434
# :section: My Section
435
# This is the section that I wrote.
436
# See it glisten in the noon-day sun.
437
# ----------------------------------------
440
lines up to the next blank line in the comment are treated as
441
the method's calling sequence, overriding the
442
default parsing of method parameters and yield arguments.
444
[<tt>:include:</tt><i>filename</i>]
445
include the contents of the named file at this point. The
446
file will be searched for in the directories listed by
447
the <tt>--include</tt> option, or in the current
448
directory by default. The contents of the file will be
449
shifted to have the same indentation as the ':' at the
450
start of the :include: directive.
452
[<tt>:title:</tt><i>text</i>]
453
Sets the title for the document. Equivalent to the --title command
454
line parameter. (The command line parameter overrides any :title:
455
directive in the source).
458
Document nothing further at the current level.
460
[<tt>:main:</tt><i>name</i>]
461
Equivalent to the --main command line parameter.
463
[<tt>:stopdoc: / :startdoc:</tt>]
464
Stop and start adding new documentation elements to the
465
current container. For example, if a class has a number of
466
constants that you don't want to document, put a
467
<tt>:stopdoc:</tt> before the first, and a
468
<tt>:startdoc:</tt> after the last. If you don't specifiy a
469
<tt>:startdoc:</tt> by the end of the container, disables
470
documentation for the entire class or module.
475
See also markup/simple_markup.rb.
479
Author:: Dave Thomas <dave@pragmaticprogrammer.com>
480
Requires:: Ruby 1.8.1 or later
481
License:: Copyright (c) 2001-2003 Dave Thomas.
482
Released under the same license as Ruby.
486
This software is provided "as is" and without any express or
487
implied warranties, including, without limitation, the implied
488
warranties of merchantibility and fitness for a particular
added
removed
lib/rdoc/README
