rdoc 2.5.11 → 3.0

data/lib/rdoc/stats/normal.rb

@@ -0,0 +1,51 @@
+##
+# Stats printer that prints just the files being documented with a progress
+# bar
+
+class RDoc::Stats::Normal < RDoc::Stats::Quiet
+
+  def begin_adding # :nodoc:
+    puts "Parsing sources..."
+  end
+
+  ##
+  # Prints a file with a progress bar
+
+  def print_file files_so_far, filename
+    progress_bar = sprintf("%3d%% [%2d/%2d]  ",
+                           100 * files_so_far / @num_files,
+                           files_so_far,
+                           @num_files)
+
+    if $stdout.tty? then
+      # Print a progress bar, but make sure it fits on a single line. Filename
+      # will be truncated if necessary.
+      terminal_width = (ENV['COLUMNS'] || 80).to_i
+      max_filename_size = terminal_width - progress_bar.size
+
+      if filename.size > max_filename_size then
+        # Turn "some_long_filename.rb" to "...ong_filename.rb"
+        filename = filename[(filename.size - max_filename_size) .. -1]
+        filename[0..2] = "..."
+      end
+
+      # Pad the line with whitespaces so that leftover output from the
+      # previous line doesn't show up.
+      line = "#{progress_bar}#{filename}"
+      padding = terminal_width - line.size
+      line << (" " * padding) if padding > 0
+
+      $stdout.print("#{line}\r")
+    else
+      $stdout.puts "#{progress_bar} #{filename}"
+    end
+
+    $stdout.flush
+  end
+
+  def done_adding # :nodoc:
+    puts
+  end
+
+end
+

data/lib/rdoc/stats/quiet.rb

@@ -0,0 +1,59 @@
+##
+# Stats printer that prints nothing
+
+class RDoc::Stats::Quiet
+
+  ##
+  # Creates a new Quiet that will print nothing
+
+  def initialize num_files
+    @num_files = num_files
+  end
+
+  ##
+  # Prints a message at the beginning of parsing
+
+  def begin_adding(*) end
+
+  ##
+  # Prints when an alias is added
+
+  def print_alias(*) end
+
+  ##
+  # Prints when an attribute is added
+
+  def print_attribute(*) end
+
+  ##
+  # Prints when a class is added
+
+  def print_class(*) end
+
+  ##
+  # Prints when a constant is added
+
+  def print_constant(*) end
+
+  ##
+  # Prints when a file is added
+
+  def print_file(*) end
+
+  ##
+  # Prints when a method is added
+
+  def print_method(*) end
+
+  ##
+  # Prints when a module is added
+
+  def print_module(*) end
+
+  ##
+  # Prints when RDoc is done
+
+  def done_adding(*) end
+
+end
+

data/lib/rdoc/stats/verbose.rb

@@ -0,0 +1,45 @@
+##
+# Stats printer that prints everything documented, including the documented
+# status
+
+class RDoc::Stats::Verbose < RDoc::Stats::Normal
+
+  ##
+  # Returns a marker for RDoc::CodeObject +co+ being undocumented
+
+  def nodoc co
+    " (undocumented)" unless co.documented?
+  end
+
+  def print_alias as # :nodoc:
+    puts "    alias #{as.new_name} #{as.old_name}#{nodoc as}"
+  end
+
+  def print_attribute attribute # :nodoc:
+    puts "    #{attribute.definition} #{attribute.name}#{nodoc attribute}"
+  end
+
+  def print_class(klass) # :nodoc:
+    puts "  class #{klass.full_name}#{nodoc klass}"
+  end
+
+  def print_constant(constant) # :nodoc:
+    puts "    #{constant.name}#{nodoc constant}"
+  end
+
+  def print_file(files_so_far, file) # :nodoc:
+    super
+    puts
+  end
+
+  def print_method(method) # :nodoc:
+    puts "    #{method.singleton ? '::' : '#'}#{method.name}#{nodoc method}"
+  end
+
+  def print_module(mod) # :nodoc:
+    puts "  module #{mod.full_name}#{nodoc mod}"
+  end
+
+end
+
+

