RDoc::Parser::C - ri - phpman

= RDoc::Parser::C < RDoc::Parser

------------------------------------------------------------------------
= Includes:
RDoc::Text (from gem rdoc-7.2.0)

------------------------------------------------------------------------
= Extended by:
TSort (from gem rdoc-7.2.0)

(from gem rdoc-7.2.0)
------------------------------------------------------------------------
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(VALUE ary)
   {
       ary = rb_obj_dup(ary);
       rb_ary_flatten_bang(ary);
       return ary;
   }

   ...

   void
   Init_Array(void)
   {
     ...
     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.

  Constant values can be supplied on the first line of the comment like
  so:

    /* 300: The highest possible score in bowling */
    rb_define_const(cFoo, "PERFECT", INT2FIX(300));

  The value can contain internal colons so long as they are escaped with
  a \


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: ClassName::method_name:
  Documentation for a singleton method in the given class.  Use this
  when the method name alone is ambiguous.


Document-method: ClassName#method_name:
  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. ...
   */

  /*
   * Document-method: read_value
   *
   * 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.
   */
------------------------------------------------------------------------
= Class methods:

  new

= Instance methods:

  add_alias
  classes
  content
  do_aliases
  do_attrs
  do_boot_defclass
  do_classes_and_modules
  do_constants
  do_includes
  do_methods
  do_missing
  enclosure_dependencies
  find_alias_comment
  find_attr_comment
  find_body
  find_class
  find_class_comment
  find_const_comment
  find_modifiers
  find_override_comment
  gen_body_table
  gen_const_table
  handle_attr
  handle_class_module
  handle_constants
  handle_ifdefs_in
  handle_method
  handle_singleton
  known_classes
  load_variable_map
  look_for_directives_in
  missing_dependencies
  new_comment
  rb_scan_args
  remove_commented_out_lines
  scan
  singleton_classes
  top_level

= Attributes:

  attr_accessor content
  attr_reader classes
  attr_reader enclosure_dependencies
  attr_reader known_classes
  attr_reader missing_dependencies
  attr_reader singleton_classes
  attr_reader top_level