rdoc 3.9.5 → 3.10.pre.1

data/lib/rdoc/markup/to_test.rb

@@ -1,6 +1,3 @@
-require 'rdoc/markup'
-require 'rdoc/markup/formatter'
-
 ##
 # This Markup outputter is used for testing purposes.
 

data/lib/rdoc/markup/to_tt_only.rb

@@ -1,6 +1,3 @@
-require 'rdoc/markup/formatter'
-require 'rdoc/markup/inline'
-
 ##
 # Extracts sections of text enclosed in plus, tt or code.  Used to discover
 # undocumented parameters.

data/lib/rdoc/markup/verbatim.rb

@@ -3,6 +3,17 @@
 
 class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
+  ##
+  # Format of this verbatim section
+
+  attr_accessor :format
+
+  def initialize *parts # :nodoc:
+    super
+
+    @format = nil
+  end
+
   ##
   # Calls #accept_verbatim on +visitor+
 
@@ -34,6 +45,13 @@ class RDoc::Markup::Verbatim < RDoc::Markup::Raw
     @parts = parts
   end
 
+  ##
+  # Is this verbatim section ruby code?
+
+  def ruby?
+    @format == :ruby
+  end
+
   ##
   # The text of the section
 

data/lib/rdoc/meta_method.rb

@@ -1,5 +1,3 @@
-require 'rdoc/any_method'
-
 ##
 # MetaMethod represents a meta-programmed method
 

data/lib/rdoc/method_attr.rb

@@ -1,4 +1,4 @@
-require 'rdoc/code_object'
+require 'cgi'
 
 ##
 # Abstract class representing either a method or an attribute.
@@ -343,6 +343,22 @@ class RDoc::MethodAttr < RDoc::CodeObject
     ]
   end
 
+  ##
+  # Used by RDoc::Generator::JsonIndex to create a record for the search
+  # engine.
+
+  def search_record
+    [
+      @name,
+      full_name,
+      @name,
+      @parent.full_name,
+      path,
+      params,
+      snippet(@comment),
+    ]
+  end
+
   def to_s # :nodoc:
     if @is_alias_for
       "#{self.class.name}: #{full_name} -> #{is_alias_for}"

data/lib/rdoc/normal_class.rb

@@ -1,5 +1,3 @@
-require 'rdoc/class_module'
-
 ##
 # A normal class, neither singleton nor anonymous
 

data/lib/rdoc/normal_module.rb

@@ -1,5 +1,3 @@
-require 'rdoc/class_module'
-
 ##
 # A normal module, like NormalClass
 

data/lib/rdoc/options.rb

@@ -1,7 +1,5 @@
 require 'optparse'
 
-require 'rdoc/ri/paths'
-
 ##
 # RDoc::Options handles the parsing and storage of options
 
@@ -98,6 +96,12 @@ class RDoc::Options
 
   attr_accessor :main_page
 
+  ##
+  # The default markup format.  The default is 'rdoc'.  'tomdoc' and 'rd' are
+  # also built-in.
+
+  attr_accessor :markup
+
   ##
   # If true, only report on undocumented files
 
@@ -171,7 +175,6 @@ class RDoc::Options
   attr_accessor :visibility
 
   def initialize # :nodoc:
-    require 'rdoc/rdoc'
     @dry_run = false
     @exclude = []
     @force_output = false
@@ -183,6 +186,7 @@ class RDoc::Options
     @hyperlink_all = false
     @line_numbers = false
     @main_page = nil
+    @markup = 'rdoc'
     @coverage_report = false
     @op_dir = nil
     @pipe = false
@@ -451,6 +455,17 @@ Usage: #{opt.program_name} [options] [names...]
         @visibility = value
       end
 
+      opt.separator nil
+
+      markup_formats = RDoc::Text::MARKUP_FORMAT.keys.sort
+
+      opt.on("--markup=MARKUP", markup_formats,
+             "The markup format for the named files.",
+             "The default is rdoc.  Valid values are:",
+             markup_formats.join(', ')) do |value|
+        @markup = value
+      end
+
       opt.separator nil
       opt.separator "Common generator options:"
       opt.separator nil

data/lib/rdoc/parser.rb

@@ -1,41 +1,31 @@
-require 'rdoc'
-require 'rdoc/code_objects'
-require 'rdoc/markup/pre_process'
-require 'rdoc/stats'
-
 ##
-# A parser is a class that subclasses RDoc::Parser and implements
-#
-#   #initialize top_level, file_name, body, options, stats
-#
-# and
+# A parser is simple a class that subclasses RDoc::Parser and implements #scan
+# to fill in an RDoc::TopLevel with parsed data.
 #
