diff options
Diffstat (limited to 'lib/rdoc.rb')
| -rw-r--r-- | lib/rdoc.rb | 171 |
1 files changed, 103 insertions, 68 deletions
diff --git a/lib/rdoc.rb b/lib/rdoc.rb index aaa1aaa092..5c2df18a0d 100644 --- a/lib/rdoc.rb +++ b/lib/rdoc.rb @@ -1,86 +1,55 @@ $DEBUG_RDOC = nil -# :main: README.txt +# :main: README.rdoc ## -# RDoc is a Ruby documentation system which contains RDoc::RDoc for generating -# documentation, RDoc::RI for interactive documentation and RDoc::Markup for -# text markup. +# RDoc produces documentation for Ruby source files by parsing the source and +# extracting the definition for classes, modules, methods, includes and +# requires. It associates these with optional documentation contained in an +# immediately preceding comment block then renders the result using an output +# formatter. # -# RDoc::RDoc produces documentation for Ruby source files. It works similarly -# to JavaDoc, parsing the source and extracting the definition for classes, -# modules, methods, includes and requires. It associates these with optional -# documentation contained in an immediately preceding comment block then -# renders the result using an output formatter. -# -# RDoc::Markup 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. -# -# RDoc::RI implements the +ri+ command-line tool which displays on-line -# documentation for ruby classes, methods, etc. +ri+ features several output -# formats and an interactive mode (<tt>ri -i</tt>). See <tt>ri --help</tt> -# for further details. +# For a simple introduction to writing or generating documentation using RDoc +# see the README. # # == Roadmap # -# * If you want to use RDoc to create documentation for your Ruby source files, -# see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line -# usage. -# * If you want to write documentation for Ruby files see RDoc::Parser::Ruby -# * If you want to write documentation for extensions written in C see -# RDoc::Parser::C -# * If you want to generate documentation using <tt>rake</tt> see RDoc::Task. -# * If you want to drive RDoc programmatically, see RDoc::RDoc. -# * If you want to use the library to format text blocks into HTML, look at -# RDoc::Markup. -# * If you want to make an RDoc plugin such as a generator or directive -# handler see RDoc::RDoc. -# * If you want to write your own output generator see RDoc::Generator. -# -# == Summary +# If you think you found a bug in RDoc see DEVELOPERS@Bugs # -# Once installed, you can create documentation using the +rdoc+ command +# If you want to use RDoc to create documentation for your Ruby source files, +# see RDoc::Markup and refer to <tt>rdoc --help</tt> for command line usage. # -# % rdoc [options] [names...] +# If you want to set the default markup format see +# RDoc::Markup@Supported+Formats # -# For an up-to-date option summary, type +# If you want to store rdoc configuration in your gem (such as the default +# markup format) see RDoc::Options@Saved+Options # -# % rdoc --help +# If you want to write documentation for Ruby files see RDoc::Parser::Ruby # -# A typical use might be to generate documentation for a package of Ruby -# source (such as RDoc itself). +# If you want to write documentation for extensions written in C see +# RDoc::Parser::C # -# % rdoc +# If you want to generate documentation using <tt>rake</tt> see RDoc::Task. # -# 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+. +# If you want to drive RDoc programmatically, see RDoc::RDoc. # -# 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 +# If you want to use the library to format text blocks into HTML or other +# formats, look at RDoc::Markup. # -# % rdoc --main README.txt +# If you want to make an RDoc plugin such as a generator or directive handler +# see RDoc::RDoc. # -# You'll find information on the various formatting tricks you can use -# in comment blocks in the documentation this generates. +# If you want to write your own output generator see RDoc::Generator. # -# 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. +# If you want an overview of how RDoc works see DEVELOPERS # -# == Other stuff +# == Credits # # 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. @@ -92,19 +61,10 @@ module RDoc class Error < RuntimeError; end - 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 = '3.9.4' + VERSION = '4.0' ## # Method visibilities @@ -143,5 +103,80 @@ module RDoc METHOD_MODIFIERS = GENERAL_MODIFIERS + %w[arg args yield yields notnew not-new not_new doc] + ## + # Loads the best available YAML library. + + def self.load_yaml + begin + gem 'psych' + rescue Gem::LoadError + end + + begin + require 'psych' + rescue ::LoadError + ensure + require 'yaml' + end + end + + autoload :RDoc, 'rdoc/rdoc' + + autoload :TestCase, 'rdoc/test_case' + + autoload :CrossReference, 'rdoc/cross_reference' + autoload :ERBIO, 'rdoc/erbio' + autoload :ERBPartial, 'rdoc/erb_partial' + autoload :Encoding, 'rdoc/encoding' + autoload :Generator, 'rdoc/generator' + autoload :Options, 'rdoc/options' + autoload :Parser, 'rdoc/parser' + autoload :Servlet, 'rdoc/servlet' + autoload :RI, 'rdoc/ri' + autoload :Stats, 'rdoc/stats' + autoload :Store, 'rdoc/store' + autoload :Task, 'rdoc/task' + autoload :Text, 'rdoc/text' + + autoload :Markdown, 'rdoc/markdown' + autoload :Markup, 'rdoc/markup' + autoload :RD, 'rdoc/rd' + autoload :TomDoc, 'rdoc/tom_doc' + + autoload :KNOWN_CLASSES, 'rdoc/known_classes' + + autoload :RubyLex, 'rdoc/ruby_lex' + autoload :RubyToken, 'rdoc/ruby_token' + autoload :TokenStream, 'rdoc/token_stream' + + autoload :Comment, 'rdoc/comment' + + # code objects + # + # We represent the various high-level code constructs that appear in Ruby + # programs: classes, modules, methods, and so on. + autoload :CodeObject, 'rdoc/code_object' + + autoload :Context, 'rdoc/context' + autoload :TopLevel, 'rdoc/top_level' + + autoload :AnonClass, 'rdoc/anon_class' + autoload :ClassModule, 'rdoc/class_module' + autoload :NormalClass, 'rdoc/normal_class' + autoload :NormalModule, 'rdoc/normal_module' + autoload :SingleClass, 'rdoc/single_class' + + autoload :Alias, 'rdoc/alias' + autoload :AnyMethod, 'rdoc/any_method' + autoload :MethodAttr, 'rdoc/method_attr' + autoload :GhostMethod, 'rdoc/ghost_method' + autoload :MetaMethod, 'rdoc/meta_method' + autoload :Attr, 'rdoc/attr' + + autoload :Constant, 'rdoc/constant' + autoload :Include, 'rdoc/include' + autoload :Extend, 'rdoc/extend' + autoload :Require, 'rdoc/require' + end |