← Back
Editing: cdesc-C_Parser.yaml
--- !ruby/object:RI::ClassDescription attributes: - !ruby/object:RI::Attribute comment: name: progress rw: RW class_methods: - !ruby/object:RI::MethodSummary name: new comment: - !ruby/struct:SM::Flow::P body: "We attempt to parse C extension files. Basically we look for the standard patterns that you find in extensions: <tt>rb_define_class, rb_define_method</tt> 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." - !ruby/struct:SM::Flow::P body: "The comments associated with a Ruby method are extracted from the C comment block associated with the routine that <em>implements</em> that method, that is to say the method whose name is given in the <tt>rb_define_method</tt> call. For example, you might write:" - !ruby/struct:SM::Flow::VERB body: " /*\n * Returns a new array that is a one-dimensional flattening of this\n * array (recursively). That is, for every element that is an array,\n * extract its elements into the new array.\n *\n * s = [ 1, 2, 3 ] #=> [1, 2, 3]\n * t = [ 4, 5, 6, [7, 8] ] #=> [4, 5, 6, [7, 8]]\n * a = [ s, t, 9, 10 ] #=> [[1, 2, 3], [4, 5, 6, [7, 8]], 9, 10]\n * a.flatten #=> [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]\n */\n static VALUE\n rb_ary_flatten(ary)\n VALUE ary;\n {\n ary = rb_obj_dup(ary);\n rb_ary_flatten_bang(ary);\n return ary;\n }\n\n ...\n\n void\n Init_Array()\n {\n ...\n rb_define_method(rb_cArray, "flatten", rb_ary_flatten, 0);\n" - !ruby/struct:SM::Flow::P body: 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. - !ruby/struct:SM::Flow::P body: C classes can be diagrammed (see /tc/dl/ruby/ruby/error.c), and RDoc integrates C and Ruby source into one tree - !ruby/struct:SM::Flow::P body: "The comment blocks may include special directives:" - !ruby/object:SM::Flow::LIST contents: - !ruby/struct:SM::Flow::LI label: "Document-class: <i>name</i>" body: This comment block is documentation for the given class. Use this when the <tt>Init_xxx</tt> method is not named after the class. - !ruby/struct:SM::Flow::LI label: "Document-method: <i>name</i>" body: This comment documents the named method. Use when RDoc cannot automatically find the method from it's declaration - !ruby/struct:SM::Flow::LI label: "call-seq: <i>text up to an empty line</i>" body: Because C source doesn't give descriptive names to Ruby-level parameters, you need to document the calling sequence explicitly type: :LABELED - !ruby/struct:SM::Flow::P body: 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 - !ruby/struct:SM::Flow::VERB body: " rb_define_method(....); // in: filename\n" - !ruby/struct:SM::Flow::P body: As an example, we might have an extension that defines multiple classes in its Init_xxx method. We could document them using - !ruby/struct:SM::Flow::VERB body: " /*\n * Document-class: MyClass\n *\n * Encapsulate the writing and reading of the configuration\n * file. ...\n */\n\n /*\n * Document-method: read_value\n *\n * call-seq:\n * cfg.read_value(key) -> value\n * cfg.read_value(key} { |key| } -> value\n *\n * Return the value corresponding to <tt>key</tt> from the configuration.\n * In the second form, if the key isn't found, invoke the\n * block and return its value.\n */\n" constants: [] full_name: RDoc::C_Parser includes: [] instance_methods: - !ruby/object:RI::MethodSummary name: do_aliases - !ruby/object:RI::MethodSummary name: do_classes - !ruby/object:RI::MethodSummary name: do_constants - !ruby/object:RI::MethodSummary name: do_includes - !ruby/object:RI::MethodSummary name: do_methods - !ruby/object:RI::MethodSummary name: find_attr_comment - !ruby/object:RI::MethodSummary name: find_body - !ruby/object:RI::MethodSummary name: find_class - !ruby/object:RI::MethodSummary name: find_class_comment - !ruby/object:RI::MethodSummary name: find_const_comment - !ruby/object:RI::MethodSummary name: find_modifiers - !ruby/object:RI::MethodSummary name: find_override_comment - !ruby/object:RI::MethodSummary name: handle_attr - !ruby/object:RI::MethodSummary name: handle_class_module - !ruby/object:RI::MethodSummary name: handle_constants - !ruby/object:RI::MethodSummary name: handle_ifdefs_in - !ruby/object:RI::MethodSummary name: handle_method - !ruby/object:RI::MethodSummary name: handle_tab_width - !ruby/object:RI::MethodSummary name: mangle_comment - !ruby/object:RI::MethodSummary name: progress - !ruby/object:RI::MethodSummary name: remove_commented_out_lines - !ruby/object:RI::MethodSummary name: remove_private_comments - !ruby/object:RI::MethodSummary name: scan - !ruby/object:RI::MethodSummary name: warn name: C_Parser superclass: Object
Save File
Cancel