# class RDoc::ClassModule

ClassModule is the base class for objects representing either a class or a module.

### Attributes

comment_location[R]

Comment and the location it came from. Use add_comment to add comments

constant_aliases[RW]

Constants that are aliases for this class or module

is_alias_for[RW]

Class or module this constant is an alias for

### Public Class Methods

from_module(class_type, mod) click to toggle source

Return a RDoc::ClassModule of class `class_type` that is a copy of module `module`. Used to promote modules to classes.

    # File lib/rdoc/class_module.rb, line 40
    def self.from_module class_type, mod
      klass = class_type.new mod.name

      mod.comment_location.each do |comment, location|
        klass.add_comment comment, location
      end

      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

new(name, superclass = nil) click to toggle source

Creates a new ClassModule with `name` with optional `superclass`

This is a constructor for subclasses, and must never be called directly.

    # File lib/rdoc/class_module.rb, line 99
    def initialize(name, superclass = nil)
      @constant_aliases = []
      @diagram          = nil
      @is_alias_for     = nil
      @name             = name
      @superclass       = superclass
      @comment_location = [] # [[comment, location]]

      super()
    end

### Public Instance Methods

add_comment(comment, location) click to toggle source

Adds `comment` to this ClassModule’s list of comments at `location`. This method is preferred over comment= since it allows ri data to be updated across multiple runs.

    # File lib/rdoc/class_module.rb, line 115
    def add_comment comment, location
      return unless document_self

      original = comment

      comment = case comment
                when RDoc::Comment then
                  comment.normalize
                else
                  normalize_comment comment
                end
      @comment_location << [comment, location]

      self.comment = original
    end

ancestors() click to toggle source

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.

    # File lib/rdoc/class_module.rb, line 143
    def ancestors
      includes.map { |i| i.module }.reverse
    end

clear_comment() click to toggle source

Clears the comment. Used by the ruby parser.

    # File lib/rdoc/class_module.rb, line 150
    def clear_comment
      @comment = ''
    end

comment=(comment) click to toggle source

This method is deprecated, use add_comment instead.

Appends `comment` to the current comment, but separated by a rule. Works more like `+=`.

    # File lib/rdoc/class_module.rb, line 160
    def comment= comment
      comment = case comment
                when RDoc::Comment then
                  comment.normalize
                else
                  normalize_comment comment
                end

      comment = "#{@comment}\n---\n#{comment}" unless @comment.empty?

      super comment
    end

complete(min_visibility) click to toggle source

Prepares this ClassModule for use by a generator.

See RDoc::TopLevel.complete

    # File lib/rdoc/class_module.rb, line 178
    def complete min_visibility
      update_aliases
      remove_nodoc_children
      update_includes
      remove_invisible min_visibility
    end

description() click to toggle source

Handy wrapper for marking up this class or module’s comment

    # File lib/rdoc/generator/markup.rb, line 142
    def description
      markup @comment_location
    end

document_self_or_methods() click to toggle source

Does this ClassModule or any of its methods have document_self set?

    # File lib/rdoc/class_module.rb, line 188
    def document_self_or_methods
      document_self || method_list.any?{ |m| m.document_self }
    end

each_ancestor() { |module| ... } click to toggle source

Iterates the ancestors of this class or module for which an RDoc::ClassModule exists.

    # File lib/rdoc/class_module.rb, line 196
    def each_ancestor # :yields: module
      ancestors.each do |mod|
        next if String === mod
        yield mod
      end
    end

find_ancestor_local_symbol(symbol) click to toggle source

Looks for a symbol in the ancestors. See RDoc::Context#find_local_symbol.

    # File lib/rdoc/class_module.rb, line 206
    def find_ancestor_local_symbol symbol
      each_ancestor do |m|
        res = m.find_local_symbol(symbol)
        return res if res
      end

      nil
    end

find_class_named(name) click to toggle source

Finds a class or module with `name` in this namespace or its descendants

    # File lib/rdoc/class_module.rb, line 218
    def find_class_named name
      return self if full_name == name
      return self if @name == name

      @classes.values.find do |klass|
        next if klass == self
        klass.find_class_named name
      end
    end

full_name() click to toggle source

Return the fully qualified name of this class or module

    # File lib/rdoc/class_module.rb, line 231
    def full_name
      @full_name ||= if RDoc::ClassModule === @parent then
                       "#{@parent.full_name}::#{@name}"
                     else
                       @name
                     end
    end

