rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/task.rb

@@ -128,7 +128,8 @@ class RDoc::Task < Rake::TaskLib
   attr_accessor :template
 
   ##
-  # Name of format generator (--fmt) used by rdoc. (defaults to rdoc's default)
+  # Name of format generator (<tt>--format<tt>) used by rdoc. (defaults to
+  # rdoc's default)
 
   attr_accessor :generator
 

data/lib/rdoc/test_case.rb

@@ -33,12 +33,37 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
 
     @top_level = nil
 
+    @have_encoding = Object.const_defined? :Encoding
+
     @RM = RDoc::Markup
 
-    RDoc::RDoc.reset
     RDoc::Markup::PreProcess.reset
 
     @pwd = Dir.pwd
+
+    @store = RDoc::Store.new
+
+    @rdoc = RDoc::RDoc.new
+    @rdoc.store = @store
+
+    g = Object.new
+    def g.class_dir() end
+    def g.file_dir() end
+    @rdoc.generator = g
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::BlankLine.new
+
+  def blank_line
+    @RM::BlankLine.new
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::BlockQuote.new with +contents+
+
+  def block *contents
+    @RM::BlockQuote.new(*contents)
   end
 
   ##
@@ -49,6 +74,62 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
     RDoc::Comment.new text, top_level
   end
 
+  ##
+  # Shortcut for RDoc::Markup::Document.new with +contents+
+
+  def doc *contents
+    @RM::Document.new(*contents)
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::HardBreak.new
+
+  def hard_break
+    @RM::HardBreak.new
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::Heading.new with +level+ and +text+
+
+  def head level, text
+    @RM::Heading.new level, text
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::ListItem.new with +label+ and +parts+
+
+  def item label = nil, *parts
+    @RM::ListItem.new label, *parts
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::List.new with +type+ and +items+
+
+  def list type = nil, *items
+    @RM::List.new type, *items
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::Paragraph.new with +contents+
+
+  def para *a
+    @RM::Paragraph.new(*a)
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::Rule.new with +weight+
+
+  def rule weight
+    @RM::Rule.new weight
+  end
+
+  ##
+  # Shortcut for RDoc::Markup::Raw.new with +contents+
+
+  def raw *contents
+    @RM::Raw.new(*contents)
+  end
+
   ##
   # Creates a temporary directory changes the current directory to it for the
   # duration of the block.
@@ -65,6 +146,27 @@ class RDoc::TestCase < MiniTest::Unit::TestCase
     end
   end
 
+  ##
+  # Shortcut for RDoc::Markup::Verbatim.new with +parts+
+
+  def verb *parts
+    @RM::Verbatim.new(*parts)
+  end
+
+  ##
+  # run capture_io with setting $VERBOSE = true
+
+  def verbose_capture_io
+    capture_io do
+      begin
+        orig_verbose = $VERBOSE
+        $VERBOSE = true
+        yield
+      ensure
+        $VERBOSE = orig_verbose
+      end
+    end
+  end
 end
 
 # This hack allows autoload to work when Dir.pwd is changed for Ruby 1.8 since

data/lib/rdoc/text.rb

@@ -25,9 +25,10 @@ module RDoc::Text
   # unknown, "rdoc" format is used.
 
   MARKUP_FORMAT = {
-    'rdoc'   => RDoc::Markup,
-    'rd'     => RDoc::RD,
-    'tomdoc' => RDoc::TomDoc,
+    'markdown' => RDoc::Markdown,
+    'rdoc'     => RDoc::Markup,
+    'rd'       => RDoc::RD,
+    'tomdoc'   => RDoc::TomDoc,
   }
 
   MARKUP_FORMAT.default = RDoc::Markup
@@ -67,7 +68,7 @@ module RDoc::Text
     expanded = []
 
     text.each_line do |line|
-      line.gsub!(/^(.{8}*?)([^\t\r\n]{0,7})\t/) do
+      line.gsub!(/^((?:.{8})*?)([^\t\r\n]{0,7})\t/) do
         r = "#{$1}#{$2}#{' ' * (8 - $2.size)}"
         r.force_encoding text.encoding if Object.const_defined? :Encoding
         r

data/lib/rdoc/tom_doc.rb

@@ -10,6 +10,10 @@
 #
 # https://github.com/mojombo/tomdoc/blob/master/tomdoc.md
 #
