rdoc 2.5.11 → 3.0

data/lib/rdoc/parser.rb

@@ -1,6 +1,6 @@
 require 'rdoc'
 require 'rdoc/code_objects'
-require 'rdoc/markup/preprocess'
+require 'rdoc/markup/pre_process'
 require 'rdoc/stats'
 
 ##
@@ -43,7 +43,15 @@ class RDoc::Parser
   @parsers = []
 
   class << self
+
+    ##
+    # A Hash that maps file exetensions regular expressions to parsers that
+    # will consume them.
+    #
+    # Use parse_files_matching to register a parser's file extensions.
+
     attr_reader :parsers
+
   end
 
   ##
@@ -62,34 +70,56 @@ class RDoc::Parser
     true
   end
 
-  def self.set_encoding(string)
-    if defined? Encoding then
-      if /coding[=:]\s*([^\s;]+)/i =~ string[%r"\A(?:#!.*\n)?.*\n"]
-        if enc = ::Encoding.find($1)
-          string.force_encoding(enc)
-        end
-      end
-    end
-  end
-
   ##
   # Determines if the file is a "binary" file which basically means it has
   # content that an RDoc parser shouldn't try to consume.
 
   def self.binary?(file)
+    return false if file =~ /\.(rdoc|txt)$/
+
     s = File.read(file, 1024) or return false
-    set_encoding(s)
-
-    if s[0, 2] == Marshal.dump('')[0, 2] then
-      true
-    elsif file =~ /erb\.rb$/ then
-      false
-    elsif s.scan(/<%|%>/).length >= 4 || s.index("\x00") then
-      true
-    elsif 0.respond_to? :fdiv then
-      s.count("^ -~\t\r\n").fdiv(s.size) > 0.3
-    else # HACK 1.8.6
-      (s.count("^ -~\t\r\n").to_f / s.size) > 0.3
+
+    have_encoding = s.respond_to? :encoding
+
+    if have_encoding then
+      return false if s.encoding != Encoding::ASCII_8BIT and s.valid_encoding?
+    end
+
+    return true if s[0, 2] == Marshal.dump('')[0, 2] or s.index("\x00")
+
+    if have_encoding then
+      s.force_encoding Encoding.default_external
+
+      not s.valid_encoding?
+    else
+      if 0.respond_to? :fdiv then
+        s.count("\x00-\x7F", "^ -~\t\r\n").fdiv(s.size) > 0.3
+      else # HACK 1.8.6
+        (s.count("\x00-\x7F", "^ -~\t\r\n").to_f / s.size) > 0.3
+      end
+    end
+  end
+
+  ##
+  # Processes common directives for CodeObjects for the C and Ruby parsers.
+  #
+  # Applies +directive+'s +value+ to +code_object+, if appropriate
+
+  def self.process_directive code_object, directive, value
+    case directive
+    when 'nodoc' then
+      code_object.document_self = nil # notify nodoc
+      code_object.document_children = value.downcase != 'all'
+    when 'doc' then
+      code_object.document_self = true
+      code_object.force_documentation = true
+    when 'yield', 'yields' then
+      # remove parameter &block
+      code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
+
+      code_object.block_params = value
+    when 'arg', 'args' then
+      code_object.params = value
     end
   end
 
@@ -154,6 +184,12 @@ class RDoc::Parser
     RDoc::Parser.parsers.unshift [regexp, self]
   end
 
+  ##
+  # Creates a new Parser storing +top_level+, +file_name+, +content+, 
+  # +options+ and +stats+ in instance variables.
+  #
+  # Usually invoked by +super+
+
   def initialize(top_level, file_name, content, options, stats)
     @top_level = top_level
     @file_name = file_name

data/lib/rdoc/parser/c.rb

@@ -3,9 +3,9 @@ require 'rdoc/parser/ruby'
 require 'rdoc/known_classes'
 
 ##
-# We attempt to parse C extension files. Basically we look for
+# RDoc::Parser::C attempts to parse C extension files.  It looks 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
+# rb_define_method</tt> and so on.  It tries to find the corresponding
 # C source for the methods and extract comments, but if we fail
 # we don't worry too much.
 #
@@ -49,13 +49,26 @@ require 'rdoc/known_classes'
 #
 # The comment blocks may include special directives:
 #
