rdoc 3.12.2 → 4.0.0.preview2

data/lib/rdoc/code_object.rb

@@ -75,9 +75,9 @@ class RDoc::CodeObject
   attr_accessor :offset
 
   ##
-  # Our parent CodeObject
+  # Sets the parent CodeObject
 
-  attr_accessor :parent
+  attr_writer :parent
 
   ##
   # Did we ever receive a +:nodoc:+ directive?
@@ -85,9 +85,14 @@ class RDoc::CodeObject
   attr_reader :received_nodoc
 
   ##
-  # Which section are we in
+  # Set the section this CodeObject is in
 
-  attr_accessor :section
+  attr_writer :section
+
+  ##
+  # The RDoc::Store for this object.
+
+  attr_accessor :store
 
   ##
   # We are the model of the code, but we know that at some point we will be
@@ -100,11 +105,16 @@ class RDoc::CodeObject
   # Creates a new CodeObject that will document itself and its children
 
   def initialize
-    @metadata  = {}
-    @comment   = ''
-    @parent    = nil
-    @file      = nil
-    @full_name = nil
+    @metadata      = {}
+    @comment       = ''
+    @parent        = nil
+    @parent_name   = nil # for loading
+    @parent_class  = nil # for loading
+    @section       = nil
+    @section_title = nil # for loading
+    @file          = nil
+    @full_name     = nil
+    @store         = nil
 
     @document_children   = true
     @document_self       = true
@@ -126,7 +136,6 @@ class RDoc::CodeObject
                  if comment and not comment.empty? then
                    normalize_comment comment
                  else
-                   # TODO is this sufficient?
                    # HACK correct fix is to have #initialize create @comment
                    #      with the correct encoding
                    if String === @comment and
@@ -214,7 +223,7 @@ class RDoc::CodeObject
 
   ##
   # Force the documentation of this object unless documentation
-  # has been turned off by :endoc:
+  # has been turned off by :enddoc:
   #--
   # HACK untested, was assigning to an ivar
 
@@ -259,6 +268,29 @@ class RDoc::CodeObject
     @ignored
   end
 
+  ##
+  # Our parent CodeObject.  The parent may be missing for classes loaded from
+  # legacy RI data stores.
+
+  def parent
+    return @parent if @parent
+    return nil unless @parent_name
+
+    if @parent_class == RDoc::TopLevel then
+      @parent = @store.add_file @parent_name
+    else
+      @parent = @store.find_class_or_module @parent_name
+
+      return @parent if @parent
+
+      begin
+        @parent = @store.load_class @parent_name
+      rescue RDoc::Store::MissingFileError
+        nil
+      end
+    end
+  end
+
   ##
   # File name of our parent
 
@@ -281,9 +313,19 @@ class RDoc::CodeObject
     @file = top_level
   end
 
+  ##
+  # The section this CodeObject is in.  Sections allow grouping of constants,
+  # attributes and methods inside a class or module.
+
+  def section
+    return @section if @section
+
+    @section = parent.add_section @section_title if parent
+  end
+
   ##
   # Enable capture of documentation unless documentation has been
-  # turned off by :endoc:
+  # turned off by :enddoc:
 
   def start_doc
     return if @done_documenting

data/lib/rdoc/comment.rb

@@ -22,6 +22,11 @@ class RDoc::Comment
 
   attr_accessor :location
 
+  ##
+  # For duck-typing when merging classes at load time
+
+  alias file location # :nodoc:
+
   ##
   # The text for this comment
 
@@ -143,7 +148,9 @@ class RDoc::Comment
   end
 
   def inspect # :nodoc:
-    "#<%s:%x %s %p>" % [self.class, object_id, @location.absolute_name, @text]
+    location = @location ? @location.relative_name : '(unknown)'
+
+    "#<%s:%x %s %p>" % [self.class, object_id, location, @text]
   end
 
   ##

data/lib/rdoc/constant.rb

@@ -3,12 +3,12 @@
 
 class RDoc::Constant < RDoc::CodeObject
 
+  MARSHAL_VERSION = 0 # :nodoc:
+
   ##
-  # If this constant is an alias for a module or class,
-  # this is the RDoc::ClassModule it is an alias for.
-  # +nil+ otherwise.
+  # Sets the module or class this is constant is an alias for.
 
-  attr_accessor :is_alias_for
+  attr_writer :is_alias_for
 
   ##
   # The constant's name
@@ -20,14 +20,23 @@ class RDoc::Constant < RDoc::CodeObject
 
   attr_accessor :value
 
+  ##
+  # The constant's visibility
+
+  attr_accessor :visibility
+
   ##
   # Creates a new constant with +name+, +value+ and +comment+
 
   def initialize(name, value, comment)
     super()