+# To choose TomDoc as your only default format see RDoc::Options@Saved+Options
+# for instructions on setting up a <code>.rdoc_options</code> file to store
+# your project default.
+#
 # There are a few differences between this parser and the specification.  A
 # best-effort was made to follow the specification as closely as possible but
 # some choices to deviate were made.
@@ -195,33 +199,30 @@ class RDoc::TomDoc < RDoc::Markup::Parser
   def tokenize text
     text.sub!(/\A(Public|Internal|Deprecated):\s+/, '')
 
-    s = StringScanner.new text
-
-    @line = 0
-    @line_pos = 0
+    setup_scanner text
 
-    until s.eos? do
-      pos = s.pos
+    until @s.eos? do
+      pos = @s.pos
 
       # leading spaces will be reflected by the column of the next token
       # the only thing we loose are trailing spaces at the end of the file
-      next if s.scan(/ +/)
+      next if @s.scan(/ +/)
 
       @tokens << case
-                 when s.scan(/\r?\n/) then
-                   token = [:NEWLINE, s.matched, *token_pos(pos)]
-                   @line_pos = s.pos
+                 when @s.scan(/\r?\n/) then
+                   token = [:NEWLINE, @s.matched, *token_pos(pos)]
+                   @line_pos = char_pos @s.pos
                    @line += 1
                    token
-                 when s.scan(/(Examples|Signature)$/) then
+                 when @s.scan(/(Examples|Signature)$/) then
                    @tokens << [:HEADER, 3, *token_pos(pos)]
 
-                   [:TEXT, s[1], *token_pos(pos)]
-                 when s.scan(/([:\w]\w*)[ ]+- /) then
-                   [:NOTE, s[1], *token_pos(pos)]
+                   [:TEXT, @s[1], *token_pos(pos)]
+                 when @s.scan(/([:\w]\w*)[ ]+- /) then
+                   [:NOTE, @s[1], *token_pos(pos)]
                  else
-                   s.scan(/.*/)
-                   [:TEXT, s.matched.sub(/\r$/, ''), *token_pos(pos)]
+                   @s.scan(/.*/)
+                   [:TEXT, @s.matched.sub(/\r$/, ''), *token_pos(pos)]
                  end
     end
 

data/lib/rdoc/top_level.rb

@@ -3,6 +3,8 @@
 
 class RDoc::TopLevel < RDoc::Context
 
+  MARSHAL_VERSION = 0 # :nodoc:
+
   ##
   # This TopLevel's File::Stat struct
 
@@ -33,294 +35,27 @@ class RDoc::TopLevel < RDoc::Context
   attr_accessor :parser
 
   ##
