Merge pull request #846 from flavorjones/flavorjones-support-category-in-c-function-comments

feature: add support for `:category:` on C functions

Author: tenderlove

lib/rdoc/any_method.rb

@@ -26,6 +26,9 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   attr_accessor :c_function
 
+  # The section title of the method (if defined in a C file via +:category:+)
+  attr_accessor :section_title
+
   # Parameters for this method
 
   attr_accessor :params

lib/rdoc/markup/pre_process.rb

@@ -163,6 +163,8 @@ def handle_directive prefix, directive, param, code_object = nil,
       if RDoc::Context === code_object then
         section = code_object.add_section param
         code_object.temporary_section = section
+      elsif RDoc::AnyMethod === code_object then
+        code_object.section_title = param
       end
 
       blankline # ignore category if we're not on an RDoc::Context

lib/rdoc/parser/c.rb

@@ -1030,7 +1030,12 @@ def handle_method(type, var_name, meth_name, function, param_count,
 
 
         meth_obj.record_location @top_level
+
+        if meth_obj.section_title
+          class_obj.temporary_section = class_obj.add_section(meth_obj.section_title)
+        end
         class_obj.add_method meth_obj
+
         @stats.add_method meth_obj
         meth_obj.visibility = :private if 'private_method' == type
       end

test/rdoc/test_rdoc_parser_c.rb

@@ -1600,6 +1600,39 @@ def test_define_method
     assert_equal "Method Comment!   ", read_method.comment.text
     assert_equal "rb_io_s_read", read_method.c_function
     assert read_method.singleton
+    assert_nil read_method.section.title
+  end
+
+  def test_define_method_with_category
+    content = <<-EOF
+/* :category: Awesome Methods
+   Method Comment!
+ */
+static VALUE
+rb_io_s_read(argc, argv, io)
+    int argc;
+    VALUE *argv;
+    VALUE io;
+{
+}
+
+void
+Init_IO(void) {
+    /*
+     * a comment for class Foo on rb_define_class
+     */
+    VALUE rb_cIO = rb_define_class("IO", rb_cObject);
+    rb_define_singleton_method(rb_cIO, "read", rb_io_s_read, -1);
+}
+    EOF
+
+    klass = util_get_class content, 'rb_cIO'
+    read_method = klass.method_list.first
+    assert_equal "read", read_method.name
+    assert_equal "Method Comment!", read_method.comment.text.strip
+    assert_equal "rb_io_s_read", read_method.c_function
+    assert read_method.singleton
+    assert_equal "Awesome Methods", read_method.section.title
   end
 
   def test_define_method_dynamically