rdoc 3.4 → 3.5

data/History.txt

@@ -1,4 +1,27 @@
-=== 3.4
+=== 3.5 / 2010-01-29
+
+* Minor enhancements
+  * RDoc::Parser::C looks for rb_scan_args and fills in RDoc::AnyMethod#params
+    appropriately.  This may provide useful information if the author did not
+    provide a call-seq.
+  * RDoc::Parser::C now records the function name for methods implemented in
+    C.
+  * RDoc now records file and byte offset information for methods.
+* Bug fixes
+  * Locations of module aliases are now recorded.
+  * RDoc::Parser::C finds method bodies better now.
+  * Fixed further locations where output encoding was not preserved.  Bug #11
+    by Vít Ondruch, RubyForge bug #28791 by Dzmitry Prakapenka.
+  * Fixed display of numeric lists on the index page and file pages.  Bug #12
+    by tobijk.
+  * Skip TestRDocOptions#test_check_files on windows until a windows-specific
+    test can be created.  RubyForge bug #28821 by Usaku Nakamura.
+  * Fixed line-height of headings in method and alias descriptions.  RubyForge
+    Bug #2770 by Adam Avilla
+  * Relaxed RDoc::Parser::Ruby#remove_private_comments to consume more dashes
+    as older versions once did.  Bug #7 by Claus Folke Brobak.
+
+=== 3.4 / 2010-01-06
 
 * Minor enhancements
   * RDoc::RDoc#document may now be called with an RDoc::Options instance.

data/lib/rdoc.rb

@@ -95,7 +95,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.4'
+  VERSION = '3.5'
 
   ##
   # Method visibilities

data/lib/rdoc/any_method.rb

@@ -13,6 +13,11 @@ class RDoc::AnyMethod < RDoc::MethodAttr
 
   attr_accessor :dont_rename_initialize
 
+  ##
+  # The C function that implements this method (if it was defined in a C file)
+
+  attr_accessor :c_function
+
   ##
   # Different ways to call this method
 
@@ -31,8 +36,9 @@ class RDoc::AnyMethod < RDoc::MethodAttr
   def initialize text, name
     super
 
+    @c_function = nil
     @dont_rename_initialize = false
-    @token_stream           = nil
+    @token_stream = nil
   end
 
   ##

data/lib/rdoc/code_object.rb

@@ -60,11 +60,23 @@ class RDoc::CodeObject
 
   attr_reader :force_documentation
 
+  ##
+  # Line in #file where this CodeObject was defined
+
+  attr_accessor :line
+
   ##
   # Hash of arbitrary metadata for this CodeObject
 
   attr_reader :metadata
 
+  ##
+  # Offset in #file where this CodeObject was defined
+  #--
+  # TODO character or byte?
+
+  attr_accessor :offset
+
   ##
   # Our parent CodeObject
 

data/lib/rdoc/context.rb

@@ -439,10 +439,13 @@ class RDoc::Context < RDoc::CodeObject
     # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
     # (this is a #ifdef: should be handled by the C parser)
     known = @constants_hash[constant.name]
-    if known
-      #$stderr.puts "\nconstant #{constant.name} already registered"
+
+    if known then
       known.comment = constant.comment if known.comment.empty?
-      known.value = constant.value if known.value.nil? or known.value.strip.empty?
+
+      known.value = constant.value if
+        known.value.nil? or known.value.strip.empty?
+
       known.is_alias_for ||= constant.is_alias_for
     else
       @constants_hash[constant.name] = constant
@@ -494,9 +497,10 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Adds an alias from +from+ (a class or module) to +name+.
+  # Adds an alias from +from+ (a class or module) to +name+ which was defined
+  # in +file+.
 
-  def add_module_alias from, name
+  def add_module_alias from, name, file
     return from if @done_documenting
 
     to_name = child_name(name)
