Put RDoc comments into array.c, and refine rdoc/ri to deal with stuff that arose

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

8 files changed, 105 insertions, 41 deletions

diff --git a/lib/rdoc/generators/ri_generator.rb b/lib/rdoc/generators/ri_generator.rb
index db86d744af..375c534923 100644
--- a/lib/rdoc/generators/ri_generator.rb
+++ b/lib/rdoc/generators/ri_generator.rb
@@ -100,8 +100,6 @@ module Generators
       cls_desc.superclass  = cls.superclass
       cls_desc.comment     = markup(cls.comment)
 
-      cls_desc.method_list = method_list(cls)
-
       cls_desc.attributes =cls.attributes.sort.map do |a|
         RI::Attribute.new(a.name, a.rw, markup(a.comment))
       end
@@ -114,16 +112,23 @@ module Generators
         RI::IncludedModule.new(i.name)
       end
 
-      methods = method_list(cls)
+      class_methods, instance_methods = method_list(cls)
 
-      cls_desc.method_list = methods.map do |m|
+      cls_desc.class_methods = class_methods.map do |m|
+        RI::MethodSummary.new(m.name)
+      end
+      cls_desc.instance_methods = instance_methods.map do |m|
         RI::MethodSummary.new(m.name)
       end
 
       @ri_writer.remove_class(cls_desc)
       @ri_writer.add_class(cls_desc)
 
-      methods.each do |m|
+      class_methods.each do |m|
+        generate_method_info(cls_desc, m)
+      end
+
+      instance_methods.each do |m|
         generate_method_info(cls_desc, m)
       end
     end
@@ -155,7 +160,8 @@ module Generators
 
     private
 
-    # return a list of methods that we'll be documenting
+    # return a list of class and instance methods that we'll be
+    # documenting
 
     def method_list(cls)
       list = cls.method_list
@@ -164,22 +170,37 @@ module Generators
           m.visibility == :public || m.force_documentation 
         end
       end
-      
-      list.sort
+
+      c = []
+      i = []
+      list.sort.each do |m|
+        if m.singleton
+          c << m
+        else
+          i << m
+        end
+      end
+      return c,i
     end
     
     def params_of(method)
