rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/parser.rb

@@ -141,6 +141,7 @@ class RDoc::Parser
     return if parser == RDoc::Parser::Simple and ext_name !~ /txt|rdoc/
 
     parser
+  rescue Errno::EACCES
   end
 
   ##
@@ -201,7 +202,8 @@ class RDoc::Parser
 
     return unless markup
 
-    return RDoc::Parser::Ruby if markup == 'tomdoc'
+    # TODO Ruby should be returned only when the filename is correct
+    return RDoc::Parser::Ruby if %w[tomdoc markdown].include? markup
 
     markup = Regexp.escape markup
 
@@ -219,6 +221,7 @@ class RDoc::Parser
   def initialize top_level, file_name, content, options, stats
     @top_level = top_level
     @top_level.parser = self.class
+    @store = @top_level.store
 
     @file_name = file_name
     @content = content
@@ -236,7 +239,8 @@ end
 
 # simple must come first in order to show up last in the parsers list
 require 'rdoc/parser/simple'
+require 'rdoc/parser/c'
+require 'rdoc/parser/markdown'
 require 'rdoc/parser/rd'
 require 'rdoc/parser/ruby'
-require 'rdoc/parser/c'
 

data/lib/rdoc/parser/c.rb

@@ -1,3 +1,5 @@
+require 'tsort'
+
 ##
 # RDoc::Parser::C attempts to parse C extension files.  It looks for
 # the standard patterns that you find in extensions: <tt>rb_define_class,
@@ -54,6 +56,13 @@
 # [Document-const: +name+]
 #   Documentation for the named +rb_define_const+.
 #
+#   Constant values can be supplied on the first line of the comment like so:
+#
+#     /* 300: The highest possible score in bowling */
+#     rb_define_const(cFoo, "PERFECT", INT2FIX(300));
+#
+#   The value can contain internal colons so long as they are escaped with a \
+#
 # [Document-global: +name+]
 #   Documentation for the named +rb_define_global_const+
 #
@@ -118,27 +127,27 @@ class RDoc::Parser::C < RDoc::Parser
 
   attr_accessor :content
 
+  ##
+  # Dependencies from a missing enclosing class to the classes in
+  # missing_dependencies that depend upon it.
+
+  attr_reader :enclosure_dependencies
 
   ##
-  # Maps C variable names to names of ruby classes (andsingleton classes)
+  # Maps C variable names to names of ruby classes (and singleton classes)
 
   attr_reader :known_classes
 
   ##
-  # Maps C variable names to names of ruby singleton classes
+  # Classes found while parsing the C file that were not yet registered due to
+  # a missing enclosing class.  These are processed by do_missing
 
-  attr_reader :singleton_classes
+  attr_reader :missing_dependencies
 
   ##
-  # Resets cross-file state.  Call when parsing different projects that need
-  # separate documentation.
-
-  def self.reset
-    @@enclosure_classes = {}
-    @@known_bodies = {}
-  end
+  # Maps C variable names to names of ruby singleton classes
 
-  reset
+  attr_reader :singleton_classes
 
   ##
   # Prepare to parse a C file
@@ -151,6 +160,38 @@ class RDoc::Parser::C < RDoc::Parser
     @classes = {}
     @singleton_classes = {}
     @file_dir = File.dirname(@file_name)
+
+    # missing variable => [handle_class_module arguments]
+    @missing_dependencies = {}
+
+    # missing enclosure variable => [dependent handle_class_module arguments]
+    @enclosure_dependencies = Hash.new { |h, k| h[k] = [] }
+    @enclosure_dependencies.instance_variable_set :@missing_dependencies,
+                                                  @missing_dependencies
+
+    @enclosure_dependencies.extend TSort
+
+    def @enclosure_dependencies.tsort_each_node &block
+      each_key(&block)
+    rescue TSort::Cyclic => e
+      cycle_vars = e.message.scan(/"(.*?)"/).flatten
+
+      cycle = cycle_vars.sort.map do |var_name|
+        delete var_name
+
+        var_name, type, mod_name, = @missing_dependencies[var_name]
+
+        "#{type} #{mod_name} (#{var_name})"
+      end.join ', '
+
+      warn "Unable to create #{cycle} due to a cyclic class or module creation"
+
+      retry
+    end
+
+    def @enclosure_dependencies.tsort_each_child node, &block
+      fetch(node, []).each(&block)
+    end
   end
 
   ##