-  # Returns all classes discovered by RDoc
-
-  def self.all_classes
-    @all_classes_hash.values
-  end
-
-  ##
-  # Returns all classes and modules discovered by RDoc
-
-  def self.all_classes_and_modules
-    @all_classes_hash.values + @all_modules_hash.values
-  end
-
-  ##
-  # Hash of all classes known to RDoc
-
-  def self.all_classes_hash
-    @all_classes_hash
-  end
-
-  ##
-  # All TopLevels known to RDoc
-
-  def self.all_files
-    @all_files_hash.values
-  end
-
-  ##
-  # Hash of all files known to RDoc
-
-  def self.all_files_hash
-    @all_files_hash
-  end
-
-  ##
-  # Returns all modules discovered by RDoc
-
-  def self.all_modules
-    all_modules_hash.values
-  end
-
-  ##
-  # Hash of all modules known to RDoc
-
-  def self.all_modules_hash
-    @all_modules_hash
-  end
-
-  ##
-  # Prepares the RDoc code object tree for use by a generator.
-  #
-  # It finds unique classes/modules defined, and replaces classes/modules that
-  # are aliases for another one by a copy with RDoc::ClassModule#is_alias_for
-  # set.
-  #
-  # It updates the RDoc::ClassModule#constant_aliases attribute of "real"
-  # classes or modules.
-  #
-  # It also completely removes the classes and modules that should be removed
-  # from the documentation and the methods that have a visibility below
-  # +min_visibility+, which is the <tt>--visibility</tt> option.
-  #
-  # See also RDoc::Context#remove_from_documentation?
-
-  def self.complete min_visibility
-    fix_basic_object_inheritance
-
-    # cache included modules before they are removed from the documentation
-    all_classes_and_modules.each { |cm| cm.ancestors }
-
-    remove_nodoc @all_classes_hash
-    remove_nodoc @all_modules_hash
-
-    @unique_classes = find_unique @all_classes_hash
-    @unique_modules = find_unique @all_modules_hash
-
-    unique_classes_and_modules.each do |cm|
-      cm.complete min_visibility
-    end
-
-    @all_files_hash.each_key do |file_name|
-      tl = @all_files_hash[file_name]
-
-      unless tl.text? then
-        tl.modules_hash.clear
-        tl.classes_hash.clear
-
-        tl.classes_or_modules.each do |cm|
-          name = cm.full_name
-          if cm.type == 'class' then
-            tl.classes_hash[name] = cm if @all_classes_hash[name]
-          else
-            tl.modules_hash[name] = cm if @all_modules_hash[name]
-          end
-        end
-      end
-    end
-  end
-
-  ##
-  # Finds the class with +name+ in all discovered classes
-
-  def self.find_class_named(name)
-    @all_classes_hash[name]
-  end
-
-  ##
-  # Finds the class with +name+ starting in namespace +from+
-
-  def self.find_class_named_from name, from
-    from = find_class_named from unless RDoc::Context === from
-
-    until RDoc::TopLevel === from do
-      return nil unless from
-
-      klass = from.find_class_named name
-      return klass if klass
-
-      from = from.parent
-    end
-
-    find_class_named name
-  end
-
-  ##
-  # Finds the class or module with +name+
-
-  def self.find_class_or_module(name)
-    name = $' if name =~ /^::/
-    RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
-  end
-
-  ##
-  # Finds the file with +name+ in all discovered files
-
-  def self.find_file_named(name)
-    @all_files_hash[name]
-  end
-
-  ##
-  # Finds the module with +name+ in all discovered modules
-
-  def self.find_module_named(name)
-    modules_hash[name]
-  end
-
-  ##
-  # Finds unique classes/modules defined in +all_hash+,
-  # and returns them as an array. Performs the alias
-  # updates in +all_hash+: see ::complete.
-  #--
-  # TODO  aliases should be registered by Context#add_module_alias
-
-  def self.find_unique(all_hash)
-    unique = []
-
-    all_hash.each_pair do |full_name, cm|
-      unique << cm if full_name == cm.full_name
-    end
-
-    unique
-  end
-
-  ##
-  # Fixes the erroneous <tt>BasicObject < Object</tt> in 1.9.
-  #
-  # Because we assumed all classes without a stated superclass
-  # inherit from Object, we have the above wrong inheritance.
-  #
-  # We fix BasicObject right away if we are running in a Ruby
-  # version >= 1.9. If not, we may be documenting 1.9 source
-  # while running under 1.8: we search the files of BasicObject
-  # for "object.c", and fix the inheritance if we find it.
-
-  def self.fix_basic_object_inheritance
-    basic = all_classes_hash['BasicObject']
-    return unless basic
-    if RUBY_VERSION >= '1.9'
-      basic.superclass = nil
-    elsif basic.in_files.any? { |f| File.basename(f.full_name) == 'object.c' }
-      basic.superclass = nil
-    end
-  end
-
-  ##
-  # Creates a new RDoc::TopLevel with +file_name+ only if one with the same
-  # name does not exist in all_files.
-
-  def self.new file_name
-    if top_level = @all_files_hash[file_name] then
-      top_level
-    else
-      top_level = super
-      @all_files_hash[file_name] = top_level
-      top_level
-    end
-  end
-
-  ##
-  # Returns the RDoc::TopLevel that has the given +name+
-
-  def self.page name
-    @all_files_hash.each_value.find do |file|
-      file.text? and file.page_name == name
-    end
-  end
-
-  ##
-  # Removes from +all_hash+ the contexts that are nodoc or have no content.
-  #
-  # See RDoc::Context#remove_from_documentation?
-
-  def self.remove_nodoc(all_hash)
-    all_hash.keys.each do |name|
-      context = all_hash[name]
-      all_hash.delete(name) if context.remove_from_documentation?
-    end
-  end
-
-  ##
-  # Empties RDoc of stored class, module and file information
-
-  def self.reset
-    @all_classes_hash = {}
-    @all_modules_hash = {}
-    @all_files_hash   = {}
-  end
-
-  ##
-  # Returns the unique classes discovered by RDoc.
-  #
-  # ::complete must have been called prior to using this method.
+  # Creates a new TopLevel for the file at +absolute_name+.  If documentation
+  # is being generated outside the source dir +relative_name+ is relative to
+  # the source directory.
 