@@ -518,7 +522,8 @@ class RDoc::Context < RDoc::CodeObject
     # HACK: register a constant for this alias:
     # constant value and comment will be updated after,
     # when the Ruby parser adds the constant
-    const = RDoc::Constant.new(name, nil, '')
+    const = RDoc::Constant.new name, nil, ''
+    const.record_location file
     const.is_alias_for = from
     add_constant const
 

data/lib/rdoc/generator/template/darkfish/rdoc.css

@@ -97,6 +97,11 @@ body.file p {
   margin: 1em 0;
 }
 
+.indexpage ol,
+.file #documentation ol {
+  line-height: 160%;
+}
+
 .indexpage ul,
 .file #documentation ul {
   line-height: 160%;
@@ -110,6 +115,20 @@ body.file p {
 .indexpage li,
 .file #documentation li {
   padding-left: 20px;
+}
+
+.indexpage ol,
+.file #documentation ol {
+  margin-left: 20px;
+}
+
+.indexpage ol > li,
+.file #documentation ol > li {
+  padding-left: 0;
+}
+
+.indexpage ul > li,
+.file #documentation ul > li {
   background: url(images/bullet_black.png) no-repeat left 4px;
 }
 .indexpage li.module {
@@ -389,9 +408,14 @@ ul.link-list .type {
 #documentation .method-description,
 #documentation .aliases {
   margin: 0 20px;
-  line-height: 1.2em;
   color: #666;
 }
+
+#documentation .method-description p,
+#documentation .aliases p {
+  line-height: 1.2em;
+}
+
 #documentation .aliases {
   padding-top: 4px;
   font-style: italic;

data/lib/rdoc/parser/c.rb

@@ -285,7 +285,7 @@ class RDoc::Parser::C < RDoc::Parser
                      \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
                      \s*(-?\w+)\s*\)
                    (?:;\s*/[*/]\s+in\s+(\w+?\.[cy]))?
-                 %xm) do |type, var_name, meth_name, meth_body, param_count, source_file|
+                 %xm) do |type, var_name, meth_name, function, param_count, source_file|
 
       # Ignore top-object and weird struct.c dynamic stuff
       next if var_name == "ruby_top_self"
@@ -294,7 +294,7 @@ class RDoc::Parser::C < RDoc::Parser
       next if var_name == "argf"   # it'd be nice to handle this one
 
       var_name = "rb_cObject" if var_name == "rb_mKernel"
-      handle_method(type, var_name, meth_name, meth_body, param_count,
+      handle_method(type, var_name, meth_name, function, param_count,
                     source_file)
     end
 
@@ -303,18 +303,19 @@ class RDoc::Parser::C < RDoc::Parser
                              \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
                              \s*(-?\w+)\s*\)
                 (?:;\s*/[*/]\s+in\s+(\w+?\.[cy]))?
-                %xm) do |meth_name, meth_body, param_count, source_file|
-      handle_method("method", "rb_mKernel", meth_name,
-                    meth_body, param_count, source_file)
+                %xm) do |meth_name, function, param_count, source_file|
+      handle_method("method", "rb_mKernel", meth_name, function, param_count,
+                    source_file)
     end
 
     @content.scan(/define_filetest_function\s*\(
                      \s*"([^"]+)",
                      \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
-                     \s*(-?\w+)\s*\)/xm) do |meth_name, meth_body, param_count|
+                     \s*(-?\w+)\s*\)/xm) do |meth_name, function, param_count|
 
-      handle_method("method", "rb_mFileTest", meth_name, meth_body, param_count)
-      handle_method("singleton_method", "rb_cFile", meth_name, meth_body, param_count)
+      handle_method("method", "rb_mFileTest", meth_name, function, param_count)
+      handle_method("singleton_method", "rb_cFile", meth_name, function,
+                    param_count)
     end
   end
 
@@ -370,21 +371,20 @@ class RDoc::Parser::C < RDoc::Parser
   ##
   # Find the C code corresponding to a Ruby method
 