-# [Document-class: <i>name</i>]
-#   This comment block is documentation for the given class. Use this
-#   when the <tt>Init_xxx</tt> method is not named after the class.
+# [Document-class: +name+]
+#   Documentation for the named class.
 #
-# [Document-method: <i>name</i>]
-#   This comment documents the named method. Use when RDoc cannot
-#   automatically find the method from it's declaration
+# [Document-module: +name+]
+#   Documentation for the named module.
+#
+# [Document-const: +name+]
+#   Documentation for the named +rb_define_const+.
+#
+# [Document-global: +name+]
+#   Documentation for the named +rb_define_global_const+
+#
+# [Document-variable: +name+]
+#   Documentation for the named +rb_define_variable+
+#
+# [Document-method: +name+]
+#   Documentation for the named method.
+#
+# [Document-attr: +name+]
+#   Documentation for the named attribute.
 #
 # [call-seq:  <i>text up to an empty line</i>]
 #   Because C source doesn't give descripive names to Ruby-level parameters,
@@ -124,6 +137,9 @@ class RDoc::Parser::C < RDoc::Parser
     @file_dir = File.dirname(@file_name)
   end
 
+  ##
+  # Scans #content for rb_define_alias
+
   def do_aliases
     @content.scan(/rb_define_alias\s*\(
                    \s*(\w+),
@@ -145,6 +161,33 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Scans #content for rb_attr and rb_define_attr
+
+  def do_attrs
+    @content.scan(/rb_attr\s*\(
+                   \s*(\w+),
+                   \s*([\w"()]+),
+                   \s*([01]),
+                   \s*([01]),
+                   \s*\w+\);/xm) do |var_name, attr_name, read, write|
+      handle_attr var_name, attr_name, read, write
+    end
+
+    @content.scan(%r%rb_define_attr\(
+                             \s*([\w\.]+),
+                             \s*"([^"]+)",
+                             \s*(\d+),
+                             \s*(\d+)\s*\);
+                %xm) do |var_name, attr_name, read, write|
+      handle_attr var_name, attr_name, read, write
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_module, rb_define_class, boot_defclass,
+  # rb_define_module_under, rb_define_class_under and rb_singleton_class
+
   def do_classes
     @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do
       |var_name, class_name|
@@ -191,12 +234,16 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Scans #content for rb_define_variable, rb_define_readonly_variable,
+  # rb_define_const and rb_define_global_const
+
   def do_constants
     @content.scan(%r%\Wrb_define_
                    ( variable          |
                      readonly_variable |
                      const             |
-                     global_const      | )
+                     global_const        )
                \s*\(
                  (?:\s*(\w+),)?
                  \s*"(\w+)",
@@ -208,9 +255,7 @@ class RDoc::Parser::C < RDoc::Parser
   end
 
   ##
-  # Look for includes of the form:
-  #
-  #   rb_include_module(rb_cArray, rb_mEnumerable);
+  # Scans #content for rb_include_module
 
   def do_includes
     @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
@@ -221,6 +266,11 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Scans #content for rb_define_method, rb_define_singleton_method,
+  # rb_define_module_function, rb_define_private_method,
+  # rb_define_global_function and define_filetest_function
+
   def do_methods
     @content.scan(%r%rb_define_
                    (
@@ -234,8 +284,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, meth_body, param_count, source_file|
 
       # Ignore top-object and weird struct.c dynamic stuff
       next if var_name == "ruby_top_self"
@@ -248,18 +297,6 @@ class RDoc::Parser::C < RDoc::Parser
                     source_file)
     end
 
-    @content.scan(%r%rb_define_attr\(
-                             \s*([\w\.]+),
-                             \s*"([^"]+)",
-                             \s*(\d+),
-                             \s*(\d+)\s*\);
-                %xm) do |var_name, attr_name, attr_reader, attr_writer|
-      #var_name = "rb_cObject" if var_name == "rb_mKernel"
-      handle_attr(var_name, attr_name,
-                  attr_reader.to_i != 0,
-                  attr_writer.to_i != 0)
-    end
-
     @content.scan(%r%rb_define_global_function\s*\(
                              \s*"([^"]+)",
                              \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
@@ -280,23 +317,49 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
-  def find_alias_comment(class_name, new_name, old_name)
-    if content =~ %r%((?>/\*.*?\*/\s+))
-                     rb_define_alias\(\s*#{class_name}\s*,
-                                      \s*"#{new_name}"\s*,
-                                      \s*"#{old_name}"\s*\);%xm then
-      $1
-    else
-      ''
-    end
+  ##
+  # Finds the comment for an alias on +class_name+ from +new_name+ to
+  # +old_name+
+
+  def find_alias_comment class_name, new_name, old_name
+    content =~ %r%((?>/\*.*?\*/\s+))
+                  rb_define_alias\(\s*#{Regexp.escape class_name}\s*,
+                                   \s*"#{Regexp.escape new_name}"\s*,
+                                   \s*"#{Regexp.escape old_name}"\s*\);%xm
+
+    $1 || ''
   end
 
-  def find_attr_comment(attr_name)
+  ##
+  # Finds a comment for rb_define_attr, rb_attr or Document-attr.
+  #
+  # +var_name+ is the C class variable the attribute is defined on.
+  # +attr_name+ is the attribute's name.
+  #
+  # +read+ and +write+ are the read/write flags ('1' or '0').  Either both or
+  # neither must be provided.
+
+  def find_attr_comment var_name, attr_name, read = nil, write = nil
+    attr_name = Regexp.escape attr_name
+
+    rw = if read and write then
+           /\s*#{read}\s*,\s*#{write}\s*/xm
+         else
+           /.*?/m
+         end
+
     if @content =~ %r%((?>/\*.*?\*/\s+))
-                      rb_define_attr\((?:\s*(\w+),)?\s*
-                                      "#{attr_name}"\s*,.*?\)\s*;%xmi
+                      rb_define_attr\((?:\s*#{var_name},)?\s*
+                                      "#{attr_name}"\s*,
+                                      #{rw}\)\s*;%xm then
+      $1
+    elsif @content =~ %r%((?>/\*.*?\*/\s+))
+                         rb_attr\(\s*#{var_name}\s*,
+                                  \s*#{attr_name}\s*,
+                                  #{rw},.*?\)\s*;%xm then
       $1
-    elsif @content =~ %r%Document-attr:\s#{attr_name}\s*?\n((?>.*?\*/))%m
+    elsif @content =~ %r%Document-attr:\s#{attr_name}\s*?\n
+                         ((?>.*?\*/))%xm then
       $1
     else
       ''
@@ -314,7 +377,6 @@ class RDoc::Parser::C < RDoc::Parser
              \s*(\([^)]*\))([^;]|$))%xm then
       comment = $1
       body_text = $2
-      params = $3
 
       remove_private_comments comment if comment
 
@@ -353,24 +415,27 @@ class RDoc::Parser::C < RDoc::Parser
       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}" unless @options.quiet
+        warn "No definition for #{meth_name}" if @options.verbosity > 1
         return false
       end
-    else
-      # No body, but might still have an override comment
-      comment = find_override_comment(class_name, meth_obj.name)
+    else # No body, but might still have an override comment
+      comment = find_override_comment class_name, meth_obj.name
 
       if comment
-        find_modifiers(comment, meth_obj)
+        find_modifiers comment, meth_obj
         meth_obj.comment = strip_stars comment
       else
-        warn "No definition for #{meth_name}" unless @options.quiet
+        warn "No definition for #{meth_name}" if @options.verbosity > 1
         return false
       end
     end
+
     true
   end
 
+  ##
+  # Finds a RDoc::NormalClass or RDoc::NormalModule for +raw_name+
+
   def find_class(raw_name, name)
     unless @classes[raw_name]
       if raw_name =~ /^rb_m/
@@ -419,7 +484,7 @@ class RDoc::Parser::C < RDoc::Parser
         (static\s+)?
         void\s+
         Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)?\)%xmi then