-    @name = name
+
+    @name  = name
     @value = value
+
     @is_alias_for = nil
+    @visibility   = nil
+
     self.comment = comment
   end
 
@@ -57,6 +66,27 @@ class RDoc::Constant < RDoc::CodeObject
     super or is_alias_for && is_alias_for.documented?
   end
 
+  ##
+  # Full constant name including namespace
+
+  def full_name
+    @full_name ||= "#{parent_name}::#{@name}"
+  end
+
+  ##
+  # The module or class this constant is an alias for
+
+  def is_alias_for
+    case @is_alias_for
+    when String then
+      found = @store.find_class_or_module @is_alias_for
+      @is_alias_for = found if found
+      @is_alias_for
+    else
+      @is_alias_for
+    end
+  end
+
   def inspect # :nodoc:
     "#<%s:0x%x %s::%s>" % [
       self.class, object_id,
@@ -65,12 +95,76 @@ class RDoc::Constant < RDoc::CodeObject
   end
 
   ##
-  # Path to this constant
+  # Dumps this Constant for use by ri.  See also #marshal_load
+
+  def marshal_dump
+    alias_name = case found = is_alias_for
+                 when RDoc::CodeObject then found.full_name
+                 else                       found
+                 end
+
+    [ MARSHAL_VERSION,
+      @name,
+      full_name,
+      @visibility,
+      alias_name,
+      parse(@comment),
+      @file.relative_name,
+      parent.name,
+      parent.class,
+      section.title,
+    ]
+  end
+
+  ##
+  # Loads this Constant from +array+.  For a loaded Constant the following
+  # methods will return cached values:
+  #
+  # * #full_name
+  # * #parent_name
+
+  def marshal_load array
+    initialize array[1], nil, array[5]
+
+    @full_name     = array[2]
+    @visibility    = array[3]
+    @is_alias_for  = array[4]
+    #                      5 handled above
+    #                      6 handled below
+    @parent_name   = array[7]
+    @parent_class  = array[8]
+    @section_title = array[9]
+
+    @file = RDoc::TopLevel.new array[6]
+  end
+
+  ##
+  # Path to this constant for use with HTML generator output.
 
   def path
     "#{@parent.path}##{@name}"
   end
 
+  def pretty_print q # :nodoc:
+    q.group 2, "[#{self.class.name} #{full_name}", "]" do
+      unless comment.empty? then
+        q.breakable
+        q.text "comment:"
+        q.breakable
+        q.pp @comment
+      end
+    end
+  end
+
+  ##
+  # Sets the store for this class or module and its contained code objects.
+
+  def store= store
+    super
+
+    @file = @store.add_file @file.full_name if @file
+  end
+
   def to_s # :nodoc:
     parent_name = parent ? parent.full_name : '(unknown)'
     if is_alias_for

data/lib/rdoc/context.rb

@@ -30,6 +30,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :attributes
 
+  ##
+  # Block params to be used in the next MethodAttr parsed under this context
+
+  attr_accessor :block_params
+
   ##
   # Constants defined
 
@@ -50,6 +55,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :includes
 
+  ##
+  # Modules this context is extended with
+
+  attr_reader :extends
+
   ##
   # Methods defined in this context
 
@@ -78,7 +88,7 @@ class RDoc::Context < RDoc::CodeObject
   attr_accessor :unmatched_alias_lists
 
   ##
-  # Aliases that could not eventually be resolved.
+  # Aliases that could not be resolved.
 
   attr_reader :external_aliases
 
@@ -93,6 +103,11 @@ class RDoc::Context < RDoc::CodeObject
 
   attr_reader :methods_hash
 
+  ##
+  # Params to be used in the next MethodAttr parsed under this context
+
+  attr_accessor :params
+
   ##
   # Hash of registered constants.
 
@@ -129,6 +144,7 @@ class RDoc::Context < RDoc::CodeObject
     @aliases     = []
     @requires    = []
     @includes    = []
+    @extends     = []
     @constants   = []
     @external_aliases = []
 
@@ -136,8 +152,12 @@ class RDoc::Context < RDoc::CodeObject
     # a method not yet encountered).
     @unmatched_alias_lists = {}
 
-    @methods_hash = {}
+    @methods_hash   = {}
     @constants_hash = {}
+
+    @params = nil
+
+    @store ||= nil
   end
 
   ##
@@ -260,12 +280,12 @@ class RDoc::Context < RDoc::CodeObject
       if full_name =~ /^(.+)::(\w+)$/ then
         name = $2
         ename = $1
-        enclosing = RDoc::TopLevel.classes_hash[ename] ||
-                    RDoc::TopLevel.modules_hash[ename]
+        enclosing = @store.classes_hash[ename] || @store.modules_hash[ename]
         # HACK: crashes in actionpack/lib/action_view/helpers/form_helper.rb (metaprogramming)
         unless enclosing then
           # try the given name at top level (will work for the above example)
-          enclosing = RDoc::TopLevel.classes_hash[given_name] || RDoc::TopLevel.modules_hash[given_name]
+          enclosing = @store.classes_hash[given_name] ||
+                      @store.modules_hash[given_name]
           return enclosing if enclosing
           # not found: create the parent(s)
           names = ename.split('::')
@@ -304,7 +324,7 @@ class RDoc::Context < RDoc::CodeObject
       end
 
       # did we believe it was a module?
-      mod = RDoc::TopLevel.modules_hash.delete superclass
+      mod = @store.modules_hash.delete superclass
 
       upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod
 
@@ -312,7 +332,7 @@ class RDoc::Context < RDoc::CodeObject
       superclass = nil if superclass == full_name
     end
 
-    klass = RDoc::TopLevel.classes_hash[full_name]
+    klass = @store.classes_hash[full_name]
 
     if klass then
       # if TopLevel, it may not be registered in the classes:
@@ -329,7 +349,7 @@ class RDoc::Context < RDoc::CodeObject
       end
     else
       # this is a new class
-      mod = RDoc::TopLevel.modules_hash.delete full_name
+      mod = @store.modules_hash.delete full_name
 
       if mod then
         klass = upgrade_to_class mod, RDoc::NormalClass, enclosing
@@ -339,10 +359,12 @@ class RDoc::Context < RDoc::CodeObject
         klass = class_type.new name, superclass
 
         enclosing.add_class_or_module(klass, enclosing.classes_hash,
-                                      RDoc::TopLevel.classes_hash)
+                                      @store.classes_hash)
       end
     end
 
