rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/markup/to_rdoc.rb

@@ -42,7 +42,7 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # Creates a new formatter that will output (mostly) \RDoc markup
 
   def initialize markup = nil
-    super
+    super nil, markup
 
     @markup.add_special(/\\\S/, :SUPPRESSED_CROSSREF)
     @width = 78
@@ -57,6 +57,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @headings[4] = ['==== ',   '']
     @headings[5] = ['===== ',  '']
     @headings[6] = ['====== ', '']
+
+    @hard_break = "\n"
   end
 
   ##
@@ -75,6 +77,21 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     @res << "\n"
   end
 
+  ##
+  # Adds +paragraph+ to the output
+
+  def accept_block_quote block_quote
+    @indent += 2
+
+    block_quote.parts.each do |part|
+      @prefix = '> '
+
+      part.accept self
+    end
+
+    @indent -= 2
+  end
+
   ##
   # Adds +heading+ to the output
 
@@ -127,10 +144,15 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
 
     case type
     when :NOTE, :LABEL then
-      bullet = attributes(list_item.label).strip + ":\n"
+      bullets = Array(list_item.label).map do |label|
+        attributes(label).strip
+      end.join "\n"
+
+      bullets << ":\n" unless bullets.empty?
+
       @prefix = ' ' * @indent
       @indent += 2
-      @prefix << bullet + (' ' * @indent)
+      @prefix << bullets + (' ' * @indent)
     else
       bullet = type == :BULLET ? '*' :  @list_index.last.to_s + '.'
       @prefix = (' ' * @indent) + bullet.ljust(bullet.length + 1)
@@ -170,7 +192,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
   # Adds +paragraph+ to the output
 
   def accept_paragraph paragraph
-    wrap attributes(paragraph.text)
+    text = paragraph.text @hard_break
+    wrap attributes text
   end
 
   ##
@@ -178,7 +201,8 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
 
   def accept_indented_paragraph paragraph
     @indent += paragraph.indent
-    wrap attributes(paragraph.text)
+    text = paragraph.text @hard_break
+    wrap attributes text
     @indent -= paragraph.indent
   end
 
@@ -236,6 +260,13 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     text
   end
 
+  ##
+  # Adds a newline to the output
+
+  def handle_special_HARD_BREAK special
+    "\n"
+  end
+
   ##
   # Prepares the visitor for text generation
 

data/lib/rdoc/markup/to_table_of_contents.rb

@@ -7,7 +7,7 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
   @to_toc = nil
 
   ##
-  # Singleton for ToC generation
+  # Singleton for table-of-contents generation
 
   def self.to_toc
     @to_toc ||= new
@@ -18,6 +18,10 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
 
   attr_reader :res
 
+  def initialize # :nodoc:
+    super nil
+  end
+
   ##
   # Adds +heading+ to the table of contents
 
@@ -40,6 +44,7 @@ class RDoc::Markup::ToTableOfContents < RDoc::Markup::Formatter
   end
 
   # :stopdoc:
+  alias accept_block_quote     ignore
   alias accept_raw             ignore
   alias accept_rule            ignore
   alias accept_blank_line      ignore

data/lib/rdoc/markup/to_tt_only.rb

@@ -18,11 +18,18 @@ class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
   # Creates a new tt-only formatter.
 
   def initialize markup = nil
-    super
+    super nil, markup
 
     add_tag :TT, nil, nil
   end
 
+  ##
+  # Adds tts from +block_quote+ to the output
+
+  def accept_block_quote block_quote
+    tt_sections block_quote.text
+  end
+
   ##
   # Pops the list type for +list+ from #list_type
 
@@ -43,7 +50,9 @@ class RDoc::Markup::ToTtOnly < RDoc::Markup::Formatter
   def accept_list_item_start list_item
     case @list_type.last
     when :NOTE, :LABEL then
-      tt_sections(list_item.label)
+      Array(list_item.label).map do |label|
+        tt_sections label
+      end.flatten
     end
   end
 

data/lib/rdoc/markup/verbatim.rb

@@ -14,6 +14,10 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
     @format = nil
   end
 
+  def == other # :nodoc:
+    super and @format == other.format
+  end
+
   ##
   # Calls #accept_verbatim on +visitor+
 
@@ -45,6 +49,21 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
     @parts = parts
   end
 
+  def pretty_print q # :nodoc:
+    self.class.name =~ /.*::(\w{1,4})/i
+
+    q.group 2, "[#{$1.downcase}: ", ']' do
+      if @format then
+        q.text "format: #{@format}"
+        q.breakable
+      end
+
+      q.seplist @parts do |part|
+        q.pp part
+      end
+    end
+  end
+
   ##
   # Is this verbatim section ruby code?
 

