rdoc 2.2.1 → 2.3.0

data/lib/rdoc/markup/to_html_crossref.rb

@@ -7,38 +7,30 @@ require 'rdoc/markup/to_html'
 
 class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
-  attr_accessor :context
-
+  ##
   # Regular expressions to match class and method references.
-  # 
-  # 1.) There can be a '\' in front of text to suppress
-  #     any cross-references (note, however, that the single '\'
-  #     is written as '\\\\' in order to escape it twice, once
-  #     in the Ruby String literal and once in the regexp).
-  # 2.) There can be a '::' in front of class names to reference
-  #     from the top-level namespace.
-  # 3.) The method can be followed by parenthesis,
-  #     which may or may not have things inside (this
-  #     apparently is allowed for Fortran 95, but I also think that this
-  #     is a good idea for Ruby, as it is very reasonable to want to
-  #     reference a call with arguments).
+  #
+  # 1) There can be a '\' in front of text to suppress any cross-references
+  # 2) There can be a '::' in front of class names to reference from the
+  #    top-level namespace.
+  # 3) The method can be followed by parenthesis which may
   #
   # NOTE: In order to support Fortran 95 properly, the [A-Z] below
   # should be changed to [A-Za-z].  This slows down rdoc significantly,
   # however, and the Fortran 95 support is broken in any case due to
   # the return in handle_special_CROSSREF if the token consists
   # entirely of lowercase letters.
-  #
-  # The markup/cross-referencing engine needs a rewrite for
-  # Fortran 95 to be supported properly.
+
   CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'
   METHOD_REGEXP_STR = '(\w+[!?=]?)(?:\([\.\w+\*\/\+\-\=\<\>]*\))?'
 
+  ##
   # Regular expressions matching text that should potentially have
-  # cross-reference links generated are passed to add_special.
-  # Note that these expressions are meant to pick up text for which
-  # cross-references have been suppressed, since the suppression
-  # characters are removed by the code that is triggered.
+  # cross-reference links generated are passed to add_special.  Note that
+  # these expressions are meant to pick up text for which cross-references
+  # have been suppressed, since the suppression characters are removed by the
+  # code that is triggered.
+
   CROSSREF_REGEXP = /(
                       # A::B::C.meth
                       #{CLASS_REGEXP_STR}[\.\#]#{METHOD_REGEXP_STR}
@@ -72,8 +64,14 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
                       )/x
 
   ##
-  # We need to record the html path of our caller so we can generate
-  # correct relative paths for any hyperlinks that we find
+  # RDoc::Generator::Context for generating references
+
+  attr_accessor :context
+
+  ##
+  # Creates a new crossref resolver that generates links relative to +context+
+  # which lives at +from_path+ in the generated files.  '#' characters on
+  # references are removed unless +show_hash+ is true.
 
   def initialize(from_path, context, show_hash)
     raise ArgumentError, 'from_path cannot be nil' if from_path.nil?
@@ -89,19 +87,18 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
   end
 
   ##
-  # We're invoked when any text matches the CROSSREF pattern
-  # (defined in MarkUp). If we fine the corresponding reference,
-  # generate a hyperlink. If the name we're looking for contains
-  # no punctuation, we look for it up the module/class chain. For
-  # example, HyperlinkHtml is found, even without the Generator::
-  # prefix, because we look for it in module Generator first.
+  # We're invoked when any text matches the CROSSREF pattern (defined in
+  # MarkUp).  If we find the corresponding reference, generate a hyperlink.
+  # If the name we're looking for contains no punctuation, we look for it up
+  # the module/class chain.  For example, HyperlinkHtml is found, even without
+  # the Generator:: prefix, because we look for it in module Generator first.
 
   def handle_special_CROSSREF(special)
     name = special.text
 
     # This ensures that words entirely consisting of lowercase letters will
-    # not have cross-references generated (to suppress lots of
-    # erroneous cross-references to "new" in text, for instance)
+    # not have cross-references generated (to suppress lots of erroneous
+    # cross-references to "new" in text, for instance)
     return name if name =~ /\A[a-z]*\z/
 
     return @seen[name] if @seen.include? name

data/lib/rdoc/options.rb

@@ -1,13 +1,14 @@
-# We handle the parsing of options, and subsequently as a singleton
-# object to be queried for option values
-
-require "rdoc/ri/paths"
 require 'optparse'
 
+require 'rdoc/ri/paths'
+
+##
+# RDoc::Options handles the parsing and storage of options
+
 class RDoc::Options
 
   ##