data/lib/rdoc/text.rb

@@ -1,8 +1,43 @@
+# coding: utf-8
+
+##
+# For RDoc::Text#to_html
+
+require 'strscan'
+
 ##
 # Methods for manipulating comment text
 
 module RDoc::Text
 
+  ##
+  # Maps an encoding to a Hash of characters properly transcoded for that
+  # encoding.
+  #
+  # See also encode_fallback.
+
+  TO_HTML_CHARACTERS = Hash.new do |h, encoding|
+    h[encoding] = {
+      :close_dquote => encode_fallback('”', encoding, '"'),
+      :close_squote => encode_fallback('’', encoding, '\''),
+      :copyright    => encode_fallback('©', encoding, '(c)'),
+      :ellipsis     => encode_fallback('…', encoding, '...'),
+      :em_dash      => encode_fallback('—', encoding, '---'),
+      :en_dash      => encode_fallback('–', encoding, '--'),
+      :open_dquote  => encode_fallback('“', encoding, '"'),
+      :open_squote  => encode_fallback('‘', encoding, '\''),
+      :trademark    => encode_fallback('®', encoding, '(r)'),
+    }
+  end if Object.const_defined? :Encoding
+
+  ##
+  # Transcodes +character+ to +encoding+ with a +fallback+ character.
+
+  def self.encode_fallback character, encoding, fallback
+    character.encode(encoding, :fallback => { character => fallback },
+                     :undef => :replace, :replace => fallback)
+  end
+
   ##
   # Expands tab characters in +text+ to eight spaces
 
@@ -43,8 +78,7 @@ module RDoc::Text
   end
 
   ##
-  # Convert a string in markup format into HTML.  Removes the first paragraph
-  # tags if +remove_para+ is true.
+  # Convert a string in markup format into HTML.
   #
   # Requires the including class to implement #formatter
 
