rdoc 3.9.5 → 3.10.pre.1

data/bin/rdoc

@@ -5,8 +5,6 @@
 #
 #  Copyright (c) 2003 Dave Thomas
 #  Released under the same terms as Ruby
-#
-#  $Revision: 15033 $
 
 begin
   gem 'rdoc'

data/lib/rdoc.rb

@@ -94,7 +94,7 @@ module RDoc
 
   def self.const_missing const_name # :nodoc:
     if const_name.to_s == 'RDocError' then
-      warn "RDoc::RDocError is deprecated"
+      warn "RDoc::RDocError is deprecated and will be removed in RDoc 4"
       return Error
     end
 
@@ -104,7 +104,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '3.9.5'
+  VERSION = '3.10'
 
   ##
   # Method visibilities
@@ -143,5 +143,58 @@ module RDoc
   METHOD_MODIFIERS = GENERAL_MODIFIERS +
     %w[arg args yield yields notnew not-new not_new doc]
 
+  autoload :RDoc,           'rdoc/rdoc'
+
+  autoload :TestCase,       'rdoc/test_case'
+
+  autoload :CrossReference, 'rdoc/cross_reference'
+  autoload :ERBIO,          'rdoc/erbio'
+  autoload :Encoding,       'rdoc/encoding'
+  autoload :Generator,      'rdoc/generator'
+  autoload :Options,        'rdoc/options'
+  autoload :Parser,         'rdoc/parser'
+  autoload :RI,             'rdoc/ri'
+  autoload :Stats,          'rdoc/stats'
+  autoload :Task,           'rdoc/task'
+  autoload :Text,           'rdoc/text'
+
+  autoload :Markup,         'rdoc/markup'
+  autoload :RD,             'rdoc/rd'
+  autoload :TomDoc,         'rdoc/tom_doc'
+
+  autoload :KNOWN_CLASSES,  'rdoc/known_classes'
+
+  autoload :RubyLex,        'rdoc/ruby_lex'
+  autoload :RubyToken,      'rdoc/ruby_token'
+  autoload :TokenStream,    'rdoc/token_stream'
+
+  autoload :Comment,        'rdoc/comment'
+
+  # code objects
+  #
+  # We represent the various high-level code constructs that appear in Ruby
+  # programs: classes, modules, methods, and so on.
+  autoload :CodeObject,     'rdoc/code_object'
+
+  autoload :Context,        'rdoc/context'
+  autoload :TopLevel,       'rdoc/top_level'
+
+  autoload :AnonClass,      'rdoc/anon_class'
+  autoload :ClassModule,    'rdoc/class_module'
+  autoload :NormalClass,    'rdoc/normal_class'
+  autoload :NormalModule,   'rdoc/normal_module'
+  autoload :SingleClass,    'rdoc/single_class'
+
+  autoload :Alias,          'rdoc/alias'
+  autoload :AnyMethod,      'rdoc/any_method'
+  autoload :MethodAttr,     'rdoc/method_attr'
+  autoload :GhostMethod,    'rdoc/ghost_method'
+  autoload :MetaMethod,     'rdoc/meta_method'
+  autoload :Attr,           'rdoc/attr'
+
+  autoload :Constant,       'rdoc/constant'
+  autoload :Include,        'rdoc/include'
+  autoload :Require,        'rdoc/require'
+
 end
 

data/lib/rdoc/alias.rb

@@ -1,5 +1,3 @@
-require 'rdoc/code_object'
-
 ##
 # Represent an alias, which is an old_name/new_name pair associated with a
 # particular context

data/lib/rdoc/anon_class.rb

@@ -1,5 +1,3 @@
-require 'rdoc/class_module'
-
 ##
 # An anonymous class like:
 #

data/lib/rdoc/any_method.rb

@@ -1,6 +1,3 @@
-require 'rdoc/method_attr'
-require 'rdoc/token_stream'
-
 ##
 # AnyMethod is the base class for objects representing methods
 

data/lib/rdoc/attr.rb

@@ -1,5 +1,3 @@
-require 'rdoc/method_attr'
-
 ##
 # An attribute created by \#attr, \#attr_reader, \#attr_writer or
 # \#attr_accessor

data/lib/rdoc/class_module.rb

@@ -1,5 +1,3 @@
-require 'rdoc/context'
-
 ##
 # ClassModule is the base class for objects representing either a class or a
 # module.
@@ -115,11 +113,16 @@ class RDoc::ClassModule < RDoc::Context
   # across multiple runs.
 
   def add_comment comment, location
