Add "Document-method:" capability

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

ChangeLog

@@ -1,3 +1,16 @@
+Sun Dec 28 01:35:35 2003  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/parsers/parse_c.rb (RDoc::C_Parser::find_body):
+	  Sometimes the Ruby source aliases two otherwise
+	  unrelated methods (for example Kernel#object_id and
+	  Kernel#hash are both the same C function). Provide a
+	  facility to allow the methods to be documented
+	  separately.
+
+Sun Dec 28 01:05:31 2003  Dave Thomas  <dave@pragprog.com>
+
+	* marshal.c, signal.c: RDoc collemts added by Elliott Hughes
+
 Sun Dec 28 00:48:47 2003  Dave Thomas  <dave@pragprog.com>
 
 	* lib/rdoc/parsers/parse_c.rb (RDoc::C_Parser::find_class_comment):

lib/rdoc/parsers/parse_c.rb

@@ -181,7 +181,9 @@ module RDoc
       @known_classes[var_name] = cm.full_name
     end
     
-    
+
+    ############################################################
+
     def find_class_comment(class_name, class_meth)
       comment = nil
       if @body =~ %r{((?>/\*.*?\*/\s+))
@@ -193,6 +195,8 @@ module RDoc
       class_meth.comment = mangle_comment(comment) if comment
     end
     
+    ############################################################
+
     def do_classes
       @body.scan(/(\w+)\s* = \s*rb_define_module\(\s*"(\w+)"\s*\)/mx) do 
         |var_name, class_name|
@@ -238,6 +242,7 @@ module RDoc
       
     end
     
+    ############################################################
     
     def do_methods
       @body.scan(/rb_define_(singleton_method|method|module_function)\(\s*(\w+),
@@ -271,6 +276,7 @@ module RDoc
       end
    end
 
+    ############################################################
 
     def handle_method(type, var_name, meth_name, meth_body, param_count)
       class_name = @known_classes[var_name] || var_name
@@ -301,6 +307,8 @@ module RDoc
       end
     end
     
+    ############################################################
+
     # Find the C code corresponding to a c method
     def find_body(meth_name, meth_obj)
       if @body =~ %r{((?>/\*.*?\*/\s+))(static\s+)?VALUE\s+#{meth_name}
@@ -315,6 +323,17 @@ module RDoc
           body_text = $&
         end
 
+        # The comment block may have been overridden with a
+        # 'Document-method' block. This happens in the interpreter
+        # when multiple methods are vectored through to the same
+        # C method but those methods are logically distinct (for
+        # example Kernel.hash and Kernel.object_id share the same
+        # implementation
+
+        override_comment = find_override_comment(meth_obj.name)
+        comment = override_comment if override_comment
+
+        # 
         # If the comment block contains a section that looks like
         #    call-seq:
         #        Array.new
@@ -332,9 +351,24 @@ module RDoc
         meth_obj.add_token(RubyToken::Token.new(1,1).set_text(body_text))
         meth_obj.comment = mangle_comment(comment)
         
+      else
+        $stderr.puts "No definition for #{meth_name}"
       end
     end
 
+    ############################################################
+
+    def find_override_comment(meth_name)
+      comment = nil
+      puts "Override #{meth_name}"
+      if @body =~ %r{Document-method:\s#{meth_name}.*?\n((?>.*?\*/))}m
+        comment = $1
+      end
+      comment
+    end
+
+    ############################################################
+
     # Look for includes of the form
     #     rb_include_module(rb_cArray, rb_mEnumerable);
     def do_includes
@@ -346,6 +380,8 @@ module RDoc
       end
     end
 
+    ############################################################
+
     # Remove the /*'s and leading asterisks from C comments
     
     def mangle_comment(comment)