data/lib/rdoc/method_attr.rb

@@ -98,7 +98,12 @@ class RDoc::MethodAttr < RDoc::CodeObject
   # Order by #singleton then #name
 
   def <=>(other)
-    [@singleton ? 0 : 1, name] <=> [other.singleton ? 0 : 1, other.name]
+    [     @singleton ? 0 : 1,       name] <=>
+    [other.singleton ? 0 : 1, other.name]
+  end
+
+  def == other # :nodoc:
+    super or self.class == other.class and full_name == other.full_name
   end
 
   ##
@@ -133,6 +138,15 @@ class RDoc::MethodAttr < RDoc::CodeObject
     @see
   end
 
+  ##
+  # Sets the store for this class or module and its contained code objects.
+
+  def store= store
+    super
+
+    @file = @store.add_file @file.full_name if @file
+  end
+
   def find_see # :nodoc:
     return nil if singleton || is_alias_for
 
@@ -149,7 +163,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
     return nil unless parent.respond_to? :ancestors
 
     searched = parent.ancestors
-    kernel = RDoc::TopLevel.all_modules_hash['Kernel']
+    kernel = @store.modules_hash['Kernel']
 
     searched << kernel if kernel &&
       parent != kernel && !searched.include?(kernel)
@@ -171,10 +185,10 @@ class RDoc::MethodAttr < RDoc::CodeObject
   # Abstract method. Contexts in their building phase call this
   # to register a new alias for this known method/attribute.
   #
-  # - creates a new AnyMethod/Attribute +newa+ named an_alias.new_name;
-  # - adds +self+ as +newa.is_alias_for+;
-  # - adds +newa+ to #aliases
-  # - adds +newa+ to the methods/attributes of +context+.
+  # - creates a new AnyMethod/Attribute named <tt>an_alias.new_name</tt>;
+  # - adds +self+ as an alias for the new method or attribute
+  # - adds the method or attribute to #aliases
+  # - adds the method or attribute to +context+.
 
   def add_alias(an_alias, context)
     raise NotImplementedError
@@ -271,6 +285,18 @@ class RDoc::MethodAttr < RDoc::CodeObject
     @full_name ||= "#{parent_name}#{pretty_name}"
   end
 
+  def inspect # :nodoc:
+    alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
+    visibility = self.visibility
+    visibility = "forced #{visibility}" if force_documentation
+    "#<%s:0x%x %s (%s)%s>" % [
+      self.class, object_id,
+      full_name,
+      visibility,
+      alias_for,
+    ]
+  end
+
   ##
   # '::' for a class method/attribute, '#' for an instance method.
 
@@ -306,7 +332,7 @@ class RDoc::MethodAttr < RDoc::CodeObject
   end
 
   ##
-  # Path to this method
+  # Path to this method for use with HTML generator output.
 
   def path
     "#{@parent.path}##{aref}"
@@ -344,18 +370,6 @@ class RDoc::MethodAttr < RDoc::CodeObject
     end
   end
 
-  def inspect # :nodoc:
-    alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
-    visibility = self.visibility
-    visibility = "forced #{visibility}" if force_documentation
-    "#<%s:0x%x %s (%s)%s>" % [
-      self.class, object_id,
-      full_name,
-      visibility,
-      alias_for,
-    ]
-  end
-
   ##
   # Used by RDoc::Generator::JsonIndex to create a record for the search
   # engine.

data/lib/rdoc/normal_class.rb

@@ -4,10 +4,20 @@
 class RDoc::NormalClass < RDoc::ClassModule
 
   ##
-  # Appends the superclass, if any, to the included modules.
+  # The ancestors of this class including modules.  Unlike Module#ancestors,
+  # this class is not included in the result.  The result will contain both
+  # RDoc::ClassModules and Strings.
 
   def ancestors
-    superclass ? super + [superclass] : super
+    if String === superclass then
+      super << superclass
+    elsif superclass then
+      ancestors = super
+      ancestors << superclass
+      ancestors.concat superclass.ancestors
+    else
+      super
+    end
   end
 
   ##
@@ -17,11 +27,15 @@ class RDoc::NormalClass < RDoc::ClassModule
     "class #{full_name}"
   end
 
+  def direct_ancestors
+    superclass ? super + [superclass] : super
+  end
+
   def inspect # :nodoc:
     superclass = @superclass ? " < #{@superclass}" : nil
