123456789_123456789_123456789_123456789_123456789_

Class: RDoc::ClassModule

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
self, Context, Comparable, CodeObject, Generator::Markup, Text
Inherits: RDoc::Context
Defined in: lib/rdoc/class_module.rb,
lib/rdoc/generator/markup.rb

Overview

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

Constant Summary

Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Context - Inherited

TYPES

Class Method Summary

Context - Inherited

.new

Creates an unnamed empty context with public current visibility.

CodeObject - Inherited

.new

Creates a new CodeObject that will document itself and its children.

Instance Attribute Summary

Context - Inherited

#block_params

Block params to be used in the next MethodAttr parsed under this context.

#current_section

The current documentation section that new items will be added to.

#current_section=

Sets the current documentation section of documentation.

#params

Params to be used in the next MethodAttr parsed under this context.

#temporary_section

Use this section for the next method, attribute or constant added.

#unmatched_alias_lists

Hash old_name => [aliases], for aliases that haven't (yet) been resolved to a method/attribute.

#visibility

Current visibility of this context.

#aliases

Class/module aliases.

#attributes

All attr* methods.

#constants

Constants defined.

#constants_hash

Hash of registered constants.

#extends

Modules this context is extended with.

#external_aliases

Aliases that could not be resolved.

#fully_documented?

Does this context and its methods and constants all have documentation?

#in_files

Files this context is found in.

#includes

Modules this context includes.

#method_list

Methods defined in this context.

#methods_hash

Hash of registered methods.

#name

Name of this class excluding namespace.

#remove_from_documentation?

Should we remove this context from the documentation?

#requires

Files this context requires.

#ongoing_visibility=

Changes the visibility for new methods to visibility

CodeObject - Inherited

#comment

Our comment.

#comment=

Replaces our comment with comment, unless it is empty.

#document_children

Do we document our children?

#document_children=

Enables or disables documentation of this CodeObject's children unless it has been turned off by :enddoc:

#document_self

Do we document ourselves?

#document_self=

Enables or disables documentation of this CodeObject unless it has been turned off by :enddoc:.

#done_documenting

Are we done documenting (ie, did we come across a :enddoc:)?

#done_documenting=

Turns documentation on/off, and turns on/off #document_self and #document_children.

#force_documentation

Force documentation of this CodeObject.

#force_documentation=

Force the documentation of this object unless documentation has been turned off by :enddoc:

#line

Line in #file where this CodeObject was defined.

#offset

Offset in #file where this CodeObject was defined.

#parent

Our parent CodeObject.

#parent=

Sets the parent CodeObject.

#section

The section this CodeObject is in.

#section=

Set the section this CodeObject is in.

#store

The Store for this object.

#store=

Sets the store that contains this CodeObject.

#viewer

We are the model of the code, but we know that at some point we will be worked on by viewers.

#display?

Should this CodeObject be displayed in output?

#documented?

Does this object have a comment with content or is #received_nodoc true?

#file

Which file this code object was defined in.

#ignored?

Has this class been ignored?

#metadata

Hash of arbitrary metadata for this CodeObject.

#received_nodoc

Did we ever receive a :nodoc: directive?

#suppressed?

Has this class been suppressed?

#full_name=

Sets the full_name overriding any computed full name.

Instance Method Summary

Context - Inherited

#<=>

Contexts are sorted by full_name.

#add

Adds an item of type klass with the given name and comment to the context.

#add_alias

Adds an_alias that is automatically resolved.

#add_attribute

Adds attribute if not already there.

#add_class

Adds a class named given_name with #superclass.

#add_class_or_module

Adds the class or module mod to the modules or classes Hash self_hash, and to all_hash (either TopLevel.modules_hash or TopLevel.classes_hash), unless #done_documenting is true.

#add_constant

Adds constant if not already there.

#add_extend

Adds extension module ext which should be an Extend

#add_include

Adds included module include which should be an Include

#add_method

Adds method if not already there.

#add_module

Adds a module named name.

#add_module_alias

Adds an alias from from (a class or module) to name which was defined in file.

#add_require

Adds require to this context's top level.

#add_section

Returns a section with title, creating it if it doesn't already exist.

#add_to

Adds thing to the collection array

#any_content

Is there any content?

#child_name

Creates the full name for a child with name

#class_attributes

Class attributes.

#class_method_list

Class methods.

#classes

Array of classes in this context.

#classes_and_modules

All classes and modules in this namespace.

#classes_hash

Hash of classes keyed by class name.

#defined_in?

Is part of this thing was defined in file?

#each_attribute

Iterator for attributes.

#each_classmodule

Iterator for classes and modules.

#each_constant

Iterator for constants.

#each_extend

Iterator for extension modules.

#each_include

Iterator for included modules.

#each_method

Iterator for methods.

#each_section

Iterator for each section's contents sorted by title.

#find_attribute

Finds an attribute name with singleton value singleton.

#find_attribute_named

Finds an attribute with name in this context.

#find_class_method_named

Finds a class method with name in this context.

#find_constant_named

Finds a constant with name in this context.

#find_enclosing_module_named

Find a module at a higher scope.