-#   #scan
+# The initialize method takes an RDoc::TopLevel to fill with parsed content,
+# the name of the file to be parsed, the content of the file, an RDoc::Options
+# object and an RDoc::Stats object to inform the user of parsed items.  The
+# scan method is then called to parse the file and must return the
+# RDoc::TopLevel object.  By calling super these items will be set for you.
 #
-# The initialize method takes a file name to be used, the body of the file,
-# and an RDoc::Options object. The scan method is then called to return an
-# appropriately parsed TopLevel code object.
+# In order to be used by RDoc the parser needs to register the file extensions
+# it can parse.  Use ::parse_files_matching to register extensions.
 #
-# RDoc::Parser::for is a factory that creates the correct parser for a
-# given filename extension.  Parsers have to register themselves RDoc::Parser
-# using parse_files_matching as when they are loaded:
-#
-#   require "rdoc/parser"
+#   require 'rdoc'
 #
 #   class RDoc::Parser::Xyz < RDoc::Parser
-#     parse_files_matching /\.xyz$/ # <<<<
+#     parse_files_matching /\.xyz$/
+#
+#     def initialize top_level, file_name, content, options, stats
+#       super
 #
-#     def initialize top_level, file_name, body, options, stats
-#       ...
+#       # extra initialization if needed
 #     end
 #
 #     def scan
-#       ...
+#       # parse file and fill in @top_level
 #     end
 #   end
-#
-# If a plain text file is detected, RDoc also looks for a shebang line in case
-# the file is a shell script.
 
 class RDoc::Parser
 
@@ -154,26 +144,30 @@ class RDoc::Parser
   end
 
   ##
-  # Find the correct parser for a particular file name. Return a SimpleParser
-  # for ones that we don't know
+  # Finds and instantiates the correct parser for the given +file_name+ and
+  # +content+.
 
-  def self.for(top_level, file_name, body, options, stats)
+  def self.for top_level, file_name, content, options, stats
     return if binary? file_name
 
-    # If no extension, look for shebang
-    if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)} then
-      shebang = $1
-      case shebang
-      when %r{env\s+ruby}, %r{/ruby}
-        file_name = "dummy.rb"
+    parser = use_format content
+
+    unless parser then
+      # If no extension, look for shebang
+      if file_name !~ /\.\w+$/ && content =~ %r{\A#!(.+)} then
+        shebang = $1
+        case shebang
+        when %r{env\s+ruby}, %r{/ruby}
+          file_name = "dummy.rb"
+        end
       end
-    end
 
-    parser = can_parse file_name
+      parser = can_parse file_name
+    end
 
     return unless parser
 
-    parser.new top_level, file_name, body, options, stats
+    parser.new top_level, file_name, content, options, stats
   end
 
   ##
@@ -186,13 +180,44 @@ class RDoc::Parser
   end
 
   ##
-  # Creates a new Parser storing +top_level+, +file_name+, +content+,
-  # +options+ and +stats+ in instance variables.
+  # If there is a <tt>format: parser_name</tt> comment at the front of the
+  # file, use it to determine the parser.  For example:
+  #
+  #   # format: rdoc
+  #   # Class comment can go here
+  #
+  #   class C
+  #   end
   #
-  # Usually invoked by +super+
+  # The comment should appear as the first line of the +content+.
+  #
+  # If the content contains a shebang or editor modeline the comment may
+  # appear on the second or third line.
+  #
+  # Any comment style may be used to hide the format comment.
+
+  def self.use_format content
+    format = content.lines.first(3).grep(/format:\s+(\w+)/) { $1 }.first
+
+    return unless format
+
+    format = Regexp.escape format
+
+    RDoc::Parser.parsers.find do |_, parser|
+      /^#{format}$/i =~ parser.name.sub(/.*:/, '')
+    end.last
+  end
+
+  ##
+  # Creates a new Parser storing +top_level+, +file_name+, +content+,
+  # +options+ and +stats+ in instance variables.  In +@preprocess+ an
+  # RDoc::Markup::PreProcess object is created which allows processing of
+  # directives.
 
-  def initialize(top_level, file_name, content, options, stats)
+  def initialize top_level, file_name, content, options, stats
     @top_level = top_level
+    @top_level.parser = self.class
+
     @file_name = file_name
     @content = content
     @options = options
@@ -202,7 +227,14 @@ class RDoc::Parser
     @preprocess.options = @options
   end
 
+  autoload :RubyTools, 'rdoc/parser/ruby_tools'
+  autoload :Text,      'rdoc/parser/text'
+
 end
 
+# simple must come first in order to show up last in the parsers list
 require 'rdoc/parser/simple'
+require 'rdoc/parser/rd'
+require 'rdoc/parser/ruby'
+require 'rdoc/parser/c'
 

data/lib/rdoc/parser/c.rb

@@ -1,7 +1,3 @@
-
-require 'rdoc/parser/ruby'
-require 'rdoc/known_classes'
-
 ##
 # RDoc::Parser::C attempts to parse C extension files.  It looks for
 # the standard patterns that you find in extensions: <tt>rb_define_class,
@@ -180,7 +176,9 @@ class RDoc::Parser::C < RDoc::Parser
       al.singleton = @singleton_classes.key? var_name
 
       comment = find_alias_comment var_name, new_name, old_name
-      comment = strip_stars comment
+
+      comment.normalize
+
       al.comment = comment
 
       al.record_location @top_level
@@ -311,7 +309,9 @@ class RDoc::Parser::C < RDoc::Parser
     @content.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
       if cls = @classes[c]
         m = @known_classes[m] || m
-        incl = cls.add_include RDoc::Include.new(m, "")
+
+        comment = RDoc::Comment.new '', @top_level
+        incl = cls.add_include RDoc::Include.new(m, comment)
         incl.record_location @top_level
       end
     end
@@ -377,7 +377,7 @@ class RDoc::Parser::C < RDoc::Parser
                                    \s*"#{Regexp.escape new_name}"\s*,
                                    \s*"#{Regexp.escape old_name}"\s*\);%xm
 
