diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2010-04-01 07:45:16 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2010-04-01 07:45:16 +0000 |
commit | 46580b51477355fece514573c88cb67030f4a502 (patch) | |
tree | 779c1a64466643461b3daa4cd9a3548b84f0fd55 /lib/rdoc.rb | |
parent | 9b40cdfe8c973a061c5683ad78c283b9ddb8b2e9 (diff) |
Import RDoc 2.5
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27147 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/rdoc.rb')
-rw-r--r-- | lib/rdoc.rb | 100 |
1 files changed, 63 insertions, 37 deletions
diff --git a/lib/rdoc.rb b/lib/rdoc.rb index 043d3420be..fb83932d27 100644 --- a/lib/rdoc.rb +++ b/lib/rdoc.rb @@ -1,5 +1,7 @@ $DEBUG_RDOC = nil +# :main: README.txt + ## # = \RDoc - Ruby Documentation System # @@ -17,7 +19,8 @@ $DEBUG_RDOC = nil # # * 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 generate documentation for 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. @@ -31,6 +34,7 @@ $DEBUG_RDOC = nil # % 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 @@ -59,6 +63,7 @@ $DEBUG_RDOC = nil # 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. @@ -68,35 +73,22 @@ $DEBUG_RDOC = nil # will make rdoc default to inline method source code. Command-line options # always will override those in +RDOCOPT+. # -# Run +# Run: # -# % rdoc --help +# rdoc --help # # for full details on rdoc's options. # -# Here are some of the most commonly used options. -# [-d, --diagram] -# Generate diagrams showing modules and -# classes. You need dot V1.8.6 or later to -# use the --diagram option correctly. Dot is -# available from http://graphviz.org -# -# [-S, --inline-source] -# Show method source code inline, rather than via a popup link. -# -# [-T, --template=NAME] -# Set the template used when generating output. -# # == Documenting Source Code # -# Comment blocks can be written fairly naturally, either using +#+ on +# 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 # @@ -112,7 +104,7 @@ $DEBUG_RDOC = nil # # FIXME: fails if the birthday falls on February 29th # #++ # # The DOB is returned as a Time object. -# +# # def get_dob(person) # # ... # end @@ -138,7 +130,7 @@ $DEBUG_RDOC = nil # # def fred # :yields: index, position # # ... -# +# # yield line, address # # which will get documented as @@ -148,6 +140,11 @@ $DEBUG_RDOC = nil # +: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 @@ -214,17 +211,17 @@ $DEBUG_RDOC = nil # # Word-based markup uses flag characters around individual words: # -# [\*word*] displays word in a *bold* font -# [\_word_] displays word in an _emphasized_ font -# [\+word+] displays word in a +code+ font +# [<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. # -# [\<b>text...</b>] displays word in a *bold* font -# [\<em>text...</em>] displays word in an _emphasized_ font -# [\\<i>text...</i>] displays word in an <i>italicized</i> font -# [\<tt>text...</tt>] displays word in a +code+ font +# [<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 @@ -233,7 +230,7 @@ $DEBUG_RDOC = nil # # * 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 +# converted into an inline \<IMG..>. Hyperlinks starting 'link:' are # assumed to refer to local files whose path is relative to the --op # directory. # @@ -242,6 +239,14 @@ $DEBUG_RDOC = nil # 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] @@ -251,12 +256,12 @@ $DEBUG_RDOC = nil # 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 @@ -290,7 +295,7 @@ $DEBUG_RDOC = nil # 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. @@ -327,6 +332,8 @@ $DEBUG_RDOC = nil # last. If you don't specify a +:startdoc:+ by the end of the container, # disables documentation for the entire class or module. # +# Further directives can be found in RDoc::Parser::Ruby and RDoc::Parser::C +# # == Other stuff # # RDoc is currently being maintained by Eric Hodel <drbrain@segment7.net> @@ -339,9 +346,6 @@ $DEBUG_RDOC = nil # 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. @@ -367,12 +371,19 @@ module RDoc class Error < RuntimeError; end - RDocError = Error # :nodoc: + def self.const_missing const_name # :nodoc: + if const_name.to_s == 'RDocError' then + warn "RDoc::RDocError is deprecated" + return Error + end + + super + end ## # RDoc version you are using - VERSION = "2.2.2" + VERSION = '2.5' ## # Name of the dotfile that contains the description of files to be processed @@ -380,14 +391,29 @@ module RDoc DOT_DOC_FILENAME = ".document" + ## + # General RDoc modifiers + GENERAL_MODIFIERS = %w[nodoc].freeze + ## + # RDoc modifiers for classes + CLASS_MODIFIERS = GENERAL_MODIFIERS - ATTR_MODIFIERS = GENERAL_MODIFIERS + ## + # RDoc modifiers for attributes + + ATTR_MODIFIERS = GENERAL_MODIFIERS + + ## + # RDoc modifiers for constants CONSTANT_MODIFIERS = GENERAL_MODIFIERS + ## + # RDoc modifiers for methods + METHOD_MODIFIERS = GENERAL_MODIFIERS + %w[arg args yield yields notnew not-new not_new doc] |