-  # Should the output be placed into a single file
+  # Should the output be placed into a single file?
 
   attr_reader :all_one_file
 
@@ -22,9 +23,9 @@ class RDoc::Options
   attr_reader :css
 
   ##
-  # Should diagrams be drawn
+  # Should diagrams be drawn?
 
-  attr_reader :diagram
+  attr_accessor :diagram
 
   ##
   # Files matching this pattern will be excluded
@@ -42,7 +43,7 @@ class RDoc::Options
   attr_accessor :extra_accessors
 
   ##
-  # Should we draw fileboxes in diagrams
+  # Should we draw fileboxes in diagrams?
 
   attr_reader :fileboxes
 
@@ -65,14 +66,14 @@ class RDoc::Options
   # Formatter to mark up text with
 
   attr_accessor :formatter
-  
+
   ##
-  # image format for diagrams
+  # Image format for diagrams
 
   attr_reader :image_format
 
   ##
-  # Include line numbers in the source listings
+  # Include line numbers in the source listings?
 
   attr_reader :include_line_numbers
 
@@ -103,7 +104,7 @@ class RDoc::Options
   attr_accessor :op_name
 
   ##
-  # Are we promiscuous about showing module contents across multiple files
+  # Are we promiscuous about showing module contents across multiple files?
 
   attr_reader :promiscuous
 
@@ -113,7 +114,7 @@ class RDoc::Options
   attr_reader :rdoc_include
 
   ##
-  # Include private and protected methods in the output
+  # Include private and protected methods in the output?
 
   attr_accessor :show_all
 
@@ -128,7 +129,7 @@ class RDoc::Options
   attr_reader :tab_width
 
   ##
-  # template to be used when generating output
+  # Template to be used when generating output
 
   attr_reader :template
 
@@ -154,16 +155,16 @@ class RDoc::Options
 
   attr_reader :webcvs
 
-  def initialize(generators = {}) # :nodoc:
+  def initialize # :nodoc:
+    require 'rdoc/rdoc'
     @op_dir = "doc"
     @op_name = nil
     @show_all = false
     @main_page = nil
     @merge = false
     @exclude = []
-    @generators = generators
-    @generator_name = 'html'
-    @generator = @generators[@generator_name]
+    @generators = RDoc::RDoc::GENERATORS
+    @generator = RDoc::Generator::Darkfish
     @rdoc_include = []
     @title = nil
     @template = nil
@@ -210,6 +211,8 @@ Usage: #{opt.program_name} [options] [names...]
   How RDoc generates output depends on the output formatter being used, and on
   the options you give.
 
+  - Darkfish is an improved, frameless HTML output by Michael Granger.
+
   - HTML output is normally produced into a number of separate files
     (one per class, module, and file, along with various indices).
     These files will appear in the directory given by the --op
@@ -327,8 +330,10 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
+      generator_text = @generators.keys.map { |name| "  #{name}" }.sort
+
       opt.on("--fmt=FORMAT", "--format=FORMAT", "-f", @generators.keys,
-             "Set the output formatter.") do |value|
+             "Set the output formatter.  One of:", *generator_text) do |value|
         @generator_name = value.downcase
         setup_generator
       end
@@ -629,7 +634,7 @@ Usage: #{opt.program_name} [options] [names...]
 
   def check_files
     @files.each do |f|
-      stat = File.stat f
+      stat = File.stat f rescue next
       raise RDoc::Error, "file '#{f}' not readable" unless stat.readable?
     end
   end

data/lib/rdoc/parser.rb