-  def find_body(class_name, meth_name, meth_obj, body, quiet = false)
-    case body
+  def find_body class_name, meth_name, meth_obj, file_content, quiet = false
+    case file_content
     when %r%((?>/\*.*?\*/\s*)?)
             ((?:(?:static|SWIGINTERN)\s+)?
              (?:intern\s+)?VALUE\s+#{meth_name}
-             \s*(\([^)]*\))([^;]|$))%xm then
+             \s*(\(.*?\))([^;]|$))%xm then
       comment = $1
-      body_text = $2
+      body = $2
+      offset = $~.offset(2).first
 
       remove_private_comments comment if comment
 
-      # see if we can find the whole body
-
-      re = Regexp.escape(body_text) + '[^(]*^\{.*?^\}'
-      body_text = $& if /#{re}/m =~ body
+      # try to find the whole body
+      body = $& if /#{Regexp.escape body}[^(]*?\{.*?^\}/m =~ file_content
 
       # The comment block may have been overridden with a 'Document-method'
       # block. This happens in the interpreter when multiple methods are
@@ -400,38 +400,53 @@ class RDoc::Parser::C < RDoc::Parser
       #meth_obj.params = params
       meth_obj.start_collecting_tokens
       tk = RDoc::RubyToken::Token.new nil, 1, 1
-      tk.set_text body_text
+      tk.set_text body
       meth_obj.add_token tk
       meth_obj.comment = strip_stars comment