-  def self.unique_classes
-    @unique_classes
-  end
-
-  ##
-  # Returns the unique classes and modules discovered by RDoc.
-  # ::complete must have been called prior to using this method.
-
-  def self.unique_classes_and_modules
-    @unique_classes + @unique_modules
-  end
-
-  ##
-  # Returns the unique modules discovered by RDoc.
-  # ::complete must have been called prior to using this method.
-
-  def self.unique_modules
-    @unique_modules
-  end
-
-  class << self
-    alias classes      all_classes
-    alias classes_hash all_classes_hash
-
-    alias files        all_files
-    alias files_hash   all_files_hash
-
-    alias modules      all_modules
-    alias modules_hash all_modules_hash
-  end
-
-  reset
-
-  ##
-  # Creates a new TopLevel for +file_name+
-
-  def initialize(file_name)
+  def initialize absolute_name, relative_name = absolute_name
     super()
     @name = nil
-    @relative_name = file_name
-    @absolute_name = file_name
-    @file_stat     = File.stat(file_name) rescue nil # HACK for testing
+    @absolute_name = absolute_name
+    @relative_name = relative_name
+    @file_stat     = File.stat(absolute_name) rescue nil # HACK for testing
     @diagram       = nil
     @parser        = nil
 
     @classes_or_modules = []
-
-    RDoc::TopLevel.files_hash[file_name] = self
   end
 
   ##
-  # An RDoc::TopLevel is equal to another with the same absolute_name
+  # An RDoc::TopLevel is equal to another with the same relative_name
 
   def == other
-    self.class === other and @absolute_name == other.absolute_name
+    self.class === other and @relative_name == other.relative_name
   end
 
   alias eql? ==
@@ -373,7 +108,7 @@ class RDoc::TopLevel < RDoc::Context
   # Base name of this file
 
   def base_name
-    File.basename @absolute_name
+    File.basename @relative_name
   end
 
   alias name base_name
@@ -393,7 +128,7 @@ class RDoc::TopLevel < RDoc::Context
   #       ones of this instance?
 
   def find_class_or_module name
-    RDoc::TopLevel.find_class_or_module name
+    @store.find_class_or_module name
   end
 
   ##
@@ -419,10 +154,10 @@ class RDoc::TopLevel < RDoc::Context
 
   ##
   # An RDoc::TopLevel has the same hash as another with the same
-  # absolute_name
+  # relative_name
 
   def hash
-    @absolute_name.hash
+    @relative_name.hash
   end
 
   ##
@@ -450,6 +185,29 @@ class RDoc::TopLevel < RDoc::Context
     @file_stat ? file_stat.mtime : nil
   end
 
+  ##
+  # Dumps this TopLevel for use by ri.  See also #marshal_load
+  def marshal_dump
+    [
+      MARSHAL_VERSION,
+      @relative_name,
+      @parser,
+      parse(@comment),
+    ]
+  end
+
+  ##
+  # Loads this TopLevel from +array+.
+
+  def marshal_load array # :nodoc:
+    initialize array[1]
+
+    @parser  = array[2]
+    @comment = array[3]
+
+    @file_stat          = nil
+  end
+
   ##
   # Returns the NormalClass "Object", creating it if not found.
   #
@@ -457,7 +215,7 @@ class RDoc::TopLevel < RDoc::Context
 
   def object_class
     @object_class ||= begin
-      oc = self.class.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
+      oc = @store.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
       oc.record_location self
       oc
     end
@@ -467,17 +225,17 @@ class RDoc::TopLevel < RDoc::Context
   # Base name of this file without the extension
 
   def page_name
-    basename = File.basename @absolute_name
+    basename = File.basename @relative_name
     basename =~ /\.[^.]*$/
 
     $` || basename
   end
 
   ##
-  # Path to this file
+  # Path to this file for use with HTML generator output.
 
   def path
-    http_url RDoc::RDoc.current.generator.file_dir
+    http_url @store.rdoc.generator.file_dir
   end
 
   def pretty_print q # :nodoc:
@@ -486,7 +244,7 @@ class RDoc::TopLevel < RDoc::Context
       q.breakable
 
       items = @modules.map { |n,m| m }
-      items.push(*@modules.map { |n,c| c })
+      items.concat @modules.map { |n,c| c }
       q.seplist items do |mod| q.pp mod end
     end
   end