-      p = method.params.gsub(/\s*\#.*/, '')
-      p = p.tr("\n", " ").squeeze(" ")
-      p = "(" + p + ")" unless p[0] == ?(
-      
-      if (block = method.block_params)
-        block.gsub!(/\s*\#.*/, '')
-        block = block.tr("\n", " ").squeeze(" ")
-        if block[0] == ?(
-          block.sub!(/^\(/, '').sub!(/\)/, '')
+      params = method.params || ""
+
+      if params =~ /^!verb!(.*)/m
+        p = $1
+      else
+        p = params.gsub(/\s*\#.*/, '')
+        p = p.tr("\n", " ").squeeze(" ")
+        p = "(" + p + ")" unless p[0] == ?(
+        
+        if (block = method.block_params)
+          block.gsub!(/\s*\#.*/, '')
+          block = block.tr("\n", " ").squeeze(" ")
+          if block[0] == ?(
+            block.sub!(/^\(/, '').sub!(/\)/, '')
+          end
+          p << " {|#{block.strip}| ...}"
         end
-        p << " {|#{block.strip}| ...}"
       end
       p
     end
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index 3d9d7a247f..3e8b48da34 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -153,7 +153,7 @@ module RDoc
     def remove_commented_out_lines
       @body.gsub!(%r{//.*rb_define_}, '//')
     end
-
+    
     def handle_class_module(var_name, class_mod, class_name, parent, in_module)
       @known_classes[var_name] = class_name
       parent_name = @known_classes[parent] || parent
@@ -162,7 +162,7 @@ module RDoc
         enclosure = @classes[in_module]
         unless enclosure
           $stderr.puts("Enclosing class/module '#{in_module}' for " +
-                        class_mod + " #{class_name} not known")
+                        "#{class_mod} #{class_name} not known")
           return
         end
       else
@@ -175,10 +175,17 @@ module RDoc
         cm = enclosure.add_module(NormalModule, class_name)
       end
       cm.record_location(enclosure.toplevel)
+      find_class_comment(class_name, cm)
       @classes[var_name] = cm
     end
     
     
+    def find_class_comment(class_name, class_meth)
+      if @body =~ %r{((?>/\*.*?\*/\s+))
+                     (static\s+)?void\s+Init_#{class_name}\s*\(\)}xm
+        class_meth.comment = mangle_comment($1)
+      end
+    end
     
     def do_classes
       @body.scan(/(\w+)\s* = \s*rb_define_module\(\s*"(\w+)"\s*\)/mx) do 
@@ -224,14 +231,20 @@ module RDoc
       @body.scan(/rb_define_(singleton_method|method|module_function)\(\s*(\w+),
                                \s*"([^"]+)",
                                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
-                               \s*(-?\w+)\s*\)/xm) do 
+                               \s*(-?\w+)\s*\)/xm) do  #"
         |type, var_name, meth_name, meth_body, param_count|
         
+        next if meth_name == "initialize_copy"
+
         class_name = @known_classes[var_name] || var_name
         class_obj  = @classes[var_name]
         if class_obj
+          if meth_name == "initialize"
+            meth_name = "new"
+            type = "singleton_method"
+          end
           meth_obj = AnyMethod.new("", meth_name)
-          meth_obj.singleton = type == "singleton_method"
+          meth_obj.singleton = type == "singleton_method" 
           
           p_count = (Integer(param_count) rescue -1)
           
@@ -265,7 +278,19 @@ module RDoc
           body_text = $&
         end
 
-        meth_obj.params = params
+        # If the comment block contains a section that looks like
+        #    call-seq:
+        #        Array.new
+        #        Array.new(10)
+        # use it for the parameters
+
+        if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '')
+          seq = $1
+          seq.gsub!(/^\s*\*\s*/, '')
+          meth_obj.params = "!verb!" + seq
+        end
+        
+#        meth_obj.params = params
         meth_obj.start_collecting_tokens
         meth_obj.add_token(RubyToken::Token.new(1,1).set_text(body_text))
         meth_obj.comment = mangle_comment(comment)
diff --git a/lib/rdoc/ri/ri_cache.rb b/lib/rdoc/ri/ri_cache.rb
index 4ca976c4b9..da2a7e47ff 100644
--- a/lib/rdoc/ri/ri_cache.rb
+++ b/lib/rdoc/ri/ri_cache.rb
@@ -56,16 +56,16 @@ module RI
     # return the list of local methods matching name
     # We're split into two because we need distinct behavior
     # when called from the toplevel
-    def methods_matching(name)
-      local_methods_matching(name)
+    def methods_matching(name, is_class_method)
+      local_methods_matching(name, is_class_method)
     end
 
     # Find methods matching 'name' in ourselves and in
     # any classes we contain
-    def recursively_find_methods_matching(name)
-      res = local_methods_matching(name)
+    def recursively_find_methods_matching(name, is_class_method)
+      res = local_methods_matching(name, is_class_method)
       @inferior_classes.each do |c|
-        res.concat(c.recursively_find_methods_matching(name))
+        res.concat(c.recursively_find_methods_matching(name, is_class_method))
       end
       res
     end
@@ -80,10 +80,19 @@ module RI
 
     private
 
-    # Return a list of all our methods matching a given string
-    def local_methods_matching(name)
-      @class_methods.find_all {|m| m.name[name] } +
-                                                   @instance_methods.find_all {|m| m.name[name] }
+    # Return a list of all our methods matching a given string.
+    # Is +is_class_methods+ if 'nil', we don't care if the method
+    # is a class method or not, otherwise we only return
+    # those methods that match
+    def local_methods_matching(name, is_class_method)
+      list = case is_class_method
+             when nil then  @class_methods + @instance
+             when true then @class_methods
+             when false then @instance_methods
+             else fail "Unknown is_class_method"
+             end
+
+      list.find_all {|m| m.name[name]}
     end
   end
 
@@ -91,8 +100,8 @@ module RI
   # for methods searches all classes, not just itself
 
   class TopLevelEntry < ClassEntry
-    def methods_matching(name)
-      res = recursively_find_methods_matching(name)
+    def methods_matching(name, is_class_method)
+      res = recursively_find_methods_matching(name, is_class_method)
     end
 
     def full_name
diff --git a/lib/rdoc/ri/ri_descriptions.rb b/lib/rdoc/ri/ri_descriptions.rb
index e80b4ebe05..f99905719b 100644
--- a/lib/rdoc/ri/ri_descriptions.rb
+++ b/lib/rdoc/ri/ri_descriptions.rb
@@ -1,5 +1,9 @@
 require 'yaml'
 
+# Descriptions are created by RDoc (in ri_generator) and
+# written out in serialized form into the documentation
+# tree. ri then reads these to generate the documentation
+
 module RI
   Alias          = Struct.new(:old_name, :new_name)
   AliasName      = Struct.new(:name)
@@ -35,7 +39,8 @@ module RI
   
   class ClassDescription < Description
     
-    attr_accessor :method_list
+    attr_accessor :class_methods
+    attr_accessor :instance_methods
     attr_accessor :attributes
     attr_accessor :constants
     attr_accessor :superclass
diff --git a/lib/rdoc/ri/ri_formatter.rb b/lib/rdoc/ri/ri_formatter.rb
index 052ac87906..1e70529bfe 100644
--- a/lib/rdoc/ri/ri_formatter.rb
+++ b/lib/rdoc/ri/ri_formatter.rb
@@ -55,7 +55,7 @@ module RI
       txt.
           gsub(%r{<tt>(.*?)</tt>}) { "+#$1+" } .
           gsub(%r{<b>(.*?)</b>}) { "*#$1*" } .
-          gsub(%r{<i>(.*?)</i>}) { "_#$1_" } .
+          gsub(%r{<em>(.*?)</em>}) { "_#$1_" } .
           gsub(/&gt;/, '>').
           gsub(/&lt;/, '<').
           gsub(/&quot;/, '"').
diff --git a/lib/rdoc/ri/ri_reader.rb b/lib/rdoc/ri/ri_reader.rb
index f7e9e3074c..eb56d654fb 100644
--- a/lib/rdoc/ri/ri_reader.rb
+++ b/lib/rdoc/ri/ri_reader.rb
@@ -24,7 +24,7 @@ module RI
     def find_methods(name, is_class_method, namespaces)
       result = []
       namespaces.each do |ns|
-        result.concat ns.methods_matching(name)
+        result.concat ns.methods_matching(name, is_class_method)
       end
       result
     end
diff --git a/lib/rdoc/ri/ri_util.rb b/lib/rdoc/ri/ri_util.rb
index 07f79b1d62..5d14650fac 100644
--- a/lib/rdoc/ri/ri_util.rb
+++ b/lib/rdoc/ri/ri_util.rb
@@ -9,6 +9,8 @@ class NameDescriptor
 
   attr_reader :class_names
   attr_reader :method_name
+
+  # true and false have the obvious meaning. nil means we don't care
   attr_reader :is_class_method
 
   # arg may be
@@ -25,9 +27,9 @@ class NameDescriptor
 
   def initialize(arg)
     @class_names = []
-    separator = "."
+    separator = nil
 
-    tokens = arg.split(/\b/)
+    tokens = arg.split(/(\.|::|#)/)
 
     # Skip leading '::', '#' or '.', but remember it might
     # be a method name qualifier
@@ -57,7 +59,9 @@ class NameDescriptor
       if @method_name =~ /::|\.|#/ or !tokens.empty?
         raise RiError.new("Bad argument: #{arg}") 
       end
-      @is_class_method = separator == "::"
+      if separator
+        @is_class_method = separator == "::"
+      end
     end
   end
 end
diff --git a/lib/rdoc/ri/ri_writer.rb b/lib/rdoc/ri/ri_writer.rb
index 072b3acfea..70468cb1f5 100644
--- a/lib/rdoc/ri/ri_writer.rb
+++ b/lib/rdoc/ri/ri_writer.rb
@@ -28,7 +28,7 @@ module RI
     def add_method(class_desc, method_desc)
       dir = path_to_dir(class_desc.full_name)
       meth_file_name = File.join(dir, method_desc.name)
-      if method_desc.is_class_method
+      if method_desc.is_singleton
         meth_file_name += "-c.yaml"
       else
         meth_file_name += "-i.yaml"