@@ -68,7 +68,12 @@ class RDoc::Parser
 
   def self.binary?(file)
     s = (File.read(file, File.stat(file).blksize) || "").split(//)
-    ((s.size - s.grep(" ".."~").size) / s.size.to_f) > 0.30
+
+    if s.size > 0 then
+      ((s.size - s.grep(" ".."~").size) / s.size.to_f) > 0.30
+    else
+      false
+    end
   end
   private_class_method :binary?
 
@@ -81,7 +86,7 @@ class RDoc::Parser
     #
     # The default parser should *NOT* parse binary files.
     #
-    if parser == RDoc::Parser::Simple then
+    if parser == RDoc::Parser::Simple && file_name !~ /\.(txt|rdoc)$/ then
       if binary? file_name then
         return nil
       end
@@ -106,6 +111,9 @@ class RDoc::Parser
 
     parser = can_parse file_name
 
+    # This method must return a parser.
+    parser ||= RDoc::Parser::Simple
+
     parser.new top_level, file_name, body, options, stats
   end
 

data/lib/rdoc/parser/c.rb

@@ -1,4 +1,5 @@
 require 'rdoc/parser'
+require 'rdoc/parser/ruby'
 require 'rdoc/known_classes'
 
 ##
@@ -95,8 +96,21 @@ class RDoc::Parser::C < RDoc::Parser
 
   parse_files_matching(/\.(?:([CcHh])\1?|c([+xp])\2|y)\z/)
 
-  @@enclosure_classes = {}
-  @@known_bodies = {}
+  ##
+  # C file the parser is parsing
+
+  attr_accessor :content
+
+  ##
+  # Resets cross-file state.  Call when parsing different projects that need
+  # separate documentation.
+
+  def self.reset
+    @@enclosure_classes = {}
+    @@known_bodies = {}
+  end
+
+  reset
 
   ##
   # Prepare to parse a C file
@@ -123,7 +137,7 @@ class RDoc::Parser::C < RDoc::Parser
   end
 
   def do_classes
-    @content.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do 
+    @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
@@ -269,12 +283,13 @@ class RDoc::Parser::C < RDoc::Parser
 
   def find_body(class_name, meth_name, meth_obj, body, quiet = false)
     case body
-    when %r"((?>/\*.*?\*/\s*)*)(?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{meth_name}
-            \s*(\([^)]*\))([^;]|$)"xm
-      comment, params = $1, $2
-      body_text = $&
+    when %r"((?>/\*.*?\*/\s*))((?:(?:static|SWIGINTERN)\s+)?(?:intern\s+)?VALUE\s+#{meth_name}
+            \s*(\([^)]*\))([^;]|$))"xm
+      comment = $1
+      body_text = $2
+      params = $3
 
-      remove_private_comments(comment) if comment
+      remove_private_comments comment if comment
 
       # see if we can find the whole body
 
@@ -287,15 +302,15 @@ class RDoc::Parser::C < RDoc::Parser
       # distinct (for example Kernel.hash and Kernel.object_id share the same
       # implementation
 
-      override_comment = find_override_comment(class_name, meth_obj.name)
+      override_comment = find_override_comment class_name, meth_obj.name
       comment = override_comment if override_comment
 
-      find_modifiers(comment, meth_obj) if comment
+      find_modifiers comment, meth_obj if comment
 
 #        meth_obj.params = params
       meth_obj.start_collecting_tokens