-    return if comment.empty? or not document_self
+    return unless document_self
 
     original = comment
 
-    comment = normalize_comment comment
+    comment = case comment
+              when RDoc::Comment then
+                comment.normalize
+              else
+                normalize_comment comment
+              end
     @comment_location << [comment, location]
 
     self.comment = original
@@ -155,9 +158,13 @@ class RDoc::ClassModule < RDoc::Context
   # more like <tt>+=</tt>.
 
   def comment= comment
-    return if comment.empty?
+    comment = case comment
+              when RDoc::Comment then
+                comment.normalize
+              else
+                normalize_comment comment
+              end
 
-    comment = normalize_comment comment
     comment = "#{@comment}\n---\n#{comment}" unless @comment.empty?
 
     super comment
@@ -175,6 +182,13 @@ class RDoc::ClassModule < RDoc::Context
     remove_invisible min_visibility
   end
 
+  ##
+  # Does this ClassModule or any of its methods have document_self set?
+
+  def document_self_or_methods
+    document_self || method_list.any?{ |m| m.document_self }
+  end
+
   ##
   # Iterates the ancestors of this class or module for which an
   # RDoc::ClassModule exists.
@@ -438,11 +452,15 @@ class RDoc::ClassModule < RDoc::Context
     when Array then
       docs = comment_location.map do |comment, location|
         doc = super comment
-        doc.file = location.absolute_name
+        doc.file = location
         doc
       end
 
       RDoc::Markup::Document.new(*docs)
+    when RDoc::Comment then
+      doc = super comment_location.text, comment_location.format
+      doc.file = comment_location.location
+      doc
     when RDoc::Markup::Document then
       return comment_location
     else
@@ -497,6 +515,21 @@ class RDoc::ClassModule < RDoc::Context
     end
   end
 
+  ##
+  # Search record used by RDoc::Generator::JsonIndex
+
+  def search_record
+    [
+      name,
+      full_name,
+      full_name,
+      '',
+      path,
+      '',
+      snippet(@comment_location),
+    ]
+  end
+
   ##
   # Get the superclass of this class.  Attempts to retrieve the superclass
   # object, returns the name if it is not known.

data/lib/rdoc/code_object.rb

@@ -1,6 +1,3 @@
-require 'rdoc'
-require 'rdoc/text'
-
 ##
 # Base class for the RDoc code tree.
 #
@@ -124,6 +121,7 @@ class RDoc::CodeObject
     @comment = case comment
                when NilClass               then ''
                when RDoc::Markup::Document then comment
+               when RDoc::Comment          then comment.normalize
                else
                  if comment and not comment.empty? then
                    normalize_comment comment

data/lib/rdoc/code_objects.rb

@@ -1,23 +1,5 @@
-# We represent the various high-level code constructs that appear in Ruby
-# programs: classes, modules, methods, and so on.
+# This file was used to load all the RDoc::CodeObject subclasses at once.  Now
+# autoload handles this.
 
-require 'rdoc/code_object'
-require 'rdoc/context'
-require 'rdoc/top_level'
-
-require 'rdoc/class_module'
-require 'rdoc/normal_class'
-require 'rdoc/normal_module'
-require 'rdoc/anon_class'
-require 'rdoc/single_class'
-
-require 'rdoc/any_method'
-require 'rdoc/alias'
-require 'rdoc/ghost_method'
-require 'rdoc/meta_method'
-
-require 'rdoc/attr'
-require 'rdoc/constant'
-require 'rdoc/require'
-require 'rdoc/include'
+require 'rdoc'
 

data/lib/rdoc/comment.rb