-      comment = $1
+      comment = $1.sub(%r%Document-(?:class|module):\s+#{class_name}%, '')
     elsif @content =~ %r%Document-(?:class|module):\s+#{class_name}\s*?
                          (?:<\s+[:,\w]+)?\n((?>.*?\*/))%xm then
       comment = $1
@@ -456,30 +521,72 @@ class RDoc::Parser::C < RDoc::Parser
   end
 
   ##
-  # If the comment block contains a section that looks like:
+  # Handles modifiers in +comment+ and updates +meth_obj+ as appropriate.
   #
-  #    call-seq:
-  #        Array.new
-  #        Array.new(10)
+  # If <tt>:nodoc:</tt> is found, documentation on +meth_obj+ is suppressed.
   #
-  # use it for the parameters.
+  # If <tt>:yields:</tt> is followed by an argument list it is used for the
+  # #block_params of +meth_obj+.
+  #
+  # If the comment block contains a <tt>call-seq:</tt> section like:
+  #
+  #   call-seq:
+  #      ARGF.readlines(sep=$/)     -> array
+  #      ARGF.readlines(limit)      -> array
+  #      ARGF.readlines(sep, limit) -> array
+  #
+  #      ARGF.to_a(sep=$/)     -> array
+  #      ARGF.to_a(limit)      -> array
+  #      ARGF.to_a(sep, limit) -> array
+  #
+  # it is used for the parameters of +meth_obj+.
+
+  def find_modifiers comment, meth_obj
+    # we must handle situations like the above followed by an unindented first
+    # comment.  The difficulty is to make sure not to match lines starting
+    # with ARGF at the same indent, but that are after the first description
+    # paragraph.
+
+    if comment =~ /call-seq:(.*?[^\s\*].*?)^\s*\*?\s*$/m then
+      all_start, all_stop = $~.offset(0)
+      seq_start, seq_stop = $~.offset(1)
+
+      # we get the following lines that start with the leading word at the
+      # same indent, even if they have blank lines before
+      if $1 =~ /(^\s*\*?\s*\n)+^(\s*\*?\s*\w+)/m then
+        leading = $2 # ' *    ARGF' in the example above
+        re = %r%
+          \A(
+             (^\s*\*?\s*\n)+
+             (^#{Regexp.escape leading}.*?\n)+
+            )+
+          ^\s*\*?\s*$
+        %xm
+        if comment[seq_stop..-1] =~ re then
+          all_stop = seq_stop + $~.offset(0).last
+          seq_stop = seq_stop + $~.offset(1).last
+        end
+      end
 
-  def find_modifiers(comment, meth_obj)
-    if comment.sub!(/:nodoc:\s*^\s*\*?\s*$/m, '') or
-       comment.sub!(/\A\/\*\s*:nodoc:\s*\*\/\Z/, '') then
-      meth_obj.document_self = false
+      seq = comment[seq_start..seq_stop]
+      seq.gsub!(/^(\s*\*?\s*?)(\S|\n)/m, '\2')
+      comment.slice! all_start...all_stop
+      meth_obj.call_seq = seq
+    elsif comment.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then
+      meth_obj.call_seq = $1.strip
     end
 
-    if comment.sub!(/call-seq:(.*?)^\s*\*?\s*$/m, '') or
-       comment.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then
-      seq = $1
-      seq.gsub!(/^\s*\*\s*/, '')
-      meth_obj.call_seq = seq
+    if comment.sub!(/\s*:(nodoc|doc|yields?|args?):\s*(.*)/, '') then
+      RDoc::Parser.process_directive meth_obj, $1, $2
     end
   end
 
+  ##
+  # Finds a <tt>Document-method</tt> override for +meth_name+ in +class_name+
+
   def find_override_comment(class_name, meth_name)
     name = Regexp.escape(meth_name)
+
     if @content =~ %r%Document-method:\s+#{class_name}(?:\.|::|#)#{name}\s*?\n((?>.*?\*/))%m then
       $1
     elsif @content =~ %r%Document-method:\s#{name}\s*?\n((?>.*?\*/))%m then
@@ -487,26 +594,38 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
-  def handle_attr(var_name, attr_name, reader, writer)
+  ##
+  # Creates a new RDoc::Attr +attr_name+ on class +var_name+ that is either
+  # +read+, +write+ or both
+
+  def handle_attr(var_name, attr_name, read, write)
     rw = ''
-    rw << 'R' if reader
-    rw << 'W' if writer
+    rw << 'R' if '1' == read
+    rw << 'W' if '1' == write
 
     class_name = @known_classes[var_name]
 
     return unless class_name
 
-    class_obj = find_class(var_name, class_name)
+    class_obj = find_class var_name, class_name
+
+    return unless class_obj
 
-    if class_obj
-      comment = find_attr_comment(attr_name)
-      comment = strip_stars comment
-      att = RDoc::Attr.new '', attr_name, rw, comment
-      @stats.add_method att
-      class_obj.add_attribute(att)
-    end
+    comment = find_attr_comment var_name, attr_name
+    comment = strip_stars comment
+
+    name = attr_name.gsub(/rb_intern\("([^"]+)"\)/, '\1')
+
+    attr = RDoc::Attr.new '', name, rw, comment
+
+    class_obj.add_attribute attr
+    @stats.add_attribute attr
   end
 
+  ##
+  # Creates a new RDoc::NormalClass or RDoc::NormalModule based on +type+
+  # named +class_name+ in +parent+ which was assigned to the C +var_name+.
+
   def handle_class_module(var_name, type, class_name, parent, in_module)
     parent_name = @known_classes[parent] || parent
 
@@ -556,15 +675,14 @@ class RDoc::Parser::C < RDoc::Parser
   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.
+  # Adds constants.  By providing some_value: at the start of the 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 (\:).
+  # Will override <tt>INT2FIX(300)</tt> with the value +300+ in the output
+  # RDoc.  Values may include quotes and escaped colons (\:).
 
   def handle_constants(type, var_name, const_name, definition)
     class_name = @known_classes[var_name]
@@ -625,6 +743,11 @@ class RDoc::Parser::C < RDoc::Parser
     body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m, '\1')
   end
 
+  ##
+  # Adds an RDoc::AnyMethod +meth_name+ defined on a class or module assigned
+  # 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,
                     source_file = nil)
     singleton = false
