rdoc 3.6.1 → 3.7

data/History.txt

@@ -1,3 +1,48 @@
+=== 3.7 / 2011-06-27
+
+* Minor enhancements
+  * New directive :category: which allows methods to be grouped into sections
+    more cleanly.  See RDoc::Markup for details.
+  * Document-class for RDoc::Parser::C now supports Foo::CONST as well as
+    CONST.
+  * ri method output is now a comma-separated list when displayed
+    interactively.  Pull Request #39 by Benoit Daloze.
+  * RDoc::ClassModule#merge now prefers the argument's information over the
+    receiver's (it now behaves like Hash#merge! instead of a backwards
+    Hash#merge!).
+  * RDoc::Markup#convert now accepts an RDoc::Markup::Document instance
+  * RDoc now owns the code for generating RDoc and ri data when gems install
+  * Added RDoc::RDoc::reset
+  * Added RDoc::CodeObject#file_name
+* Bug fixes
+  * ri no longer crashes when attempting to complete a plain [.
+  * ri data now tracks which file information came from so it can process
+    removals and changes to:
+    * Classes and Modules
+    * Methods
+    * Attributes
+    * Includes
+    * Constants
+    You will need to rebuild your ri data for it to update properly.  Issue
+    #21 by Sven Riedel
+  * Signal and SignalException no longer clobber each other
+  * RDoc::Parser::C no longer creates classes when processing aliases.
+  * RDoc::Text#strip_stars handles Document-method for methods with =, ! and ?
+    now.
+  * RDoc::Parser::C now allows .cpp files to be used with the "in" comment on
+    rb_define_method.  Bug #35 by Hanmac.
+  * RDoc::Parser::Ruby no longer eats content when =begin/=end documentation
+    blocks are followed by a documentable item.  Issue #41 by mfn.
+  * RDoc::Markup::Formatter and subclasses now allow an optional +markup+
+    parameter for adding custom markup.  The example in
+    RDoc::Markup::Formatter will now work.  Issue #38 by tsilen.
+  * RDoc::Parser::C can now distinguish between class methods and instance
+    methods in Document-method.  Issue #36 by Vincent Batts.
+  * RDoc now encodes file names in the output encoding.  Issue #33 by Perry
+    Smith.
+  * ri data generation for method aliases no longer duplicates the class in
+    #full_name
+
 === 3.6.1 / 2011-05-15
 
 * Bug fixes

data/Manifest.txt

@@ -64,6 +64,7 @@ lib/rdoc/markup/document.rb
 lib/rdoc/markup/formatter.rb
 lib/rdoc/markup/formatter_test_case.rb
 lib/rdoc/markup/heading.rb
+lib/rdoc/markup/indented_paragraph.rb
 lib/rdoc/markup/inline.rb
 lib/rdoc/markup/list.rb
 lib/rdoc/markup/list_item.rb
@@ -100,6 +101,7 @@ lib/rdoc/ri/paths.rb
 lib/rdoc/ri/store.rb
 lib/rdoc/ruby_lex.rb
 lib/rdoc/ruby_token.rb
+lib/rdoc/rubygems_hook.rb
 lib/rdoc/single_class.rb
 lib/rdoc/stats.rb
 lib/rdoc/stats/normal.rb
@@ -132,6 +134,7 @@ test/test_rdoc_include.rb
 test/test_rdoc_markup.rb
 test/test_rdoc_markup_attribute_manager.rb
 test/test_rdoc_markup_document.rb
+test/test_rdoc_markup_indented_paragraph.rb
 test/test_rdoc_markup_paragraph.rb
 test/test_rdoc_markup_parser.rb
 test/test_rdoc_markup_pre_process.rb
@@ -156,6 +159,7 @@ test/test_rdoc_ri_driver.rb
 test/test_rdoc_ri_paths.rb
 test/test_rdoc_ri_store.rb
 test/test_rdoc_ruby_lex.rb
+test/test_rdoc_rubygems_hook.rb
 test/test_rdoc_single_class.rb
 test/test_rdoc_stats.rb
 test/test_rdoc_task.rb

data/lib/rdoc.rb

@@ -27,7 +27,8 @@ $DEBUG_RDOC = nil
 # * 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 generate documentation for extensions written in C, see
+# * 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.
@@ -103,7 +104,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.6.1'
+  VERSION = '3.7'
 
   ##
   # Method visibilities

data/lib/rdoc/any_method.rb

@@ -6,7 +6,7 @@ require 'rdoc/token_stream'
 
 class RDoc::AnyMethod < RDoc::MethodAttr
 
-  MARSHAL_VERSION = 0 # :nodoc:
+  MARSHAL_VERSION = 1 # :nodoc:
 
   ##
   # Don't rename \#initialize to \::new
@@ -44,7 +44,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   ##
   # Adds +an_alias+ as an alias for this method in +context+.
 
-  def add_alias(an_alias, context = nil )
+  def add_alias an_alias, context = nil
     method = self.class.new an_alias.text, an_alias.new_name
 
     method.record_location an_alias.file
@@ -54,7 +54,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     method.comment = an_alias.comment
     method.is_alias_for = self
     @aliases << method
-    context.add_method( method ) if context
+    context.add_method method if context
     method
   end
 
@@ -83,7 +83,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   def marshal_dump
     aliases = @aliases.map do |a|
-      [a.full_name, parse(a.comment)]
+      [a.name, parse(a.comment)]
     end
 
     [ MARSHAL_VERSION,
@@ -96,6 +96,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
       @block_params,
       aliases,
       @params,
+      @file.absolute_name,
     ]
   end
 
@@ -112,6 +113,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @token_stream           = nil
     @aliases                = []
 
+    version       = array[0]
     @name         = array[1]
     @full_name    = array[2]
     @singleton    = array[3]
@@ -119,6 +121,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
     @comment      = array[5]
     @call_seq     = array[6]
     @block_params = array[7]
+
+    array[8].each do |new_name, comment|
+      add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
+    end
+
     @params       = array[9]
 
     @parent_name = if @full_name =~ /#/ then
@@ -129,9 +136,7 @@ class RDoc::AnyMethod < RDoc::MethodAttr
                      name.join '::'
                    end
 
-    array[8].each do |new_name, comment|
-      add_alias RDoc::Alias.new(nil, @name, new_name, comment, @singleton)
-    end
+    @file = RDoc::TopLevel.new array[10] if version > 0
   end
 
   ##

data/lib/rdoc/attr.rb

@@ -6,7 +6,7 @@ require 'rdoc/method_attr'
 
 class RDoc::Attr < RDoc::MethodAttr
 
-  MARSHAL_VERSION = 1 # :nodoc:
+  MARSHAL_VERSION = 2 # :nodoc:
 
   ##
   # Is the attribute readable ('R'), writable ('W') or both ('RW')?
@@ -92,6 +92,7 @@ class RDoc::Attr < RDoc::MethodAttr
       @visibility,
       parse(@comment),
       singleton,
+      @file.absolute_name,
     ]
   end
 