@@ -105,7 +139,7 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
 
   def strip_hashes text
     return text if text =~ /^(?>\s*)[^\#]/
-    text.gsub(/^\s*(#+)/) { $1.tr '#',' ' }
+    text.gsub(/^\s*(#+)/) { $1.tr '#',' ' }.gsub(/^\s+$/, '')
   end
 
   ##
@@ -123,7 +157,102 @@ http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
     text.sub!  %r%/\*+%       do " " * $&.length end
     text.sub!  %r%\*+/%       do " " * $&.length end
     text.gsub! %r%^[ \t]*\*%m do " " * $&.length end
-    text
+    text.gsub(/^\s+$/, '')
+  end
+
+  ##
+  # Converts ampersand, dashes, ellipsis, quotes, copyright and registered
+  # trademark symbols in +text+ to properly encoded characters.
+
+  def to_html text
+    if Object.const_defined? :Encoding then
+      html = ''.encode text.encoding
+
+      encoded = RDoc::Text::TO_HTML_CHARACTERS[text.encoding]
+    else
+      html = ''
+      encoded = {
+        :close_dquote => '”',
+        :close_squote => '’',
+        :copyright    => '©',
+        :ellipsis     => '…',
+        :em_dash      => '—',
+        :en_dash      => '–',
+        :open_dquote  => '“',
+        :open_squote  => '‘',
+        :trademark    => '®',
+      }
+    end
+
+    s = StringScanner.new text
+    insquotes = false
+    indquotes = false
+    after_word = nil
+
+    until s.eos? do
+      case
+      when s.scan(/<tt>.*?<\/tt>/) then # skip contents of tt
+        html << s.matched.gsub('\\\\', '\\')
+      when s.scan(/<tt>.*?/) then
+        warn 'mismatched <tt> tag' # TODO signal file/line
+        html << s.matched
+      when s.scan(/<[^>]+\/?s*>/) then # skip HTML tags
+        html << s.matched
+      when s.scan(/\\(\S)/) then # unhandled suppressed crossref
+        html << s[1]
+        after_word = nil
+      when s.scan(/\.\.\.(\.?)/) then
+        html << s[1] << encoded[:ellipsis]
+        after_word = nil
+      when s.scan(/\(c\)/) then
+        html << encoded[:copyright]
+        after_word = nil
+      when s.scan(/\(r\)/) then
+        html << encoded[:trademark]
+        after_word = nil
+      when s.scan(/---/) then
+        html << encoded[:em_dash]
+        after_word = nil
+      when s.scan(/--/) then
+        html << encoded[:en_dash]
+        after_word = nil
+      when s.scan(/&quot;|"/) then
+        html << encoded[indquotes ? :close_dquote : :open_dquote]
+        indquotes = !indquotes
+        after_word = nil
+      when s.scan(/``/) then # backtick double quote
+        html << encoded[:open_dquote]
+        after_word = nil
+      when s.scan(/''/) then # tick double quote
+        html << encoded[:close_dquote]
+        after_word = nil
+      when s.scan(/'/) then # single quote
+        if insquotes
+          html << encoded[:close_squote]
+          insquotes = false
+        elsif after_word
+          # Mary's dog, my parents' house: do not start paired quotes
+          html << encoded[:close_squote]
+        else
+          html << encoded[:open_squote]
+          insquotes = true
+        end
+
+        after_word = nil
+      else # advance to the next potentially significant character
+        match = s.scan(/.+?(?=[<\\.("'`&-])/) #"
+
+        if match then
+          html << match
+          after_word = match =~ /\w$/
+        else
+          html << s.rest
+          break
+        end
+      end
+    end
+
+    html
   end
 
 end

data/lib/rdoc/{tokenstream.rb → token_stream.rb}

@@ -1,5 +1,3 @@
-module RDoc; end
-
 ##
 # A TokenStream is a list of tokens, gathered during the parse of some entity
 # (say a method). Entities populate these streams by being registered with the

data/lib/rdoc/top_level.rb

@@ -20,7 +20,14 @@ class RDoc::TopLevel < RDoc::Context
 
   attr_accessor :absolute_name
 
-  attr_accessor :diagram
+  ##
+  # All the classes or modules that were declared in
+  # this file. These are assigned to either +#classes_hash+
+  # or +#modules_hash+ once we know what they really are.
+
+  attr_reader :classes_or_modules
+
+  attr_accessor :diagram # :nodoc:
 
   ##
   # The parser that processed this file
@@ -28,45 +35,110 @@ class RDoc::TopLevel < RDoc::Context
   attr_accessor :parser
 
   ##
-  # Returns all classes and modules discovered by RDoc
+  # Returns all classes discovered by RDoc
 
-  def self.all_classes_and_modules
-    classes_hash.values + modules_hash.values
+  def self.all_classes
+    @all_classes_hash.values
   end
 
   ##
-  # Returns all classes discovered by RDoc
+  # Returns all classes and modules discovered by RDoc
 
-  def self.classes
-    classes_hash.values
+  def self.all_classes_and_modules
+    @all_classes_hash.values + @all_modules_hash.values
   end
 
   ##
   # Hash of all classes known to RDoc
 
-  def self.classes_hash
-    @all_classes
+  def self.all_classes_hash
+    @all_classes_hash
   end
 
   ##
   # All TopLevels known to RDoc
 
-  def self.files
-    @all_files.values
+  def self.all_files
+    @all_files_hash.values
   end
 
   ##
   # Hash of all files known to RDoc
 
-  def self.files_hash
-    @all_files
+  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 RDoc::Parser::Simple === tl.parser 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)
-    classes_hash[name]
+    @all_classes_hash[name]
   end
 
   ##
@@ -91,9 +163,7 @@ class RDoc::TopLevel < RDoc::Context
   # Finds the class or module with +name+
 
   def self.find_class_or_module(name)
-    name =~ /^::/
-    name = $' || name
-
+    name = $' if name =~ /^::/
     RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
   end
 
@@ -101,7 +171,7 @@ class RDoc::TopLevel < RDoc::Context
   # Finds the file with +name+ in all discovered files
 
   def self.find_file_named(name)
-    @all_files[name]
+    @all_files_hash[name]
   end
 
   ##
@@ -112,26 +182,98 @@ class RDoc::TopLevel < RDoc::Context
   end
 
   ##
-  # Returns all modules discovered by RDoc
+  # 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.modules
-    modules_hash.values
+  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
 
   ##
-  # Hash of all modules known to RDoc
+  # 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
 
-  def self.modules_hash
-    @all_modules
+  ##
+  # 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 = {}
-    @all_modules = {}
-    @all_files   = {}
+    @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.
+
+  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
@@ -148,17 +290,49 @@ class RDoc::TopLevel < RDoc::Context
     @diagram       = nil
     @parser        = nil
 
+    @classes_or_modules = []
+
     RDoc::TopLevel.files_hash[file_name] = self
   end
 
   ##
-  # Adds +method+ to Object instead of RDoc::TopLevel
+  # Adds +an_alias+ to +Object+ instead of +self+.
+
+  def add_alias(an_alias)
+    return an_alias unless @document_self
+    object_class.add_alias an_alias
+  end
+
+  ##
+  # Adds +constant+ to +Object+ instead of +self+.
+
+  def add_constant(constant)
+    return constant unless @document_self
+    object_class.add_constant constant
+  end
+
+  ##
+  # Adds +include+ to +Object+ instead of +self+.
+
+  def add_include(include)
+    return include unless @document_self
+    object_class.add_include include
+  end
+
+  ##
+  # Adds +method+ to +Object+ instead of +self+.
 
   def add_method(method)
-    object = self.class.find_class_named 'Object'
-    object = add_class RDoc::NormalClass, 'Object' unless object
+    return method unless @document_self
+    object_class.add_method method
+  end
+
+  ##
+  # Adds class or module +mod+. Used in the building phase
+  # by the ruby parser.
 
-    object.add_method method
+  def add_to_classes_or_modules mod
+    @classes_or_modules << mod
   end
 
   ##
@@ -168,8 +342,13 @@ class RDoc::TopLevel < RDoc::Context
     File.basename @absolute_name
   end
 
+  alias name base_name
+
   ##
-  # See RDoc::TopLevel.find_class_or_module
+  # See RDoc::TopLevel::find_class_or_module
+  #--
+  # TODO Why do we search through all classes/modules found, not just the
+  #       ones of this instance?
 
   def find_class_or_module name
     RDoc::TopLevel.find_class_or_module name
@@ -186,11 +365,11 @@ class RDoc::TopLevel < RDoc::Context
   # Finds a module or class with +name+
 
   def find_module_named(name)
-    find_class_or_module(name) || find_enclosing_module_named(name)
+    find_class_or_module(name)
   end
 
   ##
-  # The name of this file
+  # Returns the relative name of this file
 
   def full_name
     @relative_name
@@ -215,16 +394,24 @@ class RDoc::TopLevel < RDoc::Context
   end
 
   ##
-  # Date this file was last modified, if known
+  # Time this file was last modified, if known
 
   def last_modified
-    @file_stat ? file_stat.mtime.to_s : 'Unknown'
+    @file_stat ? file_stat.mtime : nil
   end
 
   ##
-  # Base name of this file
-
-  alias name base_name
+  # Returns the NormalClass "Object", creating it if not found.
+  #
+  # Records +self+ as a location in "Object".
+
+  def object_class
+    @object_class ||= begin
+      oc = self.class.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
+      oc.record_location self
+      oc
+    end
+  end
 
   ##
   # Path to this file
@@ -244,5 +431,9 @@ class RDoc::TopLevel < RDoc::Context
     end
   end
 
+  def to_s # :nodoc:
+    "file #{full_name}"
+  end
+
 end