-    $1 || ''
+    RDoc::Comment.new($1 || '', @top_level)
   end
 
   ##
@@ -398,22 +398,24 @@ class RDoc::Parser::C < RDoc::Parser
            /.*?/m
          end
 
-    if @content =~ %r%((?>/\*.*?\*/\s+))
-                      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
-                         ((?>.*?\*/))%xm then
-      $1
-    else
-      ''
-    end
+    comment = if @content =~ %r%((?>/\*.*?\*/\s+))
+                                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
+                                   ((?>.*?\*/))%xm then
+                $1
+              else
+                ''
+              end
+
+    RDoc::Comment.new comment, @top_level
   end
 
   ##
@@ -425,11 +427,11 @@ class RDoc::Parser::C < RDoc::Parser
             ((?:(?:static|SWIGINTERN)\s+)?
              (?:intern\s+)?VALUE\s+#{meth_name}
              \s*(\([^)]*\))([^;]|$))%xm then
-      comment = $1
+      comment = RDoc::Comment.new $1, @top_level
       body = $2
       offset = $~.offset(2).first
 
-      remove_private_comments comment if comment
+      comment.remove_private if comment
 
       # try to find the whole body
       body = $& if /#{Regexp.escape body}[^(]*?\{.*?^\}/m =~ file_content
@@ -443,6 +445,7 @@ class RDoc::Parser::C < RDoc::Parser
       override_comment = find_override_comment class_name, meth_obj
       comment = override_comment if override_comment
 
+      comment.normalize
       find_modifiers comment, meth_obj if comment
 
       #meth_obj.params = params
@@ -450,24 +453,26 @@ class RDoc::Parser::C < RDoc::Parser
       tk = RDoc::RubyToken::Token.new nil, 1, 1
       tk.set_text body
       meth_obj.add_token tk
-      meth_obj.comment = strip_stars comment
+      meth_obj.comment = comment
       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
+      comment = RDoc::Comment.new $1, @top_level
       body = $2
       offset = $~.offset(2).first
 
       find_body class_name, $3, meth_obj, file_content, true
+
+      comment.normalize
       find_modifiers comment, meth_obj
 
       meth_obj.start_collecting_tokens
       tk = RDoc::RubyToken::Token.new nil, 1, 1
       tk.set_text body
       meth_obj.add_token tk
-      meth_obj.comment = strip_stars(comment) + meth_obj.comment.to_s
+      meth_obj.comment = comment
       meth_obj.offset  = offset
       meth_obj.line    = file_content[0, offset].count("\n") + 1
 
@@ -486,8 +491,9 @@ class RDoc::Parser::C < RDoc::Parser
       comment = find_override_comment class_name, meth_obj
 
       if comment then
+        comment.normalize
         find_modifiers comment, meth_obj
-        meth_obj.comment = strip_stars comment
+        meth_obj.comment = comment
 
         ''
       else
@@ -551,17 +557,18 @@ class RDoc::Parser::C < RDoc::Parser
       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
+      comment = "/*\n#{$1}"
     elsif @content =~ %r%((?>/\*.*?\*/\s+))
                          ([\w\.\s]+\s* = \s+)?rb_define_(class|module).*?"(#{class_name})"%xm then
       comment = $1
+    else
+      comment = ''
     end
 
-    return unless comment
+    comment = RDoc::Comment.new comment, @top_level
+    comment.normalize
 
