[ ruby-Patches-7499 ] RDoc patch that fixes rb_const_define output

Patches item #7499, was opened at 2006-12-30 05:23
You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1700&aid=7499&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 that fixes rb_const_define output

Initial Comment:
Hi,

The current RDoc behavior for handling rb_const_define is not ideal.  For example, if you have a code snippet like this:

/* The perfect score in bowling */
rb_const_define(cFoo, "PERFECT", INT2FIX(MAX_BOWLING_VALUE));

You'll end up seeing this in the generated HTML file:

PERFECT = INT2FIX(MAX_BOWLING_VALUE) The perfect score in bowling

When I really want to see this:

PERFECT = 300 The perfect score in bowling

While I could explicitly state the value in the comment, that still leaves the ugly "INT2FIX(MAX_BOWLING_VALUE)" as the definition for an end user to see.  The attached patch fixes that by allowing the user to specify a value manually within the comment using a "value: comment" form.  Literal ':' can be escaped with the '\' (backslash) character, if needed.

The patch is backwards compatible, i.e. it will simply default to the current behavior where no comments, or comments not in the 'value:comment' form, are found.

Below is the patch.  Attached is a simple C file that you can run "rdoc foo.c" over to view the generated output to see how it looks. It covers every case of rb_define_const that I've ever used or seen, but please feel free to try to break it. :)

C:\rubyVC8\lib\ruby\1.8\rdoc\parsers>diff -u parse_c.rb parse_c.new
--- parse_c.rb  Wed Aug 23 03:23:12 2006
+++ parse_c.new Sat Dec 30 05:02:57 2006
@@ -442,7 +442,27 @@

       comment = find_const_comment(type, const_name)

-      con = Constant.new(const_name, definition, mangle_comment(comment))
+      # In the case of rb_define_const, the definition and comment are in
+      # "/* definition: comment */" form.  The literal ':' and '\' characters
+      # can be escaped with a backslash.
+      if type.downcase == 'const'
+         elements = mangle_comment(comment).split(':')
+         if elements.nil? || elements.empty?
+            con = Constant.new(const_name, definition, mangle_comment(comment))
+         else
+            new_definition = elements[0..-2].join(':')
+            if new_definition.empty? # Default to literal C definition
+               new_definition = definition
+            else
+               new_definition.gsub!("\:", ":")
+               new_definition.gsub!("\\", "\")
+            end
+            con = Constant.new(const_name, new_definition, elements.last)
+         end
+      else
+         con = Constant.new(const_name, definition, mangle_comment(comment))
+      end
+
       class_obj.add_constant(con)
     end

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

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