+    klass.parent = self
+
     klass
   end
 
@@ -357,6 +379,7 @@ class RDoc::Context < RDoc::CodeObject
     mod.section = current_section # TODO declaring context? something is
                                   # wrong here...
     mod.parent = self
+    mod.store = @store
 
     unless @done_documenting then
       self_hash[mod.name] = mod
@@ -403,6 +426,15 @@ class RDoc::Context < RDoc::CodeObject
     include
   end
 
+  ##
+  # Adds extension module +ext+ which should be an RDoc::Extend
+
+  def add_extend ext
+    add_to @extends, ext
+
+    ext
+  end
+
   ##
   # Adds +method+ if not already there. If it is (as method or attribute),
   # updates the comment if it was empty.
@@ -416,6 +448,10 @@ class RDoc::Context < RDoc::CodeObject
 
     if known then
       known.comment = method.comment if known.comment.empty?
+      previously = ", previously in #{known.file}" unless
+        method.file == known.file
+      @store.rdoc.options.warn \
+        "Duplicate method #{known.full_name} in #{method.file}#{previously}"
     else
       @methods_hash[key] = method
       method.visibility = @visibility
@@ -435,9 +471,9 @@ class RDoc::Context < RDoc::CodeObject
     return mod if mod
 
     full_name = child_name name
-    mod = RDoc::TopLevel.modules_hash[full_name] || class_type.new(name)
+    mod = @store.modules_hash[full_name] || class_type.new(name)
 
-    add_class_or_module(mod, @modules, RDoc::TopLevel.modules_hash)
+    add_class_or_module mod, @modules, @store.modules_hash
   end
 
   ##
@@ -447,31 +483,34 @@ class RDoc::Context < RDoc::CodeObject
   def add_module_alias from, name, file
     return from if @done_documenting
 
-    to_name = child_name(name)
+    to_name = child_name name
 
     # if we already know this name, don't register an alias:
     # see the metaprogramming in lib/active_support/basic_object.rb,
-    # where we already know BasicObject as a class when we find
+    # where we already know BasicObject is a class when we find
     # BasicObject = BlankSlate
-    return from if RDoc::TopLevel.find_class_or_module(to_name)
+    return from if @store.find_class_or_module to_name
 
-    if from.module? then
-      RDoc::TopLevel.modules_hash[to_name] = from
-      @modules[name] = from
+    to = from.dup
+    to.name = name
+    to.full_name = nil
+
+    if to.module? then
+      @store.modules_hash[to_name] = to
+      @modules[name] = to
     else
-      RDoc::TopLevel.classes_hash[to_name] = from
-      @classes[name] = from
+      @store.classes_hash[to_name] = to
+      @classes[name] = to
     end
 
-    # HACK: register a constant for this alias:
-    # constant value and comment will be updated after,
-    # when the Ruby parser adds the constant
-    const = RDoc::Constant.new name, nil, ''
+    # Registers a constant for this alias.  The constant value and comment
+    # will be updated later, when the Ruby parser adds the constant
+    const = RDoc::Constant.new name, nil, to.comment
     const.record_location file
     const.is_alias_for = from
     add_constant const
 