-    when %r%((?>/\*.*?\*/\s*))^\s*(\#\s*define\s+#{meth_name}\s+(\w+))%m
+      meth_obj.offset  = offset
+      meth_obj.line    = file_content[0, offset].count("\n") + 1
+
+      body
+    when %r%((?>/\*.*?\*/\s*))^\s*(\#\s*define\s+#{meth_name}\s+(\w+))%m then
       comment = $1
-      body_text = $2
-      find_body class_name, $3, meth_obj, body, true
+      body = $2
+      offset = $~.offset(2).first
+
+      find_body class_name, $3, meth_obj, file_content, true
       find_modifiers comment, meth_obj
 
       meth_obj.start_collecting_tokens
       tk = RDoc::RubyToken::Token.new nil, 1, 1
-      tk.set_text body_text
+      tk.set_text body
       meth_obj.add_token tk
       meth_obj.comment = strip_stars(comment) + meth_obj.comment.to_s
-    when %r%^\s*\#\s*define\s+#{meth_name}\s+(\w+)%m
-      unless find_body(class_name, $1, meth_obj, body, true)
-        warn "No definition for #{meth_name}" if @options.verbosity > 1
-        return false
-      end
+      meth_obj.offset  = offset
+      meth_obj.line    = file_content[0, offset].count("\n") + 1
+
+      body
+    when %r%^\s*\#\s*define\s+#{meth_name}\s+(\w+)%m then
+      # with no comment we hope the aliased definition has it and use it's
+      # definition
+
+      body = find_body(class_name, $1, meth_obj, file_content, true)
+
+      return body if body
+
+      warn "No definition for #{meth_name}" if @options.verbosity > 1
+      false
     else # No body, but might still have an override comment
       comment = find_override_comment class_name, meth_obj.name
 
-      if comment
+      if comment then
         find_modifiers comment, meth_obj
         meth_obj.comment = strip_stars comment
+
+        ''
       else
         warn "No definition for #{meth_name}" if @options.verbosity > 1
-        return false
+        false
       end
     end
-
-    true
   end
 
   ##
@@ -751,7 +766,7 @@ class RDoc::Parser::C < RDoc::Parser
   # to +var_name+.  +type+ is the type of method definition function used.
   # +singleton_method+ and +module_function+ create a singleton method.
 
-  def handle_method(type, var_name, meth_name, meth_body, param_count,
+  def handle_method(type, var_name, meth_name, function, param_count,
                     source_file = nil)
     singleton = false
     class_name = @known_classes[var_name]
@@ -773,34 +788,36 @@ class RDoc::Parser::C < RDoc::Parser
       end
 
       meth_obj = RDoc::AnyMethod.new '', meth_name
+      meth_obj.c_function = function
       meth_obj.singleton =
         singleton || %w[singleton_method module_function].include?(type)
 
       p_count = Integer(param_count) rescue -1
 
-      if p_count < 0 then
-        meth_obj.params = "(*args)"
-      elsif p_count == 0
-        meth_obj.params = "()"
-      else
-        params = (1..p_count).map { |i| "p#{i}" }.join(', ')
-        meth_obj.params = "(#{params})"
-      end
-
       if source_file then
         file_name = File.join @file_dir, source_file
 
         if File.exist? file_name then
-          body = (@@known_bodies[file_name] ||= File.read(file_name))
+          file_content = (@@known_bodies[file_name] ||= File.read(file_name))
         else
           warn "unknown source #{source_file} for #{meth_name} in #{@file_name}"
         end
       else
-        body = @content
+        file_content = @content
       end
 
-      if find_body(class_name, meth_body, meth_obj, body) and
-         meth_obj.document_self then
+      body = find_body class_name, function, meth_obj, file_content
+
+      if body and meth_obj.document_self then
+        meth_obj.params = if p_count < -1 then # -2 is Array
+                            '(*args)'
+                          elsif p_count == -1 then # argc, argv
+                            rb_scan_args body
+                          else
+                            "(#{(1..p_count).map { |i| "p#{i}" }.join ', '})"
+                          end
+
+
         meth_obj.record_location @top_level
         class_obj.add_method meth_obj
         @stats.add_method meth_obj
@@ -861,6 +878,90 @@ class RDoc::Parser::C < RDoc::Parser
     comment
   end
 
+  ##
+  # Extracts parameters from the +method_body+ and returns a method
+  # parameter string.  Follows 1.9.3dev's scan-arg-spec, see README.EXT
+
+  def rb_scan_args method_body
+    method_body =~ /rb_scan_args\((.*?)\)/m
+    return '(*args)' unless $1
+
+    $1.split(/,/)[2] =~ /"(.*?)"/ # format argument
+    format = $1.split(//)
+
+    lead = opt = trail = 0
+
+    if format.first =~ /\d/ then
+      lead = $&.to_i
+      format.shift
+      if format.first =~ /\d/ then
+        opt = $&.to_i
+        format.shift
+        if format.first =~ /\d/ then
+          trail = $&.to_i
+          format.shift
+          block_arg = true
+        end
+      end
+    end
+
+    if format.first == '*' and not block_arg then
+      var = true
+      format.shift
+      if format.first =~ /\d/ then
+        trail = $&.to_i
+        format.shift
+      end
+    end
+
+    if format.first == ':' then
+      hash = true
+      format.shift
+    end
+
+    if format.first == '&' then
+      block = true
+      format.shift
+    end
+
+    # if the format string is not empty there's a bug in the C code, ignore it
+
+    args = []
+    position = 1
+
+    (1...(position + lead)).each do |index|
+      args << "p#{index}"
+    end
+
+    position += lead
+
+    (position...(position + opt)).each do |index|
+      args << "p#{index} = v#{index}"
+    end
+
+    position += opt
+
+    if var then
+      args << '*args'
+      position += 1
+    end
+
+    (position...(position + trail)).each do |index|
+      args << "p#{index}"
+    end
+
+    position += trail
+
+    if hash then
+      args << "p#{position} = {}"
+      position += 1
+    end
+
+    args << '&block' if block
+
+    "(#{args.join ', '})"
+  end
+
   ##
   # Removes lines that are commented out that might otherwise get picked up
   # when scanning for classes and methods