@@ -103,6 +104,7 @@ class RDoc::Attr < RDoc::MethodAttr
   # * #parent_name
 
   def marshal_load array
+    version     = array[0]
     @name       = array[1]
     @full_name  = array[2]
     @rw         = array[3]
@@ -110,9 +112,22 @@ class RDoc::Attr < RDoc::MethodAttr
     @comment    = array[5]
     @singleton  = array[6] || false # MARSHAL_VERSION == 0
 
+    @file = RDoc::TopLevel.new array[7] if version > 1
+
     @parent_name = @full_name
   end
 
+  def pretty_print q # :nodoc:
+    q.group 2, "[#{self.class.name} #{full_name} #{rw} #{visibility}", "]" do
+      unless comment.empty? then
+        q.breakable
+        q.text "comment:"
+        q.breakable
+        q.pp @comment
+      end
+    end
+  end
+
   def to_s # :nodoc:
     "#{definition} #{name} in: #{parent}"
   end

data/lib/rdoc/class_module.rb

@@ -6,13 +6,26 @@ require 'rdoc/context'
 
 class RDoc::ClassModule < RDoc::Context
 
-  MARSHAL_VERSION = 0 # :nodoc:
+  ##
+  # 1::
+  #   RDoc 3.7
+  #   * Added visibility, singleton and file to attributes
+  #   * Added file to constants
+  #   * Added file to includes
+  #   * Added file to methods
+
+  MARSHAL_VERSION = 1 # :nodoc:
 
   ##
   # Constants that are aliases for this class or module
 
   attr_accessor :constant_aliases
 