#find_external_alias

Finds an external alias name with singleton value singleton.

#find_external_alias_named

Finds an external alias with name in this context.

#find_file_named

Finds a file with name in this context.

#find_instance_method_named

Finds an instance method with name in this context.

#find_local_symbol

Finds a method, constant, attribute, external alias, module or file named symbol in this context.

#find_method

Finds a method named name with singleton value singleton.

#find_method_named

Finds a instance or module method with name in this context.

#find_module_named

Find a module with name using ruby's scoping rules.

#find_symbol

Look up symbol, first as a module, then as a local symbol.

#find_symbol_module

Look up a module named symbol.

#full_name

The full name for this context.

#http_url

URL for this with a prefix

#initialize_methods_etc

Sets the defaults for methods and so-forth.

#instance_attributes

Instance attributes.

#instance_method_list

Instance methods.

#methods_by_type

Breaks method_list into a nested hash by type ('class' or 'instance') and visibility (:public, :protected, :private).

#methods_matching

Yields AnyMethod and Attr entries matching the list of names in methods.

#modules

Array of modules in this context.

#modules_hash

Hash of modules keyed by module name.

#name_for_path

Name to use to generate the url.

#record_location

Record top_level as a file self is in.

#remove_invisible

Removes methods and attributes with a visibility less than min_visibility.

#resolve_aliases

Tries to resolve unmatched aliases when a method or attribute has just been added.

#section_contents

Returns Context::Section objects referenced in this context for use in a table of contents.

#sections

Sections in this context.

#set_current_section

Sets the current section to a section with title.

#set_visibility_for

Given an array methods of method names, set the visibility of each to visibility

#sort_sections

Sorts sections alphabetically (default) or in TomDoc fashion (none, Public, Internal, Deprecated).

#top_level

Return the TopLevel that owns us.

#upgrade_to_class

Upgrades NormalModule mod in enclosing to a class_type

CodeObject - Inherited

#each_parent

Yields each parent of this CodeObject.

#file_name

File name where this CodeObject was found.

#ignore

Use this to ignore a CodeObject and all its children until found again (#record_location is called).

#options

The options instance from the store this CodeObject is attached to, or a default options instance if the CodeObject is not attached.

#parent_file_name

File name of our parent.

#parent_name

Name of our parent.

#record_location

Records the TopLevel (file) where this code object was defined.

#start_doc

Enable capture of documentation unless documentation has been turned off by :enddoc:

#stop_doc

Disable capture of documentation.

#suppress

Use this to suppress a CodeObject and all its children until the next file it is seen in or documentation is discovered.

Generator::Markup - Included

#aref_to

Generates a relative URL from this object's path to target_path

#as_href

Generates a relative URL from from_path to this object's path.

#cvs_url

Build a webcvs URL starting for the given url with full_path appended as the destination path.

#description

Handy wrapper for marking up this object's comment.

#formatter

Creates an Markup::ToHtmlCrossref formatter.

Text - Included

#expand_tabs

Expands tab characters in text to eight spaces.

#flush_left

Flush text left based on the shortest line.

#markup

Convert a string in markup format into HTML.

#normalize_comment

Strips hashes, expands tabs then flushes text to the left.

#parse

Normalizes text then builds a Markup::Document from it.

#snippet

The first limit characters of text as HTML.

#strip_hashes

Strips leading # characters from text

#strip_newlines

Strips leading and trailing n characters from text

#strip_stars

Strips /* */ style comments.

#to_html

Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in text to properly encoded characters.

#wrap

Wraps txt to line_len

Constructor Details

.new(name, superclass = nil) ⇒ ClassModule

Creates a new ClassModule with name with optional #superclass

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 111

def initialize(name, superclass = nil)
  @constant_aliases = []
  @diagram          = nil
  @is_alias_for     = nil
  @name             = name
  @superclass       = superclass
  @comment_location = [] # [[comment, location]]

  super()
end

Class Method Details

.from_module(class_type, mod)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 50

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.extends.concat mod.extends

  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..update mod.

  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.extends +
   klass.classes +
   klass.modules).each do |obj|
    obj.parent = klass
    obj.full_name = nil
  end

  klass
end

Instance Attribute Details

#comment_location (rw)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 35

attr_accessor :comment_location

#constant_aliases (rw)

Constants that are aliases for this class or module

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 30

attr_accessor :constant_aliases

#documented?Boolean (readonly)

Does this class or module have a comment with content or is #received_nodoc true?

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 239

def documented?
  return true if @received_nodoc
  return false if @comment_location.empty?
  @comment_location.any? { |comment, _| not comment.empty? }
end

#is_alias_for (rw)

Class or module this constant is an alias for

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 42

attr_accessor :is_alias_for

#module?Boolean (readonly)

Does this object represent a module?

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 568

def module?
  false
end

#name=(new_name) (writeonly)

Allows overriding the initial name.

Used for modules and classes that are constant aliases.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 577

def name= new_name
  @name = new_name
end

#store=(store) (writeonly)

Sets the store for this class or module and its contained code objects.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 685

