rdoc 2.5.11 → 3.0

data/lib/rdoc/class_module.rb

@@ -8,31 +8,114 @@ class RDoc::ClassModule < RDoc::Context
 
   MARSHAL_VERSION = 0 # :nodoc:
 
-  attr_accessor :diagram
+  ##
+  # Constants that are aliases for this class or module
+
+  attr_accessor :constant_aliases
+
+  attr_accessor :diagram # :nodoc:
 
   ##
-  # Creates a new ClassModule with +name+ with optional +superclass+
+  # Class or module this constant is an alias for
 
-  def initialize(name, superclass = 'Object')
-    @diagram    = nil
-    @full_name  = nil
-    @name       = name
-    @superclass = superclass
+  attr_accessor :is_alias_for
+
+  ##
+  # Return a RDoc::ClassModule of class +class_type+ that is a copy
+  # of module +module+. Used to promote modules to classes.
+
+  def self.from_module(class_type, mod)
+    klass = class_type.new(mod.name)
+    klass.comment = mod.comment
+    klass.parent = mod.parent
+    klass.section = mod.section
+    klass.viewer = mod.viewer
+
+    klass.attributes.concat mod.attributes
+    klass.method_list.concat mod.method_list
+    klass.aliases.concat mod.aliases
+    klass.external_aliases.concat mod.external_aliases
+    klass.constants.concat mod.constants
+    klass.includes.concat mod.includes
+
+    klass.methods_hash.update mod.methods_hash
+    klass.constants_hash.update mod.constants_hash
+
+    klass.current_section = mod.current_section
+    klass.in_files.concat mod.in_files
+    klass.sections.concat mod.sections
+    klass.unmatched_alias_lists = mod.unmatched_alias_lists
+    klass.current_section = mod.current_section
+    klass.visibility = mod.visibility
+
+    klass.classes_hash.update mod.classes_hash
+    klass.modules_hash.update mod.modules_hash
+    klass.metadata.update mod.metadata
+
+    klass.document_self = mod.received_nodoc ? nil : mod.document_self
+    klass.document_children = mod.document_children
+    klass.force_documentation = mod.force_documentation
+    klass.done_documenting = mod.done_documenting
+
+    # update the parent of all children
+
+    (klass.attributes +
+     klass.method_list +
+     klass.aliases +
+     klass.external_aliases +
+     klass.constants +
+     klass.includes +
+     klass.classes +
+     klass.modules).each do |obj|
+      obj.parent = klass
+      obj.full_name = nil
+    end
+
+    klass
+  end
+
+  ##
+  # Creates a new ClassModule with +name+ with optional +superclass+
+  #
+  # This is a constructor for subclasses, and must never be called directly.
+
+  def initialize(name, superclass = nil)
+    @constant_aliases = []
+    @diagram          = nil
+    @is_alias_for     = nil
+    @name             = name
+    @superclass       = superclass
     super()
   end
 
   ##
-  # Ancestors list for this ClassModule (abstract)
+  # Ancestors list for this ClassModule: the list of included modules
+  # (classes will add their superclass if any).
+  #
+  # Returns the included classes or modules, not the includes
+  # themselves. The returned values are either String or
+  # RDoc::NormalModule instances (see RDoc::Include#module).
+  #
+  # The values are returned in reverse order of their inclusion,
+  # which is the order suitable for searching methods/attributes
+  # in the ancestors. The superclass, if any, comes last.
 
   def ancestors
-    raise NotImplementedError
+    includes.map { |i| i.module }.reverse
+  end
+
+  ##
+  # Clears the comment. Used by the ruby parser.
+
+  def clear_comment
+    @comment = ''
   end
 
   ##
   # Appends +comment+ to the current comment, but separated by a rule.  Works
   # more like <tt>+=</tt>.
 
-  def comment=(comment)
+  def comment= comment
     return if comment.empty?
 
     comment = "#{@comment}\n---\n#{normalize_comment comment}" unless
@@ -41,10 +124,35 @@ class RDoc::ClassModule < RDoc::Context
     super
   end
 
+  ##
+  # Prepares this ClassModule for use by a generator.
+  #
+  # See RDoc::TopLevel::complete
+
+  def complete min_visibility
+    update_aliases
+    remove_nodoc_children
+    update_includes
+    remove_invisible min_visibility
+  end
+
+  ##
+  # Looks for a symbol in the #ancestors. See Context#find_local_symbol.
+
+  def find_ancestor_local_symbol symbol
+    ancestors.each do |m|
+      next if m.is_a?(String)
+      res = m.find_local_symbol(symbol)
+      return res if res
+    end
+
+    nil
+  end
+
   ##
   # Finds a class or module with +name+ in this namespace or its descendents
 
-  def find_class_named(name)
+  def find_class_named name
     return self if full_name == name
     return self if @name == name
 
@@ -65,14 +173,8 @@ class RDoc::ClassModule < RDoc::Context
                    end
   end
 
-  ##
-  # 'module' or 'class'
-
-  def type
-    module? ? 'module' : 'class'
-  end
-
   def marshal_dump # :nodoc:
+    # TODO must store the singleton attribute
     attrs = attributes.sort.map do |attr|
       [attr.name, attr.rw]
     end
@@ -106,10 +208,13 @@ class RDoc::ClassModule < RDoc::Context
   end
 
   def marshal_load array # :nodoc:
+    # TODO must restore the singleton attribute
     initialize_methods_etc
     @document_self    = true
     @done_documenting = false
     @current_section  = nil
+    @parent           = nil
+    @visibility       = nil
 
     @name       = array[1]
     @full_name  = array[2]
@@ -183,6 +288,15 @@ class RDoc::ClassModule < RDoc::Context
     false
   end
 
+  ##
+  # Allows overriding the initial name.
+  #
+  # Used for modules and classes that are constant aliases.
+
+  def name= new_name
+    @name = new_name
+  end
+
   ##
   # Path to this class or module
 
@@ -190,12 +304,52 @@ class RDoc::ClassModule < RDoc::Context
     http_url RDoc::RDoc.current.generator.class_dir
   end
 
+  ##
+  # Name to use to generate the url:
+  # modules and classes that are aliases for another
+  # module or classe return the name of the latter.
+
+  def name_for_path
+    is_alias_for ? is_alias_for.full_name : full_name
+  end
+
+  ##
+  # Returns the classes and modules that are not constants
+  # aliasing another class or module. For use by formatters
+  # only (caches its result).
+
+  def non_aliases
+    @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
+  end
+
+  ##
+  # Updates the child modules or classes of class/module +parent+ by
+  # deleting the ones that have been removed from the documentation.
+  #
+  # +parent_hash+ is either <tt>parent.modules_hash</tt> or
+  # <tt>parent.classes_hash</tt> and +all_hash+ is ::all_modules_hash or
+  # ::all_classes_hash.
+
+  def remove_nodoc_children
+    prefix = self.full_name + '::'
+
+    modules_hash.each_key do |name|
+      full_name = prefix + name
+      modules_hash.delete name unless RDoc::TopLevel.all_modules_hash[full_name]
+    end
+
+    classes_hash.each_key do |name|
+      full_name = prefix + name
+      classes_hash.delete name unless RDoc::TopLevel.all_classes_hash[full_name]
+    end
+  end
+
   ##
   # Get the superclass of this class.  Attempts to retrieve the superclass
   # object, returns the name if it is not known.
 
   def superclass
-    RDoc::TopLevel.find_class_named_from(@superclass, parent) || @superclass
+    RDoc::TopLevel.find_class_named(@superclass) || @superclass
   end
 
   ##
@@ -203,12 +357,72 @@ class RDoc::ClassModule < RDoc::Context
 
   def superclass=(superclass)
     raise NoMethodError, "#{full_name} is a module" if module?
-
-    @superclass = superclass if @superclass.nil? or @superclass == 'Object'
+    @superclass = superclass
   end
 
   def to_s # :nodoc:
-    "#{self.class}: #{full_name} #{@comment} #{super}"
+    if is_alias_for then
+      "#{self.class.name} #{self.full_name} -> #{is_alias_for}"
+    else
+      super
+    end
+  end
+
+  ##
+  # 'module' or 'class'
+
+  def type
+    module? ? 'module' : 'class'
+  end
+
+  ##
+  # Updates the child modules & classes by replacing the ones that are
+  # aliases through a constant.
+  #
+  # The aliased module/class is replaced in the children and in
+  # RDoc::TopLevel::all_modules_hash or RDoc::TopLevel::all_classes_hash
+  # by a copy that has <tt>RDoc::ClassModule#is_alias_for</tt> set to
+  # the aliased module/class, and this copy is added to <tt>#aliases</tt>
+  # of the aliased module/class.
+  #
+  # Formatters can use the #non_aliases method to retrieve children that
+  # are not aliases, for instance to list the namespace content, since
+  # the aliased modules are included in the constants of the class/module,
+  # that are listed separately.
+
+  def update_aliases
+    constants.each do |const|
+      next unless cm = const.is_alias_for
+      cm_alias = cm.dup
+      cm_alias.name = const.name
+      cm_alias.parent = self
+      cm_alias.full_name = nil  # force update for new parent
+      cm_alias.aliases.clear
+      cm_alias.is_alias_for = cm
+
+      if cm.module? then
+        RDoc::TopLevel.all_modules_hash[cm_alias.full_name] = cm_alias
+        modules_hash[const.name] = cm_alias
+      else
+        RDoc::TopLevel.all_classes_hash[cm_alias.full_name] = cm_alias
+        classes_hash[const.name] = cm_alias
+      end
+
+      cm.aliases << cm_alias
+    end
+  end
+
+  ##
+  # Deletes from #includes those whose module has been removed from the
+  # documentation.
+  #--
+  # FIXME: includes are not reliably removed, see _possible_bug test case
+
+  def update_includes
+    includes.reject! do |include|
+      mod = include.module
+      !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
+    end
   end
 
 end