@@ -640,9 +763,10 @@ class RDoc::Parser::C < RDoc::Parser
     class_obj = find_class var_name, class_name
 
     if class_obj then
-      if meth_name == "initialize" then
-        meth_name = "new"
+      if meth_name == 'initialize' then
+        meth_name = 'new'
         singleton = true
+        type = 'method' # force public
       end
 
       meth_obj = RDoc::AnyMethod.new '', meth_name
@@ -671,7 +795,8 @@ class RDoc::Parser::C < RDoc::Parser
         body = @content
       end
 
-      if find_body(class_name, meth_body, meth_obj, body) and meth_obj.document_self then
+      if find_body(class_name, meth_body, meth_obj, body) and
+         meth_obj.document_self then
         class_obj.add_method meth_obj
         @stats.add_method meth_obj
         meth_obj.visibility = :private if 'private_method' == type
@@ -679,19 +804,27 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  ##
+  # Registers a singleton class +sclass_var+ as a singleton of +class_var+
+
   def handle_singleton sclass_var, class_var
     class_name = @known_classes[class_var]
 
     @singleton_classes[sclass_var] = class_name
   end
 
+  ##
+  # Normalizes tabs in +body+
+
   def handle_tab_width(body)
     if /\t/ =~ body
       tab_width = @options.tab_width
       body.split(/\n/).map do |line|
