Class: RDocF95::C_Parser

Inherits:

Object

• Object
• RDocF95::C_Parser

Extended by:

ParserFactory

Defined in:

lib/rdoc-f95/parsers/parse_c.rb

Overview

We attempt to parse C extension files. Basically we look for the standard patterns that you find in extensions: rb_define_class, rb_define_method and so on. We also try 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.

C classes can be diagramed (see /tc/dl/ruby/ruby/error.c), and RDoc integrates C and Ruby source into one tree

The comment blocks may include special direcives:

Document-class: name

This comment block is documentation for the given class. Use this when the Init_xxx method is not named after the class.

Document-method: name

This comment documents the named method. Use when RDoc cannot automatically find the method from it’s declaration

call-seq: text up to an empty line

Because C source doesn’t give descripive names to Ruby-level parameters, you need to document the calling sequence explicitly

In additon, 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.
 */

Constant Summary

@@enclosure_classes =

{}

@@known_bodies =

{}

Instance Attribute Summary

• #progress ⇒ Object writeonly

  Sets the attribute progress.

Instance Method Summary

• #initialize(top_level, file_name, body, options, stats) ⇒ C_Parser constructor

  prepare to parse a C file.

• #scan ⇒ Object

  Extract the classes/modules and methods from a C file and return the corresponding top-level object.

Methods included from ParserFactory

alias_extension, can_parse, parse_files_matching, parser_for

Constructor Details

#initialize(top_level, file_name, body, options, stats) ⇒ C_Parser

prepare to parse a C file

# File 'lib/rdoc-f95/parsers/parse_c.rb', line 178

def initialize(top_level, file_name, body, options, stats)
  @known_classes = KNOWN_CLASSES.dup
  @options = options
  @body = handle_tab_width(handle_ifdefs_in(body))
  @stats   = stats
  @top_level = top_level
  @classes = Hash.new
  @file_dir = File.dirname(file_name)
  @progress = $stderr unless @options.quiet
end

Instance Attribute Details

#progress=(value) ⇒ Object

Sets the attribute progress

Parameters:

• value —

  the value to set the attribute progress to.

# File 'lib/rdoc-f95/parsers/parse_c.rb', line 169

def progress=(value)
  @progress = value
end

Instance Method Details

#scan ⇒ Object

Extract the classes/modules and methods from a C file and return the corresponding top-level object

# File 'lib/rdoc-f95/parsers/parse_c.rb', line 191

def scan
  remove_commented_out_lines
  do_classes
  do_constants
  do_methods
  do_includes
  do_aliases
  @top_level
end