+  ##
+  # Comment and the location it came from.  Use #add_comment to add comments
+
+  attr_reader :comment_location
+
   attr_accessor :diagram # :nodoc:
 
   ##
@@ -23,10 +36,16 @@ class RDoc::ClassModule < RDoc::Context
   ##
   # Return a RDoc::ClassModule of class +class_type+ that is a copy
   # of module +module+. Used to promote modules to classes.
+  #--
+  # TODO move to RDoc::NormalClass (I think)
+
+  def self.from_module class_type, mod
+    klass = class_type.new mod.name
+
+    mod.comment_location.each do |comment, location|
+      klass.add_comment comment, location
+    end
 
-  def self.from_module(class_type, mod)
-    klass = class_type.new(mod.name)
-    klass.comment = mod.comment
     klass.parent = mod.parent
     klass.section = mod.section
     klass.viewer = mod.viewer
@@ -85,9 +104,27 @@ class RDoc::ClassModule < RDoc::Context
     @is_alias_for     = nil
     @name             = name
     @superclass       = superclass
+    @comment_location = [] # [[comment, location]]
+
     super()
   end
 
+  ##
+  # Adds +comment+ to this ClassModule's list of comments at +location+.  This
+  # method is preferred over #comment= since it allows ri data to be updated
+  # across multiple runs.
+
+  def add_comment comment, location
+    return if comment.empty?
+
+    original = comment
+
+    comment = normalize_comment comment
+    @comment_location << [comment, location]
+
+    self.comment = original
+  end
+
   ##
   # Ancestors list for this ClassModule: the list of included modules
   # (classes will add their superclass if any).
@@ -112,6 +149,8 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   ##
+  # This method is deprecated, use #add_comment instead.
+  #
   # Appends +comment+ to the current comment, but separated by a rule.  Works
   # more like <tt>+=</tt>.
 
@@ -119,10 +158,9 @@ class RDoc::ClassModule < RDoc::Context
     return if comment.empty?
 
     comment = normalize_comment comment
-    comment = "#{@comment}\n---\n#{comment}" unless
-      @comment.empty?
+    comment = "#{@comment}\n---\n#{comment}" unless @comment.empty?
 
-    super
+    super comment
   end
 
   ##
@@ -185,15 +223,16 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   def marshal_dump # :nodoc:
-    # TODO must store the singleton attribute
     attrs = attributes.sort.map do |attr|
-      [attr.name, attr.rw]
+      [ attr.name, attr.rw,
+        attr.visibility, attr.singleton, attr.file_name,
+      ]
     end
 
     method_types = methods_by_type.map do |type, visibilities|
       visibilities = visibilities.map do |visibility, methods|
         method_names = methods.map do |method|
-          method.name
+          [method.name, method.file_name]
         end
 
         [visibility, method_names.uniq]
@@ -206,51 +245,67 @@ class RDoc::ClassModule < RDoc::Context
       @name,
       full_name,
       @superclass,
-      parse(@comment),
+      parse(@comment_location),
       attrs,
       constants.map do |const|
-        [const.name, parse(const.comment)]
+        [const.name, parse(const.comment), const.file_name]
       end,
       includes.map do |incl|
-        [incl.name, parse(incl.comment)]
+        [incl.name, parse(incl.comment), incl.file_name]
       end,
       method_types,
     ]
   end
 
   def marshal_load array # :nodoc:
-    # TODO must restore the singleton attribute
     initialize_methods_etc
-    @document_self    = true
-    @done_documenting = false
-    @current_section  = nil
-    @parent           = nil
-    @visibility       = nil
+    @current_section   = nil
+    @document_self     = true
+    @done_documenting  = false
+    @parent            = nil
+    @temporary_section = nil
+    @visibility        = nil
 
     @name       = array[1]
     @full_name  = array[2]
     @superclass = array[3]
     @comment    = array[4]
 