-    from
+    to
   end
 
   ##
@@ -497,7 +536,7 @@ class RDoc::Context < RDoc::CodeObject
 
   def add_section title, comment = nil
     if section = @sections[title] then
-      section.comment = comment if comment
+      section.add_comment comment if comment
     else
       section = Section.new self, title, comment
       @sections[title] = section
@@ -509,9 +548,11 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Adds +thing+ to the collection +array+
 
-  def add_to(array, thing)
+  def add_to array, thing
     array << thing if @document_self
-    thing.parent = self
+
+    thing.parent  = self
+    thing.store   = @store if @store
     thing.section = current_section
   end
 
@@ -521,7 +562,7 @@ class RDoc::Context < RDoc::CodeObject
   # This means any of: comment, aliases, methods, attributes, external
   # aliases, require, constant.
   #
-  # Includes are also checked unless <tt>includes == false</tt>.
+  # Includes and extends are also checked unless <tt>includes == false</tt>.
 
   def any_content(includes = true)
     @any_content ||= !(
@@ -533,7 +574,7 @@ class RDoc::Context < RDoc::CodeObject
       @requires.empty? &&
       @constants.empty?
     )
-    @any_content || (includes && !@includes.empty?)
+    @any_content || (includes && !(@includes + @extends).empty? )
   end
 
   ##
@@ -616,6 +657,9 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Iterator for ancestors for duck-typing.  Does nothing.  See
   # RDoc::ClassModule#each_ancestor.
+  #
+  # This method exists to make it easy to work with Context subclasses that
+  # aren't part of RDoc.
 
   def each_ancestor # :nodoc:
   end
@@ -648,6 +692,13 @@ class RDoc::Context < RDoc::CodeObject
     @includes.each do |i| yield i end
   end
 
+  ##
+  # Iterator for extension modules
+
+  def each_extend # :yields: extend
+    @extends.each do |e| yield e end
+  end
+
   ##
   # Iterator for methods
 
@@ -671,9 +722,9 @@ class RDoc::Context < RDoc::CodeObject
     return enum_for __method__ unless block_given?
 
     constants  = @constants.group_by  do |constant|  constant.section end
-    constants.default = []
-
     attributes = @attributes.group_by do |attribute| attribute.section end
+
+    constants.default  = []
     attributes.default = []
 
     sort_sections.each do |section|
@@ -748,8 +799,8 @@ class RDoc::Context < RDoc::CodeObject
   ##
   # Finds a file with +name+ in this context
 
-  def find_file_named(name)
-    top_level.class.find_file_named(name)
+  def find_file_named name
+    @store.find_file_named name
   end
 
   ##
@@ -819,21 +870,21 @@ class RDoc::Context < RDoc::CodeObject
     # look for a class or module 'symbol'
     case symbol
     when /^::/ then
-      result = RDoc::TopLevel.find_class_or_module(symbol)
+      result = @store.find_class_or_module symbol
     when /^(\w+):+(.+)$/
       suffix = $2
       top = $1
       searched = self
-      loop do
+      while searched do
         mod = searched.find_module_named(top)
         break unless mod
-        result = RDoc::TopLevel.find_class_or_module(mod.full_name + '::' + suffix)
+        result = @store.find_class_or_module "#{mod.full_name}::#{suffix}"
         break if result || searched.is_a?(RDoc::TopLevel)
         searched = searched.parent
       end
     else
       searched = self
-      loop do
+      while searched do
         result = searched.find_module_named(symbol)
         break if result || searched.is_a?(RDoc::TopLevel)
         searched = searched.parent
@@ -1079,8 +1130,8 @@ class RDoc::Context < RDoc::CodeObject
   end
 
   ##
-  # Sorts sections alphabetically (default) or in TomDoc fasion (none, Public,
-  # Internal, Deprecated)
+  # Sorts sections alphabetically (default) or in TomDoc fashion (none,
+  # Public, Internal, Deprecated)
 
   def sort_sections
     titles = @sections.map { |title, _| title }
@@ -1122,10 +1173,11 @@ class RDoc::Context < RDoc::CodeObject
     enclosing.modules_hash.delete mod.name
 
     klass = RDoc::ClassModule.from_module class_type, mod
+    klass.store = @store
 
     # if it was there, then we keep it even if done_documenting
-    RDoc::TopLevel.classes_hash[mod.full_name] = klass
-    enclosing.classes_hash[mod.name]           = klass
+    @store.classes_hash[mod.full_name] = klass
+    enclosing.classes_hash[mod.name]   = klass
 
     klass
   end