@@ -165,7 +206,7 @@ class RDoc::Parser::C < RDoc::Parser
       class_name = @known_classes[var_name]
 
       unless class_name then
-        @options.warn "Enclosing class/module %p for alias %s %s not known" % [
+        @options.warn "Enclosing class or module %p for alias %s %s is not known" % [
           var_name, new_name, old_name]
         next
       end
@@ -212,73 +253,26 @@ class RDoc::Parser::C < RDoc::Parser
   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|
-      handle_class_module(var_name, "module", class_name, nil, nil)
-    end
-
-    # The '.' lets us handle SWIG-generated files
-    @content.scan(/([\w\.]+)\s* = \s*rb_define_class\s*
-              \(
-                 \s*"(\w+)",
-                 \s*(\w+)\s*
-              \)/mx) do |var_name, class_name, parent|
-      handle_class_module(var_name, "class", class_name, parent, nil)
-    end
-
-    @content.scan(/([\w\.]+)\s* = \s*rb_struct_define_without_accessor\s*
-              \(
-                 \s*"(\w+)",  # Class name
-                 \s*(\w+),    # Parent class
-                 \s*\w+,      # Allocation function
-                 (\s*"\w+",)* # Attributes
-                 \s*NULL
-              \)/mx) do |var_name, class_name, parent|
-      handle_class_module(var_name, "class", class_name, parent, nil)
-    end
+  # Scans #content for boot_defclass
 
+  def do_boot_defclass
     @content.scan(/(\w+)\s*=\s*boot_defclass\s*\(\s*"(\w+?)",\s*(\w+?)\s*\)/) do
       |var_name, class_name, parent|
       parent = nil if parent == "0"
-      handle_class_module(var_name, "class", class_name, parent, nil)
+      handle_class_module(var_name, :class, class_name, parent, nil)
     end
+  end
 
-    @content.scan(/(\w+)\s* = \s*rb_define_module_under\s*
-              \(
-                 \s*(\w+),
-                 \s*"(\w+)"
-              \s*\)/mx) do |var_name, in_module, class_name|
-      handle_class_module(var_name, "module", class_name, nil, in_module)
-    end
-
-    @content.scan(/([\w\.]+)\s* =                  # var_name
-                   \s*rb_define_class_under\s*
-                   \(
-                     \s* (\w+),                    # under
-                     \s* "(\w+)",                  # class_name
-                     \s*
-                     (?:
-                       ([\w\*\s\(\)\.\->]+) |      # parent_name
-                       rb_path2class\("([\w:]+)"\) # path
-                     )
-                     \s*
-                   \)
-                  /mx) do |var_name, under, class_name, parent_name, path|
-      parent = path || parent_name
-
-      handle_class_module var_name, 'class', class_name, parent, under
-    end
+  ##
+  # Scans #content for rb_define_class, boot_defclass, rb_define_class_under
+  # and rb_singleton_class
 
-    @content.scan(/([\w\.]+)\s* = \s*rb_singleton_class\s*
-                  \(
-                    \s*(\w+)
-                  \s*\)/mx) do |sclass_var, class_var|
-      handle_singleton sclass_var, class_var
-    end
+  def do_classes
+    do_boot_defclass
+    do_define_class
+    do_define_class_under
+    do_singleton_class
+    do_struct_define_without_accessor
   end
 
   ##
@@ -309,8 +303,82 @@ class RDoc::Parser::C < RDoc::Parser
                   \)
                   \s*;%xm) do |consts|
       const = consts.first
+
       handle_constants 'const', 'mCurses', const, "UINT2NUM(#{const})"
     end