-    array[5].each do |name, rw|
-      add_attribute RDoc::Attr.new(nil, name, rw, nil)
+    @comment_location = if RDoc::Markup::Document === @comment.parts.first then
+                          @comment
+                        else
+                          RDoc::Markup::Document.new @comment
+                        end
+
+    array[5].each do |name, rw, visibility, singleton, file|
+      singleton  ||= false
+      visibility ||= :public
+
+      attr = RDoc::Attr.new nil, name, rw, nil, singleton
+
+      add_attribute attr
+      attr.visibility = visibility
+      attr.record_location RDoc::TopLevel.new file
     end
 
-    array[6].each do |name, comment|
-      add_constant RDoc::Constant.new(name, nil, comment)
+    array[6].each do |name, comment, file|
+      const = add_constant RDoc::Constant.new(name, nil, comment)
+      const.record_location RDoc::TopLevel.new file
     end
 
-    array[7].each do |name, comment|
-      add_include RDoc::Include.new(name, comment)
+    array[7].each do |name, comment, file|
+      incl = add_include RDoc::Include.new(name, comment)
+      incl.record_location RDoc::TopLevel.new file
     end
 
     array[8].each do |type, visibilities|
       visibilities.each do |visibility, methods|
         @visibility = visibility
 
-        methods.each do |name|
+        methods.each do |name, file|
           method = RDoc::AnyMethod.new nil, name
           method.singleton = true if type == 'class'
+          method.record_location RDoc::TopLevel.new file
           add_method method
         end
       end
@@ -258,37 +313,73 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   ##
-  # Merges +class_module+ into this ClassModule
+  # Merges +class_module+ into this ClassModule.
+  #
+  # The data in +class_module+ is preferred over the receiver.
 
   def merge class_module
-    comment = class_module.comment
+    other_document = parse class_module.comment_location
 
-    if comment then
-      document = parse @comment
+    if other_document then
+      document = parse @comment_location
 
-      comment.parts.concat document.parts
+      document = document.merge other_document
 
-      @comment = comment
+      @comment = @comment_location = document
     end
 
-    class_module.each_attribute do |attr|
-      if match = attributes.find { |a| a.name == attr.name } then
-        match.rw = [match.rw, attr.rw].compact.uniq.join
-      else
+    merge_collections attributes, class_module.attributes do |add, attr|
+      if add then
         add_attribute attr
+      else
+        @attributes.delete attr
+        @methods_hash.delete attr.pretty_name
       end
     end
 
-    class_module.each_constant do |const|
-      add_constant const
+    merge_collections constants, class_module.constants do |add, const|
+      if add then
+        add_constant const
+      else
+        @constants.delete const
+        @constants_hash.delete const.name
+      end
     end
 
-    class_module.each_include do |incl|
-      add_include incl
+    merge_collections includes, class_module.includes do |add, incl|
+      if add then
+        add_include incl
+      else
+        @includes.delete incl
+      end
     end
 
-    class_module.each_method do |meth|
-      add_method meth
+    merge_collections method_list, class_module.method_list do |add, meth|
+      if add then
+        add_method meth
+      else
+        @method_list.delete meth
+        @methods_hash.delete meth.pretty_name
+      end
+    end
+
+    self
+  end
+
+  ##
+  # Merges collection +mine+ with +other+ preferring other.
+
+  def merge_collections mine, other, &block # :nodoc:
+    my_things    = mine. group_by { |thing| thing.file }
+    other_things = other.group_by { |thing| thing.file }
+
+    other_things.each do |file, things|
+      my_things[file].each { |thing| yield false, thing } if
+        my_things.include? file
+
+      things.each do |thing|
+        yield true, thing
+      end
     end
   end
 
@@ -308,6 +399,29 @@ class RDoc::ClassModule < RDoc::Context
     @name = new_name
   end
 
+  ##
+  # Parses +comment_location+ into an RDoc::Markup::Document composed of
+  # multiple RDoc::Markup::Documents with their file set.
+
+  def parse comment_location
+    case comment_location
+    when String then
+      super
+    when Array then
+      docs = comment_location.map do |comment, location|
+        doc = super comment
+        doc.file = location.absolute_name
+        doc
+      end
+
+      RDoc::Markup::Document.new(*docs)
+    when RDoc::Markup::Document then
+      return comment_location
+    else
+      raise ArgumentError, "unknown comment class #{comment_location.class}"
+    end
+  end
+
   ##
   # Path to this class or module