RDoc::Parser::C

RDoc::Parser::C attempts to parse C extension files. It looks for the standard patterns that you find in extensions: rb_define_class, rb_define_method and so on. It tries to find the corresponding C source for the methods and extract comments, but if we fail we don't worry too much.

The comments associated with a Ruby method are extracted from the C comment block associated with the routine that implements that method, that is to say the method whose name is given in the rb_define_method call. For example, you might write:

  Returns a new array that is a one-dimensional flattening of this
  array (recursively). That is, for every element that is an array,
  extract its elements into the new array.

     s = [ 1, 2, 3 ]           #=> [1, 2, 3]
     t = [ 4, 5, 6, [7, 8] ]   #=> [4, 5, 6, [7, 8]]
     a = [ s, t, 9, 10 ]       #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]
     a.flatten                 #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

static VALUE
rb_ary_flatten(ary)
    VALUE ary;
{
    ary = rb_obj_dup(ary);
    rb_ary_flatten_bang(ary);
    return ary;
}

...

void
Init_Array()
{
  ...
  rb_define_method(rb_cArray, "flatten", rb_ary_flatten, 0);

Here RDoc will determine from the rb_define_method line that there's a method called “flatten” in class Array, and will look for the implementation in the method rb_ary_flatten. It will then use the comment from that method in the HTML output. This method must be in the same source file as the rb_define_method.

The comment blocks may include special directives:

Document-class: name: Documentation for the named class.
Document-module: name: Documentation for the named module.
Document-const: name: Documentation for the named rb_define_const.
Document-global: name: Documentation for the named rb_define_global_const
Document-variable: name: Documentation for the named rb_define_variable
Document-method: method_name: Documentation for the named method. Use this when the method name is unambiguous.
Document-method: <tt>ClassName::method_name<tt>: Documentation for a singleton method in the given class. Use this when the method name alone is ambiguous.
Document-method: <tt>ClassName#method_name<tt>: Documentation for a instance method in the given class. Use this when the method name alone is ambiguous.
Document-attr: name: Documentation for the named attribute.
call-seq: text up to an empty line: Because C source doesn't give descriptive names to Ruby-level parameters, you need to document the calling sequence explicitly

In addition, RDoc assumes by default that the C method implementing a Ruby function is in the same source file as the rb_define_method call. If this isn't the case, add the comment:

rb_define_method(....);  // in filename

As an example, we might have an extension that defines multiple classes in its Init_xxx method. We could document them using

   Document-class:  MyClass

   Encapsulate the writing and reading of the configuration
   file. ...

/*

   call-seq:
     cfg.read_value(key)            -> value
     cfg.read_value(key} { |key| }  -> value

   Return the value corresponding to +key+ from the configuration.
   In the second form, if the key isn't found, invoke the
   block and return its value.
  /

Methods

D

do_aliases,
do_attrs,
do_classes,
do_constants,
do_includes,
do_methods

F

find_alias_comment,
find_attr_comment,
find_body,
find_class,
find_class_comment,
find_const_comment,
find_modifiers,
find_override_comment

H

handle_attr,
handle_class_module,
handle_constants,
handle_ifdefs_in,
handle_method,
handle_singleton,
handle_tab_width

L

look_for_directives_in

N

R

rb_scan_args,
remove_commented_out_lines,
remove_private_comments,
reset

S

scan

Included Modules

RDoc::Text

Attributes

[RW]	content	C file the parser is parsing
[R]	known_classes	Maps C variable names to names of ruby classes (andsingleton classes)
[R]	singleton_classes	Maps C variable names to names of ruby singleton classes

Class Public methods

new(top_level, file_name, content, options, stats) Link

Prepare to parse a C file

Class RDoc::Parser::C < RDoc::Parser