[ ruby-Patches-7569 ] RDoc patch for multiple classes and/or modules within C extensions

Patches item #7569, was opened at 2007-01-04 13:09
You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1700&aid=7569&group_id=426

Category: Ruby1.8
Group: None
Status: Open
Resolution: None
Priority: 3
Submitted By: Daniel Berger (djberg96)
Assigned to: Nobody (None)
Summary: RDoc patch for multiple classes and/or modules within C extensions

Initial Comment:
Hi,

As it stands now, if you want to document multiple classes or modules within the same source file you must use the 'Document-class' or 'Document-module' directives in a clunky, standalone fashion.  The following patch allows you to document a class or module in the same manner that you would document a method, constant or attribute, i.e. with a comment immediately prior to rb_define_class, rb_define_module, rb_define_class_under or rb_define_module_under.

If a user puts a comment above the "Init_xxx" line, then that comment still has priority, and so this patch is also backwards compatible.

This patch is against 1.8.5p12. It's a little on the ugly side as a result of Ruby's 1.8.x regex engine lack of support for positive lookbehind.

In addition, I've attached a sample C source file that contains a sampling of the sorts of styles I see and use for rb_define_class, etc, so you can see the results when you run rdoc over it.

If accepted, I'll followup with a patch for the text comments at the top of the parse_c.rb file regarding multiple classes and the 'Document-class' directive, etc.

This patch can most likely be refactored for 1.9, where positive lookbehind should enable a single extended regex, instead of the split + scan approach I had to take here.

Regards,

Dan

--- parse_c.orig        Thu Jan  4 11:25:41 2007
+++ parse_c.rb  Thu Jan  4 12:31:46 2007
@@ -271,6 +271,20 @@
         comment = $1
       elsif @body =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m
         comment = $2
+      else
+        if @body =~ /rb_define_class|rb_define_module/m
+          class_name = class_name.split("::").last
+          array = []
+          @body.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index{ |line, index|
+            array[index] = line
+            if line =~ /rb_define_(class|module).*?"(\w+?)"/m
+              if class_name == $2
+                comment = array[index-1]
+                break
+              end
+            end
+          }
+        end
       end
       class_meth.comment = mangle_comment(comment) if comment
     end

----------------------------------------------------------------------

You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1700&aid=7569&group_id=426