-        1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
+        1 while line.gsub!(/\t+/) do
+          ' ' * (tab_width * $&.length - $`.length % tab_width)
+        end && $~
         line
-      end .join("\n")
+      end.join "\n"
     else
       body
     end
@@ -704,7 +837,7 @@ class RDoc::Parser::C < RDoc::Parser
   #    * :title: My Awesome Project
   #    */
   #
-  # This routine modifies it's parameter
+  # This routine modifies its parameter
 
   def look_for_directives_in(context, comment)
     preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
@@ -715,13 +848,14 @@ class RDoc::Parser::C < RDoc::Parser
         @options.main_page = param
         ''
       when 'title' then
-        @options.title = param
+        @options.default_title = param if @options.respond_to? :default_title=
         ''
       end
     end
 
     comment
   end
+
   ##
   # Removes lines that are commented out that might otherwise get picked up
   # when scanning for classes and methods
@@ -730,14 +864,17 @@ class RDoc::Parser::C < RDoc::Parser
     @content.gsub!(%r%//.*rb_define_%, '//')
   end
 
+  ##
+  # Removes private comments from +comment+
+
   def remove_private_comments(comment)
     comment.gsub!(/\/?\*--\n(.*?)\/?\*\+\+/m, '')
     comment.sub!(/\/?\*--\n.*/m, '')
   end
 
   ##
-  # Extract the classes/modules and methods from a C file and return the
-  # corresponding top-level object
+  # Extracts the classes, modules, methods, attributes, constants and aliases
+  # from a C file and returns an RDoc::TopLevel for this file
 
   def scan
     remove_commented_out_lines
@@ -746,6 +883,7 @@ class RDoc::Parser::C < RDoc::Parser
     do_methods
     do_includes
     do_aliases
+    do_attrs
     @top_level
   end