diff options
Diffstat (limited to 'trunk/lib/rdoc/README')
-rw-r--r-- | trunk/lib/rdoc/README | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/trunk/lib/rdoc/README b/trunk/lib/rdoc/README new file mode 100644 index 0000000000..f183c61f8d --- /dev/null +++ b/trunk/lib/rdoc/README @@ -0,0 +1,232 @@ += 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, +modules, and methods (along with includes and requires). We associate with +these optional documentation contained in the immediately preceding comment +block, and then render 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::C_Parser +* For information on the various markups available in comment blocks, see + RDoc::Markup. +* 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 +(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). + + % 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 '+#--+'. +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 '+#+++'. + + ## + # 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, source 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. + +== Directives + +[+:nodoc:+ / +:nodoc:+ all] + Don't include this element in the documentation. For classes + and modules, the methods, aliases, constants, and attributes + directly within the affected class or module will also 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 +MyModule::Input+ will be documented. + +[+: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 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: + +[+:section: title+] + 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 --title 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 --main 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 + +Author:: Dave Thomas <dave@pragmaticprogrammer.com> + +== 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. + |