* lib/rdoc*: Updated to RDoc 4.0 (pre-release)

* bin/rdoc:  ditto
* test/rdoc:  ditto
* NEWS:  Updated with RDoc 4.0 information


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37889 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

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 <[email protected]>.
 #
 # Dave Thomas <[email protected]> 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