-    "<%s:0x%x class %s%s includes: %p attributes: %p methods: %p aliases: %p>" % [
+    "<%s:0x%x class %s%s includes: %p extends: %p attributes: %p methods: %p aliases: %p>" % [
       self.class, object_id,
-      full_name, superclass, @includes, @attributes, @method_list, @aliases
+      full_name, superclass, @includes, @extends, @attributes, @method_list, @aliases
     ]
   end
 
@@ -43,20 +57,25 @@ class RDoc::NormalClass < RDoc::ClassModule
       q.breakable
       q.seplist @includes do |inc| q.pp inc end
 
+      q.breakable
+      q.text "constants:"
+      q.breakable
+      q.seplist @constants do |const| q.pp const end
+
       q.breakable
       q.text "attributes:"
       q.breakable
-      q.seplist @attributes do |inc| q.pp inc end
+      q.seplist @attributes do |attr| q.pp attr end
 
       q.breakable
       q.text "methods:"
       q.breakable
-      q.seplist @method_list do |inc| q.pp inc end
+      q.seplist @method_list do |meth| q.pp meth end
 
       q.breakable
       q.text "aliases:"
       q.breakable
-      q.seplist @aliases do |inc| q.pp inc end
+      q.seplist @aliases do |aliaz| q.pp aliaz end
 
       q.breakable
       q.text "comment:"

data/lib/rdoc/normal_module.rb

@@ -4,9 +4,9 @@
 class RDoc::NormalModule < RDoc::ClassModule
 
   def inspect # :nodoc:
-    "#<%s:0x%x module %s includes: %p attributes: %p methods: %p aliases: %p>" % [
+    "#<%s:0x%x module %s includes: %p extends: %p attributes: %p methods: %p aliases: %p>" % [
       self.class, object_id,
-      full_name, @includes, @attributes, @method_list, @aliases
+      full_name, @includes, @extends, @attributes, @method_list, @aliases
     ]
   end
 
@@ -32,19 +32,24 @@ class RDoc::NormalModule < RDoc::ClassModule
       q.seplist @includes do |inc| q.pp inc end
       q.breakable
 
+      q.breakable
+      q.text "constants:"
+      q.breakable
+      q.seplist @constants do |const| q.pp const end
+
       q.text "attributes:"
       q.breakable
-      q.seplist @attributes do |inc| q.pp inc end
+      q.seplist @attributes do |attr| q.pp attr end
       q.breakable
 
       q.text "methods:"
       q.breakable
-      q.seplist @method_list do |inc| q.pp inc end
+      q.seplist @method_list do |meth| q.pp meth end
       q.breakable
 
       q.text "aliases:"
       q.breakable
-      q.seplist @aliases do |inc| q.pp inc end
+      q.seplist @aliases do |aliaz| q.pp aliaz end
       q.breakable
 
       q.text "comment:"

data/lib/rdoc/options.rb

@@ -1,4 +1,5 @@
 require 'optparse'
+require 'pathname'
 
 ##
 # RDoc::Options handles the parsing and storage of options
@@ -25,6 +26,38 @@ require 'optparse'
 # * +--quiet+
 # * +--template+
 # * +--verbose+
+#
+# == Custom Options
+#
+# Generators can hook into RDoc::Options to add generator-specific command
+# line options.
+#
+# When <tt>--format</tt> is encountered in ARGV, RDoc calls ::setup_options on
+# the generator class to add extra options to the option parser.  Options for
+# custom generators must occur after <tt>--format</tt>.  <tt>rdoc --help</tt>
+# will list options for all installed generators.
+#
+# Example:
+#
+#   class RDoc::Generator::Spellcheck
+#     RDoc::RDoc.add_generator self
+#
+#     def self.setup_options rdoc_options
+#       op = rdoc_options.option_parser
+#
+#       op.on('--spell-dictionary DICTIONARY',
+#             RDoc::Options::Path) do |dictionary|
+#         rdoc_options.spell_dictionary = dictionary
+#       end
+#     end
+#   end
+#
+# == Option Validators
+#
+# OptionParser validators will validate and cast user input values.  In
+# addition to the validators that ship with OptionParser (String, Integer,
+# Float, TrueClass, FalseClass, Array, Regexp, Date, Time, URI, etc.),
+# RDoc::Options adds Path, PathArray and Template.
 
 class RDoc::Options
 
@@ -63,6 +96,7 @@ class RDoc::Options
     option_parser
     pipe
     rdoc_include
+    root
     static_path
     stylesheet_url
     template
@@ -73,17 +107,27 @@ class RDoc::Options
   ]
 
   ##
-  # Path option validator for OptionParser
+  # Option validator for OptionParser that matches a directory that exists on
+  # the filesystem.
+
+  Directory = Object.new
+
+  ##
+  # Option validator for OptionParser that matches a file or directory that
+  # exists on the filesystem.
 
   Path = Object.new
 
   ##
-  # Array of Paths option validator for OptionParser
+  # Option validator for OptionParser that matches a comma-separated list of
+  # files or directories that exist on the filesystem.
 
   PathArray = Object.new
 
   ##
-  # Template option validator for OptionParser
+  # Option validator for OptionParser that matches a template directory for an
+  # installed generator that lives in
+  # <tt>"rdoc/generator/template/#{template_name}"</tt>
 
   Template = Object.new
 
@@ -98,7 +142,9 @@ class RDoc::Options
   attr_accessor :dry_run
 
   ##
-  # Encoding of output where.  This is set via --encoding.
+  # The output encoding.  All input files will be transcoded to this encoding.
+  #
+  # The default encoding is UTF-8.  This is set via --encoding.
 
   attr_accessor :encoding
 
@@ -129,7 +175,7 @@ class RDoc::Options
   attr_accessor :formatter
 
   ##
-  # Description of the output generator (set with the <tt>--fmt</tt> option)
+  # Description of the output generator (set with the <tt>--format</tt> option)
 
   attr_accessor :generator
 
@@ -162,8 +208,8 @@ class RDoc::Options
   attr_accessor :main_page
 
   ##
-  # The default markup format.  The default is 'rdoc'.  'tomdoc' and 'rd' are
-  # also built-in.
+  # The default markup format.  The default is 'rdoc'.  'markdown', 'tomdoc'
+  # and 'rd' are also built-in.
 
   attr_accessor :markup
 
@@ -192,6 +238,13 @@ class RDoc::Options
 
   attr_accessor :rdoc_include
 
+  ##
+  # Root of the source documentation will be generated for.  Set this when
+  # building documentation outside the source directory.  Defaults to the
+  # current directory.
+
+  attr_accessor :root
+
   ##
   # Include the '#' at the front of hyperlinked instance method names
 
@@ -266,6 +319,7 @@ class RDoc::Options
     @op_dir = nil
     @pipe = false
     @rdoc_include = []
+    @root = Pathname(Dir.pwd)
     @show_hash = false
     @static_path = []
     @stylesheet_url = nil # TODO remove in RDoc 4
@@ -280,8 +334,8 @@ class RDoc::Options
     @write_options = false
 
     if Object.const_defined? :Encoding then
-      @encoding = Encoding.default_external
-      @charset = @encoding.to_s
+      @encoding = Encoding::UTF_8
+      @charset = @encoding.name
     else
       @encoding = nil
       @charset = 'UTF-8'
@@ -524,25 +578,33 @@ Usage: #{opt.program_name} [options] [names...]
         end
       end
 
-      opt.accept Path do |directory|
+      opt.accept Directory do |directory|
         directory = File.expand_path directory
 
-        raise OptionParser::InvalidArgument unless File.exist? directory
+        raise OptionParser::InvalidArgument unless File.directory? directory
 
         directory
       end
 
-      opt.accept PathArray do |directories,|
-        directories = if directories then
-                        directories.split(',').map { |d| d unless d.empty? }
-                      end
+      opt.accept Path do |path|
+        path = File.expand_path path
+
+        raise OptionParser::InvalidArgument unless File.exist? path
+
+        path
+      end
+
+      opt.accept PathArray do |paths,|
+        paths = if paths then
+                  paths.split(',').map { |d| d unless d.empty? }
+                end
 
-        directories.map do |directory|
-          directory = File.expand_path directory
+        paths.map do |path|
+          path = File.expand_path path
 
-          raise OptionParser::InvalidArgument unless File.exist? directory
+          raise OptionParser::InvalidArgument unless File.exist? path
 
-          directory
+          path
         end
       end
 
@@ -554,9 +616,10 @@ Usage: #{opt.program_name} [options] [names...]
         opt.on("--encoding=ENCODING", "-e", Encoding.list.map { |e| e.name },
                "Specifies the output encoding.  All files",
                "read will be converted to this encoding.",
-               "Preferred over --charset") do |value|
+               "The default encoding is UTF-8.",
+               "--encoding is preferred over --charset") do |value|
                  @encoding = Encoding.find value
-                 @charset = @encoding.to_s # may not be valid value
+                 @charset = @encoding.name # may not be valid value
                end
 
         opt.separator nil
@@ -634,6 +697,17 @@ Usage: #{opt.program_name} [options] [names...]
         @markup = value
       end
 
+      opt.separator nil
+
+      opt.on("--root=ROOT", Directory,
+             "Root of the source tree documentation",
+             "will be generated for.  Set this when",
+             "building documentation outside the",
+             "source directory.  Default is the",
+             "current directory.") do |root|
+        @root = Pathname(root)
+      end
+
       opt.separator nil
       opt.separator "Common generator options:"
       opt.separator nil