+
+    @content.scan(%r%
+                  \Wrb_file_const
+                  \s*\(
+                    \s*
+                    "([^"]+)",
+                    \s*
+                    (.*?)
+                    \s*
+                  \)
+                  \s*;%xm) do |name, value|
+      handle_constants 'const', 'rb_mFConst', name, value
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_class
+
+  def do_define_class
+    # The '.' lets us handle SWIG-generated files
+    @content.scan(/([\w\.]+)\s* = \s*rb_define_class\s*
+              \(
+                 \s*"(\w+)",
+                 \s*(\w+)\s*
+              \)/mx) do |var_name, class_name, parent|
+      handle_class_module(var_name, :class, class_name, parent, nil)
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_class_under
+
+  def do_define_class_under
+    @content.scan(/([\w\.]+)\s* =                  # var_name
+                   \s*rb_define_class_under\s*
+                   \(
+                     \s* (\w+),                    # under
+                     \s* "(\w+)",                  # class_name
+                     \s*
+                     (?:
+                       ([\w\*\s\(\)\.\->]+) |      # parent_name
+                       rb_path2class\("([\w:]+)"\) # path
+                     )
+                     \s*
+                   \)
+                  /mx) do |var_name, under, class_name, parent_name, path|
+      parent = path || parent_name
+
+      handle_class_module var_name, :class, class_name, parent, under
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_module
+
+  def do_define_module
+    @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do
+      |var_name, class_name|
+      handle_class_module(var_name, :module, class_name, nil, nil)
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_module_under
+
+  def do_define_module_under
+    @content.scan(/(\w+)\s* = \s*rb_define_module_under\s*
+              \(
+                 \s*(\w+),
+                 \s*"(\w+)"
+              \s*\)/mx) do |var_name, in_module, class_name|
+      handle_class_module(var_name, :module, class_name, nil, in_module)
+    end
   end
 
   ##
@@ -378,6 +446,54 @@ class RDoc::Parser::C < RDoc::Parser
     end
   end
 
+  def do_missing
+    return if @missing_dependencies.empty?
+
+    @enclosure_dependencies.tsort.each do |in_module|
+      arguments = @missing_dependencies.delete in_module
+
+      next unless arguments # dependency on existing class
+
+      handle_class_module(*arguments)
+    end
+  end
+
+  ##
+  # Scans #content for rb_define_module and rb_define_module_under
+
+  def do_modules
+    do_define_module
+    do_define_module_under
+  end
+
+  ##
+  # Scans #content for rb_singleton_class
+
+  def do_singleton_class
+    @content.scan(/([\w\.]+)\s* = \s*rb_singleton_class\s*
+                  \(
+                    \s*(\w+)
+                  \s*\)/mx) do |sclass_var, class_var|
+      handle_singleton sclass_var, class_var
+    end
+  end
+
+  ##
+  # Scans #content for struct_define_without_accessor
+
+  def do_struct_define_without_accessor
+    @content.scan(/([\w\.]+)\s* = \s*rb_struct_define_without_accessor\s*
+              \(
+                 \s*"(\w+)",  # Class name
+                 \s*(\w+),    # Parent class
+                 \s*\w+,      # Allocation function
+                 (\s*"\w+",)* # Attributes
+                 \s*NULL
+              \)/mx) do |var_name, class_name, parent|
+      handle_class_module(var_name, :class, class_name, parent, nil)
+    end
+  end
+
   ##
   # Finds the comment for an alias on +class_name+ from +new_name+ to
   # +old_name+
@@ -440,7 +556,7 @@ class RDoc::Parser::C < RDoc::Parser
              \s*(\([^)]*\))([^;]|$))%xm then
       comment = RDoc::Comment.new $1, @top_level
       body = $2
-      offset = $~.offset(2).first
+      offset, = $~.offset(2)
 
       comment.remove_private if comment
 
@@ -557,7 +673,7 @@ class RDoc::Parser::C < RDoc::Parser
   #    */
   #   VALUE cFoo = rb_define_class("Foo", rb_cObject);
 
-  def find_class_comment(class_name, class_mod)
+  def find_class_comment class_name, class_mod
     comment = nil
 
     if @content =~ %r%
@@ -569,10 +685,10 @@ class RDoc::Parser::C < RDoc::Parser
     elsif @content =~ %r%Document-(?:class|module):\s+#{class_name}\s*?
                          (?:<\s+[:,\w]+)?\n((?>.*?\*/))%xm then
       comment = "/*\n#{$1}"
-    elsif @content =~ %r%((?>/\*.*?\*/\s+))
+    elsif @content =~ %r%.*((?>/\*.*?\*/\s+))
                          ([\w\.\s]+\s* = \s+)?rb_define_(class|module).*?"(#{class_name})"%xm then
       comment = $1