data/lib/rdoc/code_object.rb

@@ -12,15 +12,16 @@ require 'rdoc/text'
 # * RDoc::Context
 #   * RDoc::TopLevel
 #   * RDoc::ClassModule
-#     * RDoc::AnonClass
+#     * RDoc::AnonClass (never used so far)
 #     * RDoc::NormalClass
 #     * RDoc::NormalModule
 #     * RDoc::SingleClass
-# * RDoc::AnyMethod
-#   * RDoc::GhostMethod
-#   * RDoc::MetaMethod
+# * RDoc::MethodAttr
+#   * RDoc::Attr
+#   * RDoc::AnyMethod
+#     * RDoc::GhostMethod
+#     * RDoc::MetaMethod
 # * RDoc::Alias
-# * RDoc::Attr
 # * RDoc::Constant
 # * RDoc::Require
 # * RDoc::Include
@@ -47,12 +48,17 @@ class RDoc::CodeObject
   ##
   # Are we done documenting (ie, did we come across a :enddoc:)?
 
-  attr_accessor :done_documenting
+  attr_reader :done_documenting
+
+  ##
+  # Which file this code object was defined in
+
+  attr_reader :file
 
   ##
   # Force documentation of this CodeObject
 
-  attr_accessor :force_documentation
+  attr_reader :force_documentation
 
   ##
   # Hash of arbitrary metadata for this CodeObject
@@ -64,6 +70,11 @@ class RDoc::CodeObject
 
   attr_accessor :parent
 
+  ##
+  # Did we ever receive a +:nodoc:+ directive?
+
+  attr_reader :received_nodoc
+
   ##
   # Which section are we in
 
@@ -80,15 +91,17 @@ class RDoc::CodeObject
   # Creates a new CodeObject that will document itself and its children
 
   def initialize
-    @metadata = {}
-    @comment = ''
+    @metadata  = {}
+    @comment   = ''
+    @parent    = nil
+    @file      = nil
+    @full_name = nil
 
     @document_children   = true
     @document_self       = true
     @done_documenting    = false
     @force_documentation = false
-
-    @parent = nil
+    @received_nodoc      = false
   end
 
   ##
@@ -108,28 +121,64 @@ class RDoc::CodeObject
   end
 
   ##
-  # Enables or disables documentation of this CodeObject's children.  Calls
-  # remove_classes_and_modules when disabling.
+  # Enables or disables documentation of this CodeObject's children unless it
+  # has been turned off by :enddoc:
 
   def document_children=(document_children)
-    @document_children = document_children
-    remove_classes_and_modules unless document_children
+    @document_children = document_children unless @done_documenting
   end
 
   ##
-  # Enables or disables documentation of this CodeObject.  Calls
-  # remove_methods_etc when disabling.
+  # Enables or disables documentation of this CodeObject unless it has been
+  # turned off by :enddoc:.  If the argument is +nil+ it means the
+  # documentation is turned off by +:nodoc:+.
 
   def document_self=(document_self)
+    return if @done_documenting
+
     @document_self = document_self
-    remove_methods_etc unless document_self
+    @received_nodoc = true if document_self.nil?
   end
 
   ##
-  # Does this class have a comment with content or is document_self false.
+  # Does this object have a comment with content or is #received_nodoc true?
 
   def documented?
-    !(@document_self and @comment.empty?)
+    @received_nodoc or !@comment.empty?
+  end
+
+  ##
+  # Turns documentation on/off, and turns on/off #document_self
+  # and #document_children.
+  #
+  # Once documentation has been turned off (by +:enddoc:+),
+  # the object will refuse to turn #document_self or
+  # #document_children on, so +:doc:+ and +:start_doc:+ directives
+  # will have no effect in the current file.
+
+  def done_documenting=(value)
+    @done_documenting = value
+    @document_self = !value
+    @document_children = @document_self
+  end
+
+  ##
+  # Force the documentation of this object unless documentation
+  # has been turned off by :endoc:
+  #--
+  # HACK untested, was assigning to an ivar
+
+  def force_documentation=(value)
+    @force_documentation = value unless @done_documenting
+  end
+
+  ##
+  # Sets the full_name overriding any computed full name.
+  #
+  # Set to +nil+ to clear RDoc's cached value
+
+  def full_name= full_name
+    @full_name = full_name
   end
 
   ##
@@ -147,23 +196,19 @@ class RDoc::CodeObject
   end
 
   ##
-  # Callback called upon disabling documentation of children.  See
-  # #document_children=
-
-  def remove_classes_and_modules
-  end
-
-  ##
-  # Callback called upon disabling documentation of ourself.  See
-  # #document_self=
+  # Records the RDoc::TopLevel (file) where this code object was defined
 
-  def remove_methods_etc
+  def record_location top_level
+    @file = top_level
   end
 
   ##
-  # Enable capture of documentation
+  # Enable capture of documentation unless documentation has been
+  # turned off by :endoc:
 
   def start_doc
+    return if @done_documenting
+
     @document_self = true
     @document_children = true
   end