From bc8c73c42a552fcc1d414c3475c64099f5a246d6 Mon Sep 17 00:00:00 2001 From: dave Date: Tue, 16 Dec 2003 20:28:44 +0000 Subject: Put RDoc comments into array.c, and refine rdoc/ri to deal with stuff that arose git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5202 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- lib/rdoc/generators/ri_generator.rb | 57 +++++++++++++++++++++++++------------ lib/rdoc/parsers/parse_c.rb | 35 +++++++++++++++++++---- lib/rdoc/ri/ri_cache.rb | 31 +++++++++++++------- lib/rdoc/ri/ri_descriptions.rb | 7 ++++- lib/rdoc/ri/ri_formatter.rb | 2 +- lib/rdoc/ri/ri_reader.rb | 2 +- lib/rdoc/ri/ri_util.rb | 10 +++++-- lib/rdoc/ri/ri_writer.rb | 2 +- 8 files changed, 105 insertions(+), 41 deletions(-) (limited to 'lib') diff --git a/lib/rdoc/generators/ri_generator.rb b/lib/rdoc/generators/ri_generator.rb index db86d744af..375c534923 100644 --- a/lib/rdoc/generators/ri_generator.rb +++ b/lib/rdoc/generators/ri_generator.rb @@ -100,8 +100,6 @@ module Generators cls_desc.superclass = cls.superclass cls_desc.comment = markup(cls.comment) - cls_desc.method_list = method_list(cls) - cls_desc.attributes =cls.attributes.sort.map do |a| RI::Attribute.new(a.name, a.rw, markup(a.comment)) end @@ -114,16 +112,23 @@ module Generators RI::IncludedModule.new(i.name) end - methods = method_list(cls) + class_methods, instance_methods = method_list(cls) - cls_desc.method_list = methods.map do |m| + cls_desc.class_methods = class_methods.map do |m| + RI::MethodSummary.new(m.name) + end + cls_desc.instance_methods = instance_methods.map do |m| RI::MethodSummary.new(m.name) end @ri_writer.remove_class(cls_desc) @ri_writer.add_class(cls_desc) - methods.each do |m| + class_methods.each do |m| + generate_method_info(cls_desc, m) + end + + instance_methods.each do |m| generate_method_info(cls_desc, m) end end @@ -155,7 +160,8 @@ module Generators private - # return a list of methods that we'll be documenting + # return a list of class and instance methods that we'll be + # documenting def method_list(cls) list = cls.method_list @@ -164,22 +170,37 @@ module Generators m.visibility == :public || m.force_documentation end end - - list.sort + + c = [] + i = [] + list.sort.each do |m| + if m.singleton + c << m + else + i << m + end + end + return c,i end def params_of(method) - p = method.params.gsub(/\s*\#.*/, '') - p = p.tr("\n", " ").squeeze(" ") - p = "(" + p + ")" unless p[0] == ?( - - if (block = method.block_params) - block.gsub!(/\s*\#.*/, '') - block = block.tr("\n", " ").squeeze(" ") - if block[0] == ?( - block.sub!(/^\(/, '').sub!(/\)/, '') + params = method.params || "" + + if params =~ /^!verb!(.*)/m + p = $1 + else + p = params.gsub(/\s*\#.*/, '') + p = p.tr("\n", " ").squeeze(" ") + p = "(" + p + ")" unless p[0] == ?( + + if (block = method.block_params) + block.gsub!(/\s*\#.*/, '') + block = block.tr("\n", " ").squeeze(" ") + if block[0] == ?( + block.sub!(/^\(/, '').sub!(/\)/, '') + end + p << " {|#{block.strip}| ...}" end - p << " {|#{block.strip}| ...}" end p end diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb index 3d9d7a247f..3e8b48da34 100644 --- a/lib/rdoc/parsers/parse_c.rb +++ b/lib/rdoc/parsers/parse_c.rb @@ -153,7 +153,7 @@ module RDoc def remove_commented_out_lines @body.gsub!(%r{//.*rb_define_}, '//') end - + def handle_class_module(var_name, class_mod, class_name, parent, in_module) @known_classes[var_name] = class_name parent_name = @known_classes[parent] || parent @@ -162,7 +162,7 @@ module RDoc enclosure = @classes[in_module] unless enclosure $stderr.puts("Enclosing class/module '#{in_module}' for " + - class_mod + " #{class_name} not known") + "#{class_mod} #{class_name} not known") return end else @@ -175,10 +175,17 @@ module RDoc cm = enclosure.add_module(NormalModule, class_name) end cm.record_location(enclosure.toplevel) + find_class_comment(class_name, cm) @classes[var_name] = cm end + def find_class_comment(class_name, class_meth) + if @body =~ %r{((?>/\*.*?\*/\s+)) + (static\s+)?void\s+Init_#{class_name}\s*\(\)}xm + class_meth.comment = mangle_comment($1) + end + end def do_classes @body.scan(/(\w+)\s* = \s*rb_define_module\(\s*"(\w+)"\s*\)/mx) do @@ -224,14 +231,20 @@ module RDoc @body.scan(/rb_define_(singleton_method|method|module_function)\(\s*(\w+), \s*"([^"]+)", \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?, - \s*(-?\w+)\s*\)/xm) do + \s*(-?\w+)\s*\)/xm) do #" |type, var_name, meth_name, meth_body, param_count| + next if meth_name == "initialize_copy" + class_name = @known_classes[var_name] || var_name class_obj = @classes[var_name] if class_obj + if meth_name == "initialize" + meth_name = "new" + type = "singleton_method" + end meth_obj = AnyMethod.new("", meth_name) - meth_obj.singleton = type == "singleton_method" + meth_obj.singleton = type == "singleton_method" p_count = (Integer(param_count) rescue -1) @@ -265,7 +278,19 @@ module RDoc body_text = $& end - meth_obj.params = params + # If the comment block contains a section that looks like + # call-seq: + # Array.new + # Array.new(10) + # use it for the parameters + + if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '') + seq = $1 + seq.gsub!(/^\s*\*\s*/, '') + meth_obj.params = "!verb!" + seq + end + +# meth_obj.params = params meth_obj.start_collecting_tokens meth_obj.add_token(RubyToken::Token.new(1,1).set_text(body_text)) meth_obj.comment = mangle_comment(comment) diff --git a/lib/rdoc/ri/ri_cache.rb b/lib/rdoc/ri/ri_cache.rb index 4ca976c4b9..da2a7e47ff 100644 --- a/lib/rdoc/ri/ri_cache.rb +++ b/lib/rdoc/ri/ri_cache.rb @@ -56,16 +56,16 @@ module RI # return the list of local methods matching name # We're split into two because we need distinct behavior # when called from the toplevel - def methods_matching(name) - local_methods_matching(name) + def methods_matching(name, is_class_method) + local_methods_matching(name, is_class_method) end # Find methods matching 'name' in ourselves and in # any classes we contain - def recursively_find_methods_matching(name) - res = local_methods_matching(name) + def recursively_find_methods_matching(name, is_class_method) + res = local_methods_matching(name, is_class_method) @inferior_classes.each do |c| - res.concat(c.recursively_find_methods_matching(name)) + res.concat(c.recursively_find_methods_matching(name, is_class_method)) end res end @@ -80,10 +80,19 @@ module RI private - # Return a list of all our methods matching a given string - def local_methods_matching(name) - @class_methods.find_all {|m| m.name[name] } + - @instance_methods.find_all {|m| m.name[name] } + # Return a list of all our methods matching a given string. + # Is +is_class_methods+ if 'nil', we don't care if the method + # is a class method or not, otherwise we only return + # those methods that match + def local_methods_matching(name, is_class_method) + list = case is_class_method + when nil then @class_methods + @instance + when true then @class_methods + when false then @instance_methods + else fail "Unknown is_class_method" + end + + list.find_all {|m| m.name[name]} end end @@ -91,8 +100,8 @@ module RI # for methods searches all classes, not just itself class TopLevelEntry < ClassEntry - def methods_matching(name) - res = recursively_find_methods_matching(name) + def methods_matching(name, is_class_method) + res = recursively_find_methods_matching(name, is_class_method) end def full_name diff --git a/lib/rdoc/ri/ri_descriptions.rb b/lib/rdoc/ri/ri_descriptions.rb index e80b4ebe05..f99905719b 100644 --- a/lib/rdoc/ri/ri_descriptions.rb +++ b/lib/rdoc/ri/ri_descriptions.rb @@ -1,5 +1,9 @@ require 'yaml' +# Descriptions are created by RDoc (in ri_generator) and +# written out in serialized form into the documentation +# tree. ri then reads these to generate the documentation + module RI Alias = Struct.new(:old_name, :new_name) AliasName = Struct.new(:name) @@ -35,7 +39,8 @@ module RI class ClassDescription < Description - attr_accessor :method_list + attr_accessor :class_methods + attr_accessor :instance_methods attr_accessor :attributes attr_accessor :constants attr_accessor :superclass diff --git a/lib/rdoc/ri/ri_formatter.rb b/lib/rdoc/ri/ri_formatter.rb index 052ac87906..1e70529bfe 100644 --- a/lib/rdoc/ri/ri_formatter.rb +++ b/lib/rdoc/ri/ri_formatter.rb @@ -55,7 +55,7 @@ module RI txt. gsub(%r{(.*?)}) { "+#$1+" } . gsub(%r{(.*?)}) { "*#$1*" } . - gsub(%r{(.*?)}) { "_#$1_" } . + gsub(%r{(.*?)}) { "_#$1_" } . gsub(/>/, '>'). gsub(/</, '<'). gsub(/"/, '"'). diff --git a/lib/rdoc/ri/ri_reader.rb b/lib/rdoc/ri/ri_reader.rb index f7e9e3074c..eb56d654fb 100644 --- a/lib/rdoc/ri/ri_reader.rb +++ b/lib/rdoc/ri/ri_reader.rb @@ -24,7 +24,7 @@ module RI def find_methods(name, is_class_method, namespaces) result = [] namespaces.each do |ns| - result.concat ns.methods_matching(name) + result.concat ns.methods_matching(name, is_class_method) end result end diff --git a/lib/rdoc/ri/ri_util.rb b/lib/rdoc/ri/ri_util.rb index 07f79b1d62..5d14650fac 100644 --- a/lib/rdoc/ri/ri_util.rb +++ b/lib/rdoc/ri/ri_util.rb @@ -9,6 +9,8 @@ class NameDescriptor attr_reader :class_names attr_reader :method_name + + # true and false have the obvious meaning. nil means we don't care attr_reader :is_class_method # arg may be @@ -25,9 +27,9 @@ class NameDescriptor def initialize(arg) @class_names = [] - separator = "." + separator = nil - tokens = arg.split(/\b/) + tokens = arg.split(/(\.|::|#)/) # Skip leading '::', '#' or '.', but remember it might # be a method name qualifier @@ -57,7 +59,9 @@ class NameDescriptor if @method_name =~ /::|\.|#/ or !tokens.empty? raise RiError.new("Bad argument: #{arg}") end - @is_class_method = separator == "::" + if separator + @is_class_method = separator == "::" + end end end end diff --git a/lib/rdoc/ri/ri_writer.rb b/lib/rdoc/ri/ri_writer.rb index 072b3acfea..70468cb1f5 100644 --- a/lib/rdoc/ri/ri_writer.rb +++ b/lib/rdoc/ri/ri_writer.rb @@ -28,7 +28,7 @@ module RI def add_method(class_desc, method_desc) dir = path_to_dir(class_desc.full_name) meth_file_name = File.join(dir, method_desc.name) - if method_desc.is_class_method + if method_desc.is_singleton meth_file_name += "-c.yaml" else meth_file_name += "-i.yaml" -- cgit v1.2.3