-    comment = strip_stars comment
-
-    comment = look_for_directives_in class_mod, comment
+    look_for_directives_in class_mod, comment
 
     class_mod.add_comment comment, @top_level
   end
@@ -571,79 +578,33 @@ class RDoc::Parser::C < RDoc::Parser
   # comment or in the matching Document- section.
 
   def find_const_comment(type, const_name, class_name = nil)
-    if @content =~ %r%((?>^\s*/\*.*?\*/\s+))
-                   rb_define_#{type}\((?:\s*(\w+),)?\s*
-                                      "#{const_name}"\s*,
-                                      .*?\)\s*;%xmi then
-      $1
-    elsif class_name and
-          @content =~ %r%Document-(?:const|global|variable):\s
-                         #{class_name}::#{const_name}
-                         \s*?\n((?>.*?\*/))%xm then
-      $1
-    elsif @content =~ %r%Document-(?:const|global|variable):\s#{const_name}
-                         \s*?\n((?>.*?\*/))%xm then
-      $1
-    else
-      ''
-    end
+    comment = if @content =~ %r%((?>^\s*/\*.*?\*/\s+))
+                             rb_define_#{type}\((?:\s*(\w+),)?\s*
+                                                "#{const_name}"\s*,
+                                                .*?\)\s*;%xmi then
+                $1
+              elsif class_name and
+                    @content =~ %r%Document-(?:const|global|variable):\s
+                                   #{class_name}::#{const_name}
+                                   \s*?\n((?>.*?\*/))%xm then
+                "/*\n#{$1}"
+              elsif @content =~ %r%Document-(?:const|global|variable):
+                                   \s#{const_name}
+                                   \s*?\n((?>.*?\*/))%xm then
+                "/*\n#{$1}"
+              else
+                ''
+              end
+
+    RDoc::Comment.new comment, @top_level
   end
 
   ##
   # Handles modifiers in +comment+ and updates +meth_obj+ as appropriate.
-  #
-  # If <tt>:nodoc:</tt> is found, documentation on +meth_obj+ is suppressed.
-  #
-  # 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
-
-      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
+    comment.normalize
+    comment.extract_call_seq meth_obj
 
     look_for_directives_in meth_obj, comment
   end
@@ -655,11 +616,18 @@ class RDoc::Parser::C < RDoc::Parser
     name = Regexp.escape meth_obj.name
     prefix = Regexp.escape meth_obj.name_prefix
 
-    if @content =~ %r%Document-method:\s+#{class_name}#{prefix}#{name}\s*?\n((?>.*?\*/))%m then
-      $1
-    elsif @content =~ %r%Document-method:\s#{name}\s*?\n((?>.*?\*/))%m then
-      $1
-    end
+    comment = if @content =~ %r%Document-method:
+                                \s+#{class_name}#{prefix}#{name}
+                                \s*?\n((?>.*?\*/))%xm then
+                "/*#{$1}"
+              elsif @content =~ %r%Document-method:
+                                   \s#{name}\s*?\n((?>.*?\*/))%xm then
+                "/*#{$1}"
+              end
+
+    return unless comment
+
+    RDoc::Comment.new comment, @top_level
   end
 
   ##
@@ -680,7 +648,7 @@ class RDoc::Parser::C < RDoc::Parser
     return unless class_obj
 
     comment = find_attr_comment var_name, attr_name
-    comment = strip_stars comment
+    comment.normalize
 
     name = attr_name.gsub(/rb_intern\("([^"]+)"\)/, '\1')
 
@@ -770,14 +738,13 @@ class RDoc::Parser::C < RDoc::Parser
     end
 
     comment = find_const_comment type, const_name, class_name
-    comment = strip_stars comment
-    comment = normalize_comment comment
+    comment.normalize
 
     # In the case of rb_define_const, the definition and comment are in
     # "/* definition: comment */" form.  The literal ':' and '\' characters
     # can be escaped with a backslash.
     if type.downcase == 'const' then
-      elements = comment.split ':'
+      elements = comment.text.split ':'
 
       if elements.nil? or elements.empty? then
         con = RDoc::Constant.new const_name, definition, comment
@@ -799,6 +766,8 @@ class RDoc::Parser::C < RDoc::Parser
                         "#{$1}#{elements.last.lstrip}"
                       end
 
+        new_comment = RDoc::Comment.new new_comment, @top_level
+
         con = RDoc::Constant.new const_name, new_definition, new_comment
       end
     else
@@ -1020,14 +989,6 @@ 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
-
   ##
   # Extracts the classes, modules, methods, attributes, constants and aliases
   # from a C file and returns an RDoc::TopLevel for this file