-      meth_obj.add_token(RDoc::RubyToken::Token.new(1,1).set_text(body_text))
-      meth_obj.comment = mangle_comment(comment)
+      meth_obj.add_token RDoc::RubyToken::Token.new(1,1).set_text(body_text)
+      meth_obj.comment = mangle_comment comment
     when %r{((?>/\*.*?\*/\s*))^\s*\#\s*define\s+#{meth_name}\s+(\w+)}m
       comment = $1
       find_body(class_name, $2, meth_obj, body, true)
@@ -364,25 +379,18 @@ class RDoc::Parser::C < RDoc::Parser
 
   def find_class_comment(class_name, class_meth)
     comment = nil
+
     if @content =~ %r{((?>/\*.*?\*/\s+))
                    (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then
       comment = $1
-    elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
+    elsif @content =~ %r{Document-(?:class|module):\s+#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m then
+      comment = $1
+    elsif @content =~ %r{((?>/\*.*?\*/\s+))
+                         ([\w\.\s]+\s* = \s+)?rb_define_(class|module).*?"(#{class_name})"}xm then
       comment = $1
-    else
-      if @content =~ /rb_define_(class|module)/m then
-        class_name = class_name.split("::").last
-        comments = []
-        @content.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index do |chunk, index|
-          comments[index] = chunk
-          if chunk =~ /rb_define_(class|module).*?"(#{class_name})"/m then
-            comment = comments[index-1]
-            break
-          end
-        end
-      end
     end
-    class_meth.comment = mangle_comment(comment) if comment
+
+    class_meth.comment = mangle_comment comment if comment
   end
 
   ##
@@ -424,7 +432,7 @@ class RDoc::Parser::C < RDoc::Parser
 
   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
+    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
       $1
@@ -491,9 +499,10 @@ class RDoc::Parser::C < RDoc::Parser
       @stats.add_module cm
     end
 
-    cm.record_location(enclosure.toplevel)
+    cm.record_location enclosure.toplevel
+
+    find_class_comment cm.full_name, cm
 
-    find_class_comment(cm.full_name, cm)
     @classes[var_name] = cm
     @@enclosure_classes[var_name] = cm
     @known_classes[var_name] = cm.full_name

data/lib/rdoc/parser/f95.rb

@@ -295,7 +295,7 @@ class RDoc::Parser::F95 < RDoc::Parser
 
         @stats.add_module f9x_module
 
-        f9x_comment = COMMENTS_ARE_UPPER ? 
+        f9x_comment = COMMENTS_ARE_UPPER ?
           find_comments(pre_comment.join("\n"))  + "\n" + module_trailing :
             module_trailing + "\n" + find_comments(module_code.sub(/^.*$\n/i, ''))
         f9x_module.comment = f9x_comment
@@ -320,8 +320,8 @@ class RDoc::Parser::F95 < RDoc::Parser
         program_code = module_program_code
         program_trailing = module_program_trailing
         # progress "p" # HACK what stats thingy does this correspond to?
-        program_comment = COMMENTS_ARE_UPPER ? 
-          find_comments(pre_comment.join("\n")) + "\n" + program_trailing : 
+        program_comment = COMMENTS_ARE_UPPER ?
+          find_comments(pre_comment.join("\n")) + "\n" + program_trailing :
             program_trailing + "\n" + find_comments(program_code.sub(/^.*$\n/i, ''))
         program_comment = "\n\n= <i>Program</i> <tt>#{program_name}</tt>\n\n" \
                           + program_comment
@@ -410,12 +410,12 @@ class RDoc::Parser::F95 < RDoc::Parser
     # This information is used when "add_method" and
     # "set_visibility_for" are called.
     #
-    visibility_default, visibility_info = 
+    visibility_default, visibility_info =
               parse_visibility(remaining_lines.join("\n"), visibility, container)
     @@public_methods.concat visibility_info
     if visibility_default == :public
       if !cascaded_modules_list.empty?
-        cascaded_modules = 
+        cascaded_modules =
           Attr.new("Cascaded Modules",
                    "Imported modules all of whose components are published again",
                    "",
@@ -499,7 +499,7 @@ class RDoc::Parser::F95 < RDoc::Parser
       type_trailing = find_comments($4)
       next if type_trailing =~ /^:nodoc:/
       type_visibility = $1
-      type_comment = COMMENTS_ARE_UPPER ? 
+      type_comment = COMMENTS_ARE_UPPER ?
         find_comments($~.pre_match) + "\n" + type_trailing :
           type_trailing + "\n" + find_comments(type_code.sub(/^.*$\n/i, ''))
       type_element_visibility_public = true
@@ -567,8 +567,8 @@ class RDoc::Parser::F95 < RDoc::Parser
     end
 
     if !derived_types_comment.empty?
-      derived_types_table = 
-        Attr.new("Derived Types", "Derived_Types", "", 
+      derived_types_table =
+        Attr.new("Derived Types", "Derived_Types", "",
                  derived_types_comment)
       container.add_attribute(derived_types_table)
     end
@@ -733,8 +733,8 @@ class RDoc::Parser::F95 < RDoc::Parser
         subroutine_trailing = procedure_trailing
         subroutine_code     = procedure_code
 
-        subroutine_comment = COMMENTS_ARE_UPPER ? 
-          pre_comment.join("\n") + "\n" + subroutine_trailing : 
+        subroutine_comment = COMMENTS_ARE_UPPER ?
+          pre_comment.join("\n") + "\n" + subroutine_trailing :
             subroutine_trailing + "\n" + subroutine_code.sub(/^.*$\n/i, '')
         subroutine = AnyMethod.new("subroutine", subroutine_name)
         parse_subprogram(subroutine, subroutine_params,
@@ -787,7 +787,7 @@ class RDoc::Parser::F95 < RDoc::Parser
 
       # The visibility of procedure is specified
       #
-      set_visibility(container, procedure_name, 
+      set_visibility(container, procedure_name,
                      visibility_default, @@public_methods)
 
       # The alias for this procedure from external modules
@@ -871,11 +871,11 @@ class RDoc::Parser::F95 < RDoc::Parser
           next if !old_meth
           nolink = old_meth.visibility == :private ? true : nil
           nolink = nil if @options.show_all
-          new_meth = 
-             initialize_external_method(generic_name, proc, 
-                                        old_meth.params, nil, 
-                                        old_meth.comment, 
-                                        old_meth.clone.token_stream[0].text, 
+          new_meth =
+             initialize_external_method(generic_name, proc,
+                                        old_meth.params, nil,
+                                        old_meth.comment,
+                                        old_meth.clone.token_stream[0].text,
                                         true, nolink)
           new_meth.singleton = old_meth.singleton
 
@@ -937,10 +937,10 @@ class RDoc::Parser::F95 < RDoc::Parser
         end
 
         if indicated_method
-          external_method = 
-            initialize_external_method(generic_name, proc, 
-                                       indicated_method.params, 
-                                       indicated_file, 
+          external_method =
+            initialize_external_method(generic_name, proc,
+                                       indicated_method.params,
+                                       indicated_file,
                                        indicated_method.comment)
 
           @stats.add_method external_method
@@ -1004,12 +1004,12 @@ class RDoc::Parser::F95 < RDoc::Parser
   # Parse arguments, comment, code of subroutine and function.  Return
   # AnyMethod object.
 
-  def parse_subprogram(subprogram, params, comment, code, 
+  def parse_subprogram(subprogram, params, comment, code,
                        before_contains=nil, function=nil, prefix=nil)
     subprogram.singleton = false
     prefix = "" if !prefix
     arguments = params.sub(/\(/, "").sub(/\)/, "").split(",") if params
-    args_comment, params_opt = 
+    args_comment, params_opt =
       find_arguments(arguments, code.sub(/^s*?contains\s*?(!.*?)?$.*/im, ""),
                      nil, nil, true)
     params_opt = "( " + params_opt + " ) " if params_opt
@@ -1086,7 +1086,7 @@ class RDoc::Parser::F95 < RDoc::Parser
         if arg == defitem.varname.strip.chomp || all
           args_rdocforms << <<-"EOF"
 
-#{indent}<tt><b>#{defitem.varname.chomp.strip}#{defitem.arraysuffix}</b> #{defitem.inivalue}</tt> :: 
+#{indent}<tt><b>#{defitem.varname.chomp.strip}#{defitem.arraysuffix}</b> #{defitem.inivalue}</tt> ::
 #{indent}   <tt>#{defitem.types.chomp.strip}</tt>
 EOF
           if !defitem.comment.chomp.strip.empty?
@@ -1096,7 +1096,7 @@ EOF
             }
             args_rdocforms << <<-"EOF"
 
-#{indent}   <tt></tt> :: 
+#{indent}   <tt></tt> ::
 #{indent}       <tt></tt>
 #{indent}       #{comment.chomp.strip}
 EOF
@@ -1130,7 +1130,7 @@ EOF
     before_contains = "" if !before_contains
     while lines =~ /^\s*?namelist\s+\/\s*?(\w+)\s*?\/([\s\w\,]+)$/i
       lines = $~.post_match
-      nml_comment = COMMENTS_ARE_UPPER ? 
+      nml_comment = COMMENTS_ARE_UPPER ?
           find_comments($~.pre_match) : find_comments($~.post_match)
       nml_name = $1
       nml_args = $2.split(",")
@@ -1193,7 +1193,7 @@ EOF
 
     if internal
       external_alias_header = "#{INTERNAL_ALIAS_MES} "
-      external_alias_text   = external_alias_header + old 
+      external_alias_text   = external_alias_header + old
     elsif file
       external_alias_header = "#{EXTERNAL_ALIAS_MES} "
       external_alias_text   = external_alias_header + file + "#" + old
@@ -1325,8 +1325,8 @@ EOF
                   subname.upcase == alias_item["old_name"].upcase &&
                           @options.ignore_case
 
-        new_meth = initialize_external_method(alias_item["new_name"], 
-                                              subname, params, @file_name, 
+        new_meth = initialize_external_method(alias_item["new_name"],
+                                              subname, params, @file_name,
                                               comment)
         new_meth.visibility = alias_item["visibility"]
 
@@ -1402,7 +1402,7 @@ EOF
             brank_flag = false
             now_continuing = false
             next ""
-          else 
+          else
             brank_flag     = false
             now_continuing = false
             ignore         = false
@@ -1595,7 +1595,7 @@ EOF
     comment_block = Array.new
     checked = false
     lines.each do |line|
-      if !checked 
+      if !checked
         if /^\s?#{INTERNAL_ALIAS_MES}/ =~ line ||
             /^\s?#{EXTERNAL_ALIAS_MES}/ =~ line
           checked = true
@@ -1676,9 +1676,9 @@ EOF
 
     def to_s
       return <<-EOF
-<Fortran95Definition: 
+<Fortran95Definition:
 varname=#{@varname}, types=#{types},
-inivalue=#{@inivalue}, arraysuffix=#{@arraysuffix}, nodoc=#{@nodoc}, 
+inivalue=#{@inivalue}, arraysuffix=#{@arraysuffix}, nodoc=#{@nodoc},
 comment=
 #{@comment}
 >