def store= store
  super

  @attributes .each do |attr|  attr.store  = store end
  @constants  .each do |const| const.store = store end
  @includes   .each do |incl|  incl.store  = store end
  @extends    .each do |ext|   ext.store   = store end
  @method_list.each do |meth|  meth.store  = store end
end

#superclass (rw)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 699

def superclass
  @store.find_class_named(@superclass) || @superclass
end

#superclass=(superclass) (rw)

Set the superclass of this class to #superclass

Raises:

  • (NoMethodError)
[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 706

def superclass=(superclass)
  raise NoMethodError, "#{full_name} is a module" if module?
  @superclass = superclass
end

Instance Method Details

#add_comment(comment, location)

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.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 127

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.delete_if { |(_, l)| l == location }

  @comment_location << [comment, location]

  self.comment = original
end

#ancestors Also known as: #direct_ancestors

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 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.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 169

def ancestors
  includes.map { |i| i.module }.reverse
end

#aref

HTML fragment reference for this module or class. See RDoc::NormalClass#aref and RDoc::NormalModule#aref

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 181

def aref
  "#{aref_prefix}-#{full_name}"
end

#clear_comment

Clears the comment. Used by the Ruby parser.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 193

def clear_comment
  @comment = ''
end

#complete(min_visibility)

Prepares this ClassModule for use by a generator.

See Store#complete

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 221

def complete min_visibility
  update_aliases
  remove_nodoc_children
  update_includes
  remove_invisible min_visibility
end

#description

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

[ GitHub ]

  
# File 'lib/rdoc/generator/markup.rb', line 141

def description
  markup @comment_location
end

#direct_ancestors

Ancestors of this class or module only

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 188

alias direct_ancestors ancestors

#document_self_or_methods

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 231

def document_self_or_methods
  document_self || method_list.any?{ |m| m.document_self }
end

#each_ancestor

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 249

def each_ancestor # :yields: module
  return enum_for __method__ unless block_given?

  ancestors.each do |mod|
    next if String === mod
    next if self == mod
    yield mod
  end
end

#find_ancestor_local_symbol(symbol)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 262

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)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 274

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

Return the fully qualified name of this class or module

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 287

def full_name
  @full_name ||= if RDoc::ClassModule === parent then
                   "#{parent.full_name}::#{@name}"
                 else
                   @name
                 end
end

#merge(class_module)

Merges class_module into this ClassModule.

The data in class_module is preferred over the receiver.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 433

def merge class_module
  @parent      = class_module.parent
  @parent_name = class_module.parent_name

  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 extends, cm.extends, other_files do |add, ext|
    if add then
      add_extend ext
    else
      @extends.delete ext
    end
  end

  @extends.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

  merge_sections cm

  self
end

#name_for_path

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 620

def name_for_path
  is_alias_for ? is_alias_for.full_name : full_name
end

#non_aliases

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 629

def non_aliases
  @non_aliases ||= classes_and_modules.reject { |cm| cm.is_alias_for }
end

#parse(comment_location)

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 585

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

Path to this class or module for use with HTML generator output.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 611

def path
  http_url @store.rdoc.generator.class_dir
end

#remove_nodoc_children

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.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 641

def remove_nodoc_children
  prefix = self.full_name + '::'

  modules_hash.each_key do |name|
    full_name = prefix + name
    modules_hash.delete name unless @store.modules_hash[full_name]
  end

  classes_hash.each_key do |name|
    full_name = prefix + name
    classes_hash.delete name unless @store.classes_hash[full_name]
  end
end

#search_record

Search record used by Generator::JsonIndex

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 670

def search_record
  [
    name,
    full_name,
    full_name,
    '',
    path,
    '',
    snippet(@comment_location),
  ]
end

#type

'module' or 'class'

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 722

def type
  module? ? 'module' : 'class'
end

#update_aliases

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 Store#modules_hash or Store#classes_hash by a copy that has #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.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 741

def update_aliases
  constants.each do |const|
    next unless cm = const.is_alias_for
    cm_alias = cm.dup
    cm_alias.name = const.name

    # Don't move top-level aliases under Object, they look ugly there
    unless RDoc::TopLevel === cm_alias.parent then
      cm_alias.parent = self
      cm_alias.full_name = nil # force update for new parent
    end

    cm_alias.aliases.clear
    cm_alias.is_alias_for = cm

    if cm.module? then
      @store.modules_hash[cm_alias.full_name] = cm_alias
      modules_hash[const.name] = cm_alias
    else
      @store.classes_hash[cm_alias.full_name] = cm_alias
      classes_hash[const.name] = cm_alias
    end

    cm.aliases << cm_alias
  end
end

#update_extends

Deletes from #extends those whose module has been removed from the documentation.

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 789

def update_extends
  extends.reject! do |ext|
    mod = ext.module

    !(String === mod) && @store.modules_hash[mod.full_name].nil?
  end

  extends.uniq!
end

#update_includes

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

[ GitHub ]

  
# File 'lib/rdoc/class_module.rb', line 774

def update_includes
  includes.reject! do |include|
    mod = include.module
    !(String === mod) && @store.modules_hash[mod.full_name].nil?
  end

  includes.uniq!
end