* lib/rdoc.rb: Import RDoc 3.7 release candidate

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

1 files changed, 75 insertions, 29 deletions

diff --git a/lib/rdoc/context.rb b/lib/rdoc/context.rb
index f0168585ec..d2552c647c 100644
--- a/lib/rdoc/context.rb
+++ b/lib/rdoc/context.rb
@@ -30,9 +30,9 @@ class RDoc::Context < RDoc::CodeObject
   attr_reader :constants
 
   ##
-  # Current section of documentation
+  # Sets the current documentation section of documentation
 
-  attr_accessor :current_section
+  attr_writer :current_section
 
   ##
   # Files this context is found in
@@ -60,6 +60,11 @@ class RDoc::Context < RDoc::CodeObject
   attr_reader :requires
 
   ##
+  # Use this section for the next method, attribute or constant added.
+
+  attr_accessor :temporary_section
+
+  ##
   # Hash <tt>old_name => [aliases]</tt>, for aliases
   # that haven't (yet) been resolved to a method/attribute.
   # (Not to be confused with the aliases of the context.)
@@ -186,10 +191,7 @@ class RDoc::Context < RDoc::CodeObject
     end
 
     def inspect # :nodoc:
-      "#<%s:0x%x %s %p>" % [
-        self.class, object_id,
-        @sequence, title
-      ]
+      "#<%s:0x%x %p>" % [self.class, object_id, title]
     end
 
     ##
@@ -216,6 +218,7 @@ class RDoc::Context < RDoc::CodeObject
 
     @current_section = Section.new self, nil, nil
     @sections = { nil => @current_section }
+    @temporary_section = nil
 
     @classes = {}
     @modules = {}
@@ -287,22 +290,32 @@ class RDoc::Context < RDoc::CodeObject
     # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
     register = false
 
-    if attribute.rw.index('R') then
+    key = nil
+
+    if attribute.rw.index 'R' then
       key = attribute.pretty_name
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name << '='] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
       end
     end
 
-    if attribute.rw.index('W')
+    if attribute.rw.index 'W' then
       key = attribute.pretty_name << '='
       known = @methods_hash[key]
+
       if known then
         known.comment = attribute.comment if known.comment.empty?
+      elsif registered = @methods_hash[attribute.pretty_name] and
+            RDoc::Attr === registered then
+        registered.rw = 'RW'
       else
         @methods_hash[key] = attribute
         register = true
@@ -314,6 +327,8 @@ class RDoc::Context < RDoc::CodeObject
       add_to @attributes, attribute
       resolve_aliases attribute
     end
+
+    attribute
   end
 
   ##
@@ -444,8 +459,8 @@ class RDoc::Context < RDoc::CodeObject
   # to +self+, and its #section to #current_section. Returns +mod+.
 
   def add_class_or_module mod, self_hash, all_hash
-    mod.section = @current_section # TODO declaring context? something is
-                                   # wrong here...
+    mod.section = current_section # TODO declaring context? something is
+                                  # wrong here...
     mod.parent = self
 
     unless @done_documenting then
@@ -462,7 +477,7 @@ class RDoc::Context < RDoc::CodeObject
   # Adds +constant+ if not already there. If it is, updates the comment,
   # value and/or is_alias_for of the known constant if they were empty/nil.
 
-  def add_constant(constant)
+  def add_constant constant
     return constant unless @document_self
 
     # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
@@ -480,28 +495,32 @@ class RDoc::Context < RDoc::CodeObject
       @constants_hash[constant.name] = constant
       add_to @constants, constant
     end
+
+    constant
   end
 
   ##
   # Adds included module +include+ which should be an RDoc::Include
 
-  def add_include(include)
-    add_to @includes, include unless @includes.map { |i| i.full_name }.include?( include.full_name )
+  def add_include include
+    add_to @includes, include unless
+      @includes.map { |i| i.full_name }.include? include.full_name
+
+    include
   end
 
   ##
   # Adds +method+ if not already there. If it is (as method or attribute),
   # updates the comment if it was empty.
 
-  def add_method(method)
+  def add_method method
     return method unless @document_self
 
     # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
     key = method.pretty_name
     known = @methods_hash[key]
-    if known
-      # TODO issue stderr messages if --verbose
-      #$stderr.puts "\n#{display(method)} already registered as #{display(known)}"
+
+    if known then
       known.comment = method.comment if known.comment.empty?
     else
       @methods_hash[key] = method
@@ -509,6 +528,8 @@ class RDoc::Context < RDoc::CodeObject
       add_to @method_list, method
       resolve_aliases method
     end
+
+    method
   end
 
   ##
@@ -573,12 +594,31 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
+  # Returns a section with +title+, creating it if it doesn't already exist.
+  # +comment+ will be appended to the section's comment.
+  #
+  # A section with a +title+ of +nil+ will return the default section.
+  #
+  # See also RDoc::Context::Section
+
+  def add_section title, comment
+    if section = @sections[title] then
+      section.comment = comment
+    else
+      section = Section.new self, title, comment
+      @sections[title] = section
+    end
+
+    section
+  end
+
+  ##
   # Adds +thing+ to the collection +array+
 
   def add_to(array, thing)
     array << thing if @document_self
     thing.parent = self
-    thing.section = @current_section
+    thing.section = current_section
   end
 
   ##
@@ -649,6 +689,20 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
+  # The current documentation section that new items will be added to.  If
+  # temporary_section is available it will be used.
+
+  def current_section
+    if section = @temporary_section then
+      @temporary_section = nil
+    else
+      section = @current_section
+    end
+
+    section
+  end
+
+  ##
   # Is part of this thing was defined in +file+?
 
   def defined_in?(file)
@@ -1082,18 +1136,10 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Creates a new section with +title+ and +comment+
-
-  def set_current_section(title, comment)
-    if @sections.key? title then
-      @current_section = @sections[title]
-      @current_section.comment = comment
-    else
-      @current_section = Section.new self, title, comment
-      @sections[title] = @current_section
-    end
+  # Sets the current section to a section with +title+.  See also #add_section
 
-    @current_section
+  def set_current_section title, comment
+    @current_section = add_section title, comment
   end
 
   ##