merge(class_module) click to toggle source

Merges `class_module` into this ClassModule.

The data in `class_module` is preferred over the receiver.

    # File lib/rdoc/class_module.rb, line 337
    def merge class_module
      other_document = parse class_module.comment_location

      if other_document then
        document = parse @comment_location

        document = document.merge other_document

        @comment = @comment_location = document
      end

      cm = class_module
      other_files = cm.in_files

      merge_collections attributes, cm.attributes, other_files do |add, attr|
        if add then
          add_attribute attr
        else
          @attributes.delete attr
          @methods_hash.delete attr.pretty_name
        end
      end

      merge_collections constants, cm.constants, other_files do |add, const|
        if add then
          add_constant const
        else
          @constants.delete const
          @constants_hash.delete const.name
        end
      end

      merge_collections includes, cm.includes, other_files do |add, incl|
        if add then
          add_include incl
        else
          @includes.delete incl
        end
      end

      @includes.uniq! # clean up

      merge_collections method_list, cm.method_list, other_files do |add, meth|
        if add then
          add_method meth
        else
          @method_list.delete meth
          @methods_hash.delete meth.pretty_name
        end
      end

      self
    end

module?() click to toggle source

Does this object represent a module?

    # File lib/rdoc/class_module.rb, line 433
    def module?
      false
    end

name=(new_name) click to toggle source

Allows overriding the initial name.

Used for modules and classes that are constant aliases.

    # File lib/rdoc/class_module.rb, line 442
    def name= new_name
      @name = new_name
    end

name_for_path() click to toggle source

Name to use to generate the url: modules and classes that are aliases for another module or class return the name of the latter.

    # File lib/rdoc/class_module.rb, line 485
    def name_for_path
      is_alias_for ? is_alias_for.full_name : full_name
    end

non_aliases() click to toggle source

Returns the classes and modules that are not constants aliasing another class or module. For use by formatters only (caches its result).

    # File lib/rdoc/class_module.rb, line 494
    def non_aliases
      @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
    end

parse(comment_location) click to toggle source

Parses `comment_location` into an RDoc::Markup::Document composed of multiple RDoc::Markup::Documents with their file set.

    # File lib/rdoc/class_module.rb, line 450
    def parse comment_location
      case comment_location
      when String then
        super
      when Array then
        docs = comment_location.map do |comment, location|
          doc = super comment
          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
        raise ArgumentError, "unknown comment class #{comment_location.class}"
      end
    end

path() click to toggle source

Path to this class or module

    # File lib/rdoc/class_module.rb, line 476
    def path
      http_url RDoc::RDoc.current.generator.class_dir
    end

remove_nodoc_children() click to toggle source

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 `parent.modules_hash` or `parent.classes_hash` and `all_hash` is ::all_modules_hash or ::all_classes_hash.

    # File lib/rdoc/class_module.rb, line 506
    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

search_record() click to toggle source

Search record used by RDoc::Generator::JsonIndex

    # File lib/rdoc/class_module.rb, line 523
    def search_record
      [
        name,
        full_name,
        full_name,
        '',
        path,
        '',
        snippet(@comment_location),
      ]
    end

superclass() click to toggle source

Get the superclass of this class. Attempts to retrieve the superclass object, returns the name if it is not known.

    # File lib/rdoc/class_module.rb, line 539
    def superclass
      RDoc::TopLevel.find_class_named(@superclass) || @superclass
    end

superclass=(superclass) click to toggle source

Set the superclass of this class to `superclass`

    # File lib/rdoc/class_module.rb, line 546
    def superclass=(superclass)
      raise NoMethodError, "#{full_name} is a module" if module?
      @superclass = superclass
    end

type() click to toggle source

‘module’ or ‘class’

    # File lib/rdoc/class_module.rb, line 562
    def type
      module? ? 'module' : 'class'
    end

update_aliases() click to toggle source

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 `RDoc::ClassModule#is_alias_for` set to the aliased module/class, and this copy is added to `#aliases` 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.

    # File lib/rdoc/class_module.rb, line 581
    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

update_includes() click to toggle source

Deletes from includes those whose module has been removed from the documentation.

    # File lib/rdoc/class_module.rb, line 609
    def update_includes
      includes.reject! do |include|
        mod = include.module
        !(String === mod) && RDoc::TopLevel.all_modules_hash[mod.full_name].nil?
      end

      includes.uniq!
    end