@@ -0,0 +1,225 @@
+##
+# A comment holds the text comment for a RDoc::CodeObject and provides a
+# unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
+#
+# Each comment may have a different markup format set by #format=.  By default
+# 'rdoc' is used.  The :markup: directive tells RDoc which format to use.
+#
+# See RDoc::Markup@Other+directives for instructions on adding an alternate
+# format.
+
+class RDoc::Comment
+
+  include RDoc::Text
+
+  ##
+  # The format of this comment.  Defaults to RDoc::Markup
+
+  attr_reader :format
+
+  ##
+  # The RDoc::TopLevel this comment was found in
+
+  attr_accessor :location
+
+  ##
+  # The text for this comment
+
+  attr_reader :text
+
+  ##
+  # Overrides the content returned by #parse.  Use when there is no #text
+  # source for this comment
+
+  attr_writer   :document
+
+  ##
+  # Creates a new comment with +text+ that is found in the RDoc::TopLevel
+  # +location+.
+
+  def initialize text = nil, location = nil
+    @location = location
+    @text     = text
+
+    @document   = nil
+    @format     = 'rdoc'
+    @normalized = false
+  end
+
+  ##
+  #--
+  # TODO deep copy @document
+
+  def initialize_copy copy # :nodoc:
+    @text = copy.text.dup
+  end
+
+  def == other # :nodoc:
+    self.class === other and
+      other.text == @text and other.location == @location
+  end
+
+  ##
+  # Look for a 'call-seq' in the comment to override the normal parameter
+  # handling.  The :call-seq: is indented from the baseline.  All lines of the
+  # same indentation level and prefix are consumed.
+  #
+  # For example, all of the following will be used as the :call-seq:
+  #
+  #   # :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
+
+  def extract_call_seq method
+    # 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 @text =~ /^\s*:?call-seq:(.*?(?:\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*\n)+^(\s*\w+)/m then
+        leading = $2 # ' *    ARGF' in the example above
+        re = %r%
+          \A(
+             (^\s*\n)+
+             (^#{Regexp.escape leading}.*?\n)+
+            )+
+          ^\s*$
+        %xm
+
+        if @text[seq_stop..-1] =~ re then
+          all_stop = seq_stop + $~.offset(0).last
+          seq_stop = seq_stop + $~.offset(1).last
+        end
+      end
+
+      seq = @text[seq_start..seq_stop]
+      seq.gsub!(/^\s*(\S|\n)/m, '\1')
+      @text.slice! all_start...all_stop
+
+      method.call_seq = seq.chomp
+
+    elsif @text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/m, '') then
+      seq = $1
+      seq.gsub!(/^\s*/, '')
+      method.call_seq = seq
+    end
+    #elsif @text.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then
+    #  method.call_seq = $1.strip
+    #end
+
+    method
+  end
+
+  ##
+  # A comment is empty if its text String is empty.
+
+  def empty?
+    @text.empty?
+  end
+
+  ##
+  # HACK dubious
+
+  def force_encoding encoding
+    @text.force_encoding encoding
+  end
+
+  ##
+  # Sets the format of this comment and resets any parsed document
+
+  def format= format
+    @format = format
+    @document = nil
+  end
+
+  def inspect # :nodoc:
+    "#<%s:%x %s %p>" % [self.class, object_id, @location.absolute_name, @text]
+  end
+
+  ##
+  # Normalizes the text.  See RDoc::Text#normalize_comment for details
+
+  def normalize
+    return self unless @text
+    return self if @normalized # TODO eliminate duplicate normalization
+
+    @text = normalize_comment @text
+
+    @normalized = true
+
+    self
+  end
+
+  ##
+  # Was this text normalized?
+
+  def normalized? # :nodoc:
+    @normalized
+  end
+
+  ##
+  # Parses the comment into an RDoc::Markup::Document.  The parsed document is
+  # cached until the text is changed.
+
+  def parse
+    return @document if @document
+
+    @document = super @text, @format
+    @document.file = @location
+    @document
+  end
+
+  ##
+  # Removes private sections from this comment.  Private sections are flush to
+  # the comment marker and start with <tt>--</tt> and end with <tt>++</tt>.
+  # For C-style comments, a private marker may not start at the opening of the
+  # comment.
+  #
+  #   /*
+  #    *--
+  #    * private
+  #    *++
+  #    * public
+  #    */
+
+  def remove_private
+    # Workaround for gsub encoding for Ruby 1.9.2 and earlier
+    empty = ''
+    empty.force_encoding @text.encoding if Object.const_defined? :Encoding
+
+    @text = @text.gsub(%r%^\s*([#*]?)--.*?^\s*(\1)\+\+\n?%m, empty)
+    @text = @text.sub(%r%^\s*[#*]?--.*%m, '')
+  end
+
+  ##
+  # Replaces this comment's text with +text+ and resets the parsed document.
+  #
+  # An error is raised if the comment contains a document but no text.
+
+  def text= text
+    raise RDoc::Error, 'replacing document-only comment is not allowed' if
+      @text.nil? and @document
+
+    @document = nil
+    @text = text
+  end
+
+  ##
+  # Returns true if this comment is in TomDoc format.
+
+  def tomdoc?
+    @format == 'tomdoc'
+  end
+
+end
+