In Files

  • rdoc/parsers/parse_c.rb

Parent

Methods

Files

Class/Module Index [+]

Quicksearch

RDoc::C_Parser

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. ...

/*

   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.
  /

Attributes

progress[RW]

Public Class Methods

new(top_level, file_name, body, options, stats) click to toggle source

prepare to parse a C file

 
               # File rdoc/parsers/parse_c.rb, line 177
def initialize(top_level, file_name, body, options, stats)
  @known_classes = KNOWN_CLASSES.dup
  @body = handle_tab_width(handle_ifdefs_in(body))
  @options = options
  @stats   = stats
  @top_level = top_level
  @classes = Hash.new
  @file_dir = File.dirname(file_name)
  @progress = $stderr unless options.quiet
end
            

Public Instance Methods

scan() click to toggle source

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

 
               # File rdoc/parsers/parse_c.rb, line 190
def scan
  remove_commented_out_lines
  do_classes
  do_constants
  do_methods
  do_includes
  do_aliases
  @top_level
end
            

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

blog comments powered by Disqus