From 47eea500020f55fddad93916de8a8079952a21db Mon Sep 17 00:00:00 2001 From: drbrain Date: Sun, 31 Dec 2006 21:27:31 +0000 Subject: [PATCH] Make RDoc accessible. Update constant value information. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@11445 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 5 + lib/rdoc/parsers/parse_c.rb | 237 +++++++++++++++++++----------------- 2 files changed, 131 insertions(+), 111 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4c83445959..9200bdc0c5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Mon Jan 1 06:13:11 2007 Eric Hodel + + * lib/rdoc/parsers/c_parser.rb: Make Rdoc accessible. Update constant + value information. + Mon Jan 1 06:13:11 2007 Eric Hodel * ext/bigdecimal/bigdecimal.c: Update constant comments to provide diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb index e4c4a4a0f5..7053fac7d5 100644 --- a/lib/rdoc/parsers/parse_c.rb +++ b/lib/rdoc/parsers/parse_c.rb @@ -1,97 +1,5 @@ - # 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 outomatically - # 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. - # */ - # - - - # Classes and modules built in to the interpreter. We need - # these to define superclasses of user objects +# Classes and modules built in to the interpreter. We need +# these to define superclasses of user objects require "rdoc/code_objects" require "rdoc/parsers/parserfactory" @@ -100,6 +8,9 @@ require "rdoc/rdoc" module RDoc + ## + # Ruby's built-in classes. + KNOWN_CLASSES = { "rb_cObject" => "Object", "rb_cArray" => "Array", @@ -159,10 +70,99 @@ module RDoc "rb_mGC" => "GC", "rb_mMath" => "Math", "rb_mProcess" => "Process" - } - # See rdoc/c_parse.rb + ## + # 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. + # */ + # class C_Parser @@ -220,8 +220,9 @@ module RDoc comment.sub!(/\/?\*--.*/m, '') end - # remove lines that are commented out that might otherwise get - # picked up when scanning for classes and methods + ## + # removes lines that are commented out that might otherwise get picked up + # when scanning for classes and methods def remove_commented_out_lines @body.gsub!(%r{//.*rb_define_}, '//') @@ -264,7 +265,6 @@ module RDoc @@enclosure_classes[var_name] = cm @known_classes[var_name] = cm.full_name end - ############################################################ @@ -429,7 +429,16 @@ module RDoc end end - ############################################################ + ## + # Adds constant comments. By providing some_value: at the start ofthe + # comment you can override the C value of the comment to give a friendly + # definition. + # + # /* 300: The perfect score in bowling */ + # rb_define_const(cFoo, "PERFECT", INT2FIX(300); + # + # Will override +INT2FIX(300)+ with the value +300+ in the output RDoc. + # Values may include quotes and escaped colons (\:). def handle_constants(type, var_name, const_name, definition) #@stats.num_constants += 1 @@ -473,7 +482,9 @@ module RDoc class_obj.add_constant(con) end - ########################################################### + ## + # Finds a comment matching +type+ and +const_name+ either above the + # comment or in the matching Document- section. def find_const_comment(type, const_name) if @body =~ %r{((?>^\s*/\*.*?\*/\s+)) @@ -637,13 +648,15 @@ module RDoc end - ################################################## - # - # If the comment block contains a section that looks like + ## + # If the comment block contains a section that looks like: + # # call-seq: # Array.new # Array.new(10) - # use it for the parameters + # + # use it for the parameters. + def find_modifiers(comment, meth_obj) if comment.sub!(/:nodoc:\s*^\s*\*?\s*$/m, '') or comment.sub!(/\A\/\*\s*:nodoc:\s*\*\/\Z/, '') @@ -666,10 +679,11 @@ module RDoc end end - ############################################################ - - # Look for includes of the form + ## + # Look for includes of the form: + # # rb_include_module(rb_cArray, rb_mEnumerable); + def do_includes @body.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m| if cls = @classes[c] @@ -679,8 +693,7 @@ module RDoc end end - ############################################################ - + ## # Remove the /*'s and leading asterisks from C comments def mangle_comment(comment) @@ -713,7 +726,8 @@ module RDoc end end - # Remove #ifdefs that would otherwise confuse us + ## + # Removes #ifdefs that would otherwise confuse us def handle_ifdefs_in(body) body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m) { $1 } @@ -722,3 +736,4 @@ module RDoc end end +