-    elsif @content =~ %r%((?>/\*.*?\*/\s+))
+    elsif @content =~ %r%.*((?>/\*.*?\*/\s+))
                          ([\w\.\s]+\s* = \s+)?rb_define_(class|module)_under.*?"(#{class_name.split('::').last})"%xm then
       comment = $1
     else
@@ -681,24 +797,26 @@ class RDoc::Parser::C < RDoc::Parser
     parent_name = @known_classes[parent] || parent
 
     if in_module then
-      enclosure = @classes[in_module] || @@enclosure_classes[in_module]
+      enclosure = @classes[in_module] || @store.c_enclosure_classes[in_module]
 
       if enclosure.nil? and enclosure = @known_classes[in_module] then
-        enc_type = /^rb_m/ =~ in_module ? "module" : "class"
+        enc_type = /^rb_m/ =~ in_module ? :module : :class
         handle_class_module in_module, enc_type, enclosure, nil, nil
         enclosure = @classes[in_module]
       end
 
       unless enclosure then
-        @options.warn "Enclosing class/module '#{in_module}' for " \
-                      "#{type} #{class_name} not known"
+        @enclosure_dependencies[in_module] << var_name
+        @missing_dependencies[var_name] =
+          [var_name, type, class_name, parent, in_module]
+
         return
       end
     else
       enclosure = @top_level
     end
 
-    if type == "class" then
+    if type == :class then
       full_name = if RDoc::ClassModule === enclosure then
                     enclosure.full_name + "::#{class_name}"
                   else
@@ -726,7 +844,7 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     @classes[var_name] = cm
-    @@enclosure_classes[var_name] = cm
+    @store.c_enclosure_classes[var_name] = cm
     @known_classes[var_name] = cm.full_name
   end
 
@@ -748,7 +866,7 @@ class RDoc::Parser::C < RDoc::Parser
     class_obj = find_class var_name, class_name
 
     unless class_obj then
-      @options.warn "Enclosing class/module #{const_name.inspect} not known"
+      @options.warn 'Enclosing class or module %p is not known' % [const_name]
       return
     end
 
@@ -759,13 +877,9 @@ class RDoc::Parser::C < RDoc::Parser
     # "/* definition: comment */" form.  The literal ':' and '\' characters
     # can be escaped with a backslash.
     if type.downcase == 'const' then
-      elements = comment.text.split ':'
-
-      if elements.nil? or elements.empty? then
-        con = RDoc::Constant.new const_name, definition, comment
-      else
-        new_definition = elements[0..-2].join(':')
+      no_match, new_definition, new_comment = comment.text.split(/(\A.*):/)
 
+      if no_match and no_match.empty? then
         if new_definition.empty? then # Default to literal C definition
           new_definition = definition
         else
@@ -775,15 +889,13 @@ class RDoc::Parser::C < RDoc::Parser
 
         new_definition.sub!(/\A(\s+)/, '')
 
-        new_comment = if $1.nil? then
-                        elements.last.lstrip
-                      else
-                        "#{$1}#{elements.last.lstrip}"
-                      end
+        new_comment = "#{$1}#{new_comment.lstrip}"
 
         new_comment = RDoc::Comment.new new_comment, @top_level
 
         con = RDoc::Constant.new const_name, new_definition, new_comment
+      else
+        con = RDoc::Constant.new const_name, definition, comment
       end
     else
       con = RDoc::Constant.new const_name, definition, comment
@@ -833,10 +945,9 @@ class RDoc::Parser::C < RDoc::Parser
         file_name = File.join @file_dir, source_file
 
         if File.exist? file_name then
-          file_content = (@@known_bodies[file_name] ||= File.read(file_name))
+          file_content = File.read file_name
         else
-          @options.warn "unknown source #{source_file} for " \
-                        "#{meth_name} in #{@file_name}"
+          @options.warn "unknown source #{source_file} for #{meth_name} in #{@file_name}"
         end
       else
         file_content = @content
@@ -1011,7 +1122,11 @@ class RDoc::Parser::C < RDoc::Parser
 
   def scan
     remove_commented_out_lines
+
+    do_modules
     do_classes
+    do_missing
+
     do_constants
     do_methods
     do_includes