Class: RDoc::Context

Relationships & Source Files
Namespace Children
Classes: `Section`
Extension / Inclusion / Inheritance Descendants
Subclasses: AnonClass, ClassModule, NormalClass, NormalModule, SingleClass, TopLevel
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `CodeObject`
Instance Chain: self, Comparable, `CodeObject`, `Generator::Markup`, `Text`
Inherits:	RDoc::CodeObject Object RDoc::CodeObject RDoc::Context
Defined in:	lib/rdoc/context.rb

Overview

A Context is something that can hold modules, classes, methods, attributes, aliases, requires, and includes. Classes, modules, and files are all Contexts.

Constant Summary

TOMDOC_TITLES = Internal use only

If a context has these titles it will be sorted in this order.

# File 'lib/rdoc/context.rb', line 19
```
[nil, 'Public', 'Internal', 'Deprecated']
```
TOMDOC_TITLES_SORT = Internal use only
# File 'lib/rdoc/context.rb', line 20
```
TOMDOC_TITLES.sort_by { |title| title.to_s }
```
TYPES =

Types of methods

# File 'lib/rdoc/context.rb', line 14
```
%w[class instance]
```

`Text` - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Method Summary

.new ⇒ Context constructor

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

#aliases readonly

Class/module aliases.
#attributes readonly

All attr* methods.
#block_params rw

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

Constants defined.
#constants_hash readonly

Hash of registered constants.
#current_line_visibility=(value) writeonly

Current visibility of this line.
#current_section rw

The current documentation section that new items will be added to.
#current_section=(value) rw

Sets the current documentation section of documentation.
#extends readonly

Modules this context is extended with.
#external_aliases readonly

Aliases that could not be resolved.
#fully_documented? ⇒ Boolean readonly

Does this context and its methods and constants all have documentation?
#in_files readonly

Files this context is found in.
#includes readonly

Modules this context includes.
#method_list readonly

Methods defined in this context.
#methods_hash readonly

Hash of registered methods.
#name readonly

Name of this class excluding namespace.
#ongoing_visibility=(visibility) writeonly

Changes the visibility for new methods to #visibility
#params rw

Params to be used in the next MethodAttr parsed under this context.
#remove_from_documentation? ⇒ Boolean readonly

Should we remove this context from the documentation?
#requires readonly

Files this context requires.
#temporary_section rw

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

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

Current visibility of this context.

`CodeObject` - Inherited

#comment	Our comment.
#comment=	Replaces our comment with `comment`, unless it is empty.
#display?	Should this `CodeObject` be displayed in output?
#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:.
#documented?	Does this object have a comment with content or is `#received_nodoc` true?
#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`.
#file	Which file this code object was defined in.
#force_documentation	Force documentation of this `CodeObject`.
#force_documentation=	Force the documentation of this object unless documentation has been turned off by :enddoc:
#full_name=	Sets the full_name overriding any computed full name.
#ignored?	Has this class been ignored?
#line	Line in `#file` where this `CodeObject` was defined.
#metadata	Hash of arbitrary metadata for this `CodeObject`.
#parent	Our parent `CodeObject`.
#parent=	Sets the parent `CodeObject`.
#received_nodoc	Did we ever receive a `:nodoc:` directive?
#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`.
#suppressed?	Has this class been suppressed?
#viewer	We are the model of the code, but we know that at some point we will be worked on by viewers.

`Text` - Included

#language

Instance Method Summary

#<=>(other)

Contexts are sorted by full_name.
#add(klass, name, comment)

Adds an item of type klass with the given #name and comment to the context.
#add_alias(an_alias)

Adds an_alias that is automatically resolved.
#add_attribute(attribute)

Adds attribute if not already there.
#add_class(class_type, given_name, superclass = '::Object')

Adds a class named given_name with superclass.
#add_class_or_module(mod, self_hash, all_hash)

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(constant)

Adds constant if not already there.
#add_extend(ext)

Adds extension module ext which should be an Extend
#add_include(include)

Adds included module include which should be an Include
#add_method(method)

Adds method if not already there.
#add_module(class_type, name)

Adds a module named #name.
#add_module_alias(from, from_name, to, file)

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

Adds a module by NormalModule instance.
#add_require(require)

Adds require to this context’s top level.
#add_section(title, comment = nil)

Returns a section with title, creating it if it doesn’t already exist.
#add_to(array, thing)

Adds thing to the collection array
#any_content(includes = true)

Is there any content?
#child_name(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?(file) ⇒ Boolean

Is part of this thing was defined in file?
#each_attribute

Iterator for attributes.
#each_classmodule(&block)

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(name, singleton)

Finds an attribute #name with singleton value singleton.
#find_attribute_named(name)

Finds an attribute with #name in this context.
#find_class_method_named(name)

Finds a class method with #name in this context.
#find_constant_named(name)

Finds a constant with #name in this context.
#find_enclosing_module_named(name)

Find a module at a higher scope.
#find_external_alias(name, singleton)

Finds an external alias #name with singleton value singleton.
#find_external_alias_named(name)

Finds an external alias with #name in this context.
#find_file_named(name)

Finds a file with #name in this context.
#find_instance_method_named(name)

Finds an instance method with #name in this context.
#find_local_symbol(symbol)

Finds a method, constant, attribute, external alias, module or file named symbol in this context.
#find_method(name, singleton)

Finds a method named #name with singleton value singleton.
#find_method_named(name)

Finds a instance or module method with #name in this context.
#find_module_named(name)

Find a module with #name using ruby’s scoping rules.
#find_symbol(symbol)

Look up symbol, first as a module, then as a local symbol.
#find_symbol_module(symbol)

Look up a module named symbol.
#full_name

The full name for this context.
#http_url(prefix)

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

Instance methods.
#methods_by_type(section = nil)

Breaks method_list into a nested hash by type ('class' or 'instance') and visibility (:public, :protected, :private).
#methods_matching(methods, singleton = false, &block)

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(top_level)

Record #top_level as a file self is in.
#remove_invisible(min_visibility)

Removes methods and attributes with a visibility less than min_visibility.
#resolve_aliases(added)

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

Returns Section objects referenced in this context for use in a table of contents.
#sections

Sections in this context.
#set_constant_visibility_for(names, visibility)

Given an array names of constants, set the visibility of each constant to #visibility
#set_current_section(title, comment)

Sets the current section to a section with title.
#set_visibility_for(methods, visibility, singleton = false)

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(mod, class_type, enclosing)

Upgrades NormalModule mod in enclosing to a class_type
#display(method_attr) Internal use only
#each_ancestor Internal use only

Iterator for ancestors for duck-typing.
#remove_invisible_in(array, min_visibility) Internal use only

Only called when min_visibility == :public or :private.
#sections_hash Internal use only
#to_s Internal use only

`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.
#initialize_visibility	Initializes state for visibility of this `CodeObject` and its children.

`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 ⇒ `Context`

Creates an unnamed empty context with public current visibility

[ GitHub ]

# File 'lib/rdoc/context.rb', line 123


def initialize
  super

  @in_files = []

  @name    ||= "unknown"
  @parent  = nil
  @visibility = :public

  @current_section = Section.new self, nil, nil
  @sections = { nil => @current_section }
  @temporary_section = nil

  @classes = {}
  @modules = {}

  initialize_methods_etc
end

Instance Attribute Details

#aliases (readonly)

Class/module aliases

[ GitHub ]

# File 'lib/rdoc/context.rb', line 25


attr_reader :aliases

#attributes (readonly)

All attr* methods

[ GitHub ]

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


attr_reader :attributes

#block_params (rw)

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

[ GitHub ]

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


attr_accessor :block_params

#constants (readonly)

Constants defined

[ GitHub ]

# File 'lib/rdoc/context.rb', line 40


attr_reader :constants

#constants_hash (readonly)

Hash of registered constants.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 118


attr_reader :constants_hash

#current_line_visibility=(value) (writeonly)

Current visibility of this line

[ GitHub ]

# File 'lib/rdoc/context.rb', line 102


attr_writer :current_line_visibility

#current_section (rw)

The current documentation section that new items will be added to. If temporary_section is available it will be used.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 681


def current_section
  if section = @temporary_section then
    @temporary_section = nil
  else
    section = @current_section
  end

  section
end

#current_section=(value) (rw)

Sets the current documentation section of documentation

[ GitHub ]

# File 'lib/rdoc/context.rb', line 45


attr_writer :current_section

#extends (readonly)

Modules this context is extended with

[ GitHub ]

# File 'lib/rdoc/context.rb', line 60


attr_reader :extends

#external_aliases (readonly)

Aliases that could not be resolved.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 92


attr_reader :external_aliases

#fully_documented? ⇒ `Boolean` (readonly)

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

(Yes, fully documented doesn’t mean everything.)

[ GitHub ]

# File 'lib/rdoc/context.rb', line 966


def fully_documented?
  documented? and
    attributes.all? { |a| a.documented? } and
    method_list.all? { |m| m.documented? } and
    constants.all? { |c| c.documented? }
end

#in_files (readonly)

Files this context is found in

[ GitHub ]

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


attr_reader :in_files

#includes (readonly)

Modules this context includes

[ GitHub ]

# File 'lib/rdoc/context.rb', line 55


attr_reader :includes

#method_list (readonly)

Methods defined in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 65


attr_reader :method_list

#methods_hash (readonly)

Hash of registered methods. Attributes are also registered here, twice if they are RW.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 108


attr_reader :methods_hash

#name (readonly)

Name of this class excluding namespace. See also full_name

[ GitHub ]

# File 'lib/rdoc/context.rb', line 70


attr_reader :name

#ongoing_visibility=(visibility) (writeonly)

Changes the visibility for new methods to #visibility

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1073


def ongoing_visibility=(visibility)
  @visibility = visibility
end

#params (rw)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 113


attr_accessor :params

#remove_from_documentation? ⇒ `Boolean` (readonly)

Should we remove this context from the documentation?

The answer is yes if:

#received_nodoc is true
#any_content is false (not counting includes)
All #includes are modules (not a string), and their module has #remove_from_documentation? == true
All classes and modules have #remove_from_documentation? == true

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1094


def remove_from_documentation?
  @remove_from_documentation ||=
    @received_nodoc &&
    !any_content(false) &&
    @includes.all? { |i| !i.module.is_a?(String) && i.module.remove_from_documentation? } &&
    classes_and_modules.all? { |cm| cm.remove_from_documentation? }
end

#requires (readonly)

Files this context requires

[ GitHub ]

# File 'lib/rdoc/context.rb', line 75


attr_reader :requires

#temporary_section (rw)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 80


attr_accessor :temporary_section

#unmatched_alias_lists (rw)

Hash old_name => [aliases], for aliases that haven’t (yet) been resolved to a method/attribute. (Not to be confused with the aliases of the context.)

[ GitHub ]

# File 'lib/rdoc/context.rb', line 87


attr_accessor :unmatched_alias_lists

#visibility (rw)

Current visibility of this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 97


attr_accessor :visibility

Instance Method Details

#<=>(other)

Contexts are sorted by full_name

[ GitHub ]

# File 'lib/rdoc/context.rb', line 171


def <=>(other)
  return nil unless RDoc::CodeObject === other

  full_name <=> other.full_name
end

#add(klass, name, comment)

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

Currently only Extend and Include are supported.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 183


def add klass, name, comment
  if RDoc::Extend == klass then
    ext = RDoc::Extend.new name, comment
    add_extend ext
  elsif RDoc::Include == klass then
    incl = RDoc::Include.new name, comment
    add_include incl
  else
    raise NotImplementedError, "adding a #{klass} is not implemented"
  end
end

#add_alias(an_alias)

Adds an_alias that is automatically resolved

[ GitHub ]

# File 'lib/rdoc/context.rb', line 198


def add_alias an_alias
  return an_alias unless @document_self

  method_attr = find_method(an_alias.old_name, an_alias.singleton) ||
                find_attribute(an_alias.old_name, an_alias.singleton)

  if method_attr then
    method_attr.add_alias an_alias, self
  else
    add_to @external_aliases, an_alias
    unmatched_alias_list =
      @unmatched_alias_lists[an_alias.pretty_old_name] ||= []
    unmatched_alias_list.push an_alias
  end

  an_alias
end

#add_attribute(attribute)

Adds attribute if not already there. If it is (as method(s) or attribute), updates the comment if it was empty.

The attribute is registered only if it defines a new method. For instance, attr_reader :foo will not be registered if method foo exists, but attr_accessor :foo will be registered if method foo exists, but foo= does not.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 225


def add_attribute attribute
  return attribute unless @document_self

  # mainly to check for redefinition of an attribute as a method
  # TODO find a policy for 'attr_reader :foo' + 'def foo=()'
  register = false

  key = nil

  if attribute.rw.index 'R' then
    key = attribute.pretty_name
    known = @methods_hash[key]

    if known then
      known.comment = attribute.comment if known.comment.empty?
    elsif registered = @methods_hash[attribute.pretty_name + '='] and
          RDoc::Attr === registered then
      registered.rw = 'RW'
    else
      @methods_hash[key] = attribute
      register = true
    end
  end

  if attribute.rw.index 'W' then
    key = attribute.pretty_name + '='
    known = @methods_hash[key]

    if known then
      known.comment = attribute.comment if known.comment.empty?
    elsif registered = @methods_hash[attribute.pretty_name] and
          RDoc::Attr === registered then
      registered.rw = 'RW'
    else
      @methods_hash[key] = attribute
      register = true
    end
  end

  if register then
    attribute.visibility = @visibility
    add_to @attributes, attribute
    resolve_aliases attribute
  end

  attribute
end

#add_class(class_type, given_name, superclass = '::Object')

Adds a class named given_name with superclass.

Both given_name and superclass may contain ‘::’, and are interpreted relative to the self context. This allows handling correctly examples like these:

class RDoc::Gauntlet < Gauntlet
module Mod
  class Object   # implies < ::Object
  class SubObject < Object  # this is _not_ ::Object

Given class Container::Item RDoc assumes Container is a module unless it later sees class Container. add_class automatically upgrades given_name to a class in this case.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 288


def add_class class_type, given_name, superclass = '::Object'
  # superclass nil is passed by the C parser in the following cases:
  # - registering Object in 1.8 (correct)
  # - registering BasicObject in 1.9 (correct)
  # - registering RubyVM in 1.9 in iseq.c (incorrect: < Object in vm.c)
  #
  # If we later find a superclass for a registered class with a nil
  # superclass, we must honor it.

  # find the name & enclosing context
  if given_name =~ /^:(\w)$/ then
    full_name = $1
    enclosing = top_level
    name = full_name.split(/:+/).last
  else
    full_name = child_name given_name

    if full_name =~ /^(.)::(\w)$/ then
      name = $2
      ename = $1
      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 = @store.classes_hash[given_name] ||
                    @store.modules_hash[given_name]
        return enclosing if enclosing
        # not found: create the parent(s)
        names = ename.split('::')
        enclosing = self
        names.each do |n|
          enclosing = enclosing.classes_hash[n] ||
                      enclosing.modules_hash[n] ||
                      enclosing.add_module(RDoc::NormalModule, n)
        end
      end
    else
      name = full_name
      enclosing = self
    end
  end

  # fix up superclass
  if full_name == 'BasicObject' then
    superclass = nil
  elsif full_name == 'Object' then
    superclass = '::BasicObject'
  end

  # find the superclass full name
  if superclass then
    if superclass =~ /^:+/ then
      superclass = $' #'
    else
      if superclass =~ /^(\w):(.+)$/ then
        suffix = $2
        mod = find_module_named($1)
        superclass = mod.full_name + '::' + suffix if mod
      else
        mod = find_module_named(superclass)
        superclass = mod.full_name if mod
      end
    end

    # did we believe it was a module?
    mod = @store.modules_hash.delete superclass

    upgrade_to_class mod, RDoc::NormalClass, mod.parent if mod

    # e.g., Object < Object
    superclass = nil if superclass == full_name
  end

  klass = @store.classes_hash[full_name]

  if klass then
    # if TopLevel, it may not be registered in the classes:
    enclosing.classes_hash[name] = klass

    # update the superclass if needed
    if superclass then
      existing = klass.superclass
      existing = existing.full_name unless existing.is_a?(String) if existing
      if existing.nil? ||
         (existing == 'Object' && superclass != 'Object') then
        klass.superclass = superclass
      end
    end
  else
    # this is a new class
    mod = @store.modules_hash.delete full_name

    if mod then
      klass = upgrade_to_class mod, RDoc::NormalClass, enclosing

      klass.superclass = superclass unless superclass.nil?
    else
      klass = class_type.new name, superclass

      enclosing.add_class_or_module(klass, enclosing.classes_hash,
                                    @store.classes_hash)
    end
  end

  klass.parent = self

  klass
end

#add_class_or_module(mod, self_hash, all_hash)

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. Sets the #parent of mod to self, and its #section to #current_section. Returns mod.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 404


def add_class_or_module mod, self_hash, all_hash
  mod.section = current_section # TODO declaring context? something is
                                # wrong here...
  mod.parent = self
  mod.full_name = nil
  mod.store = @store

  unless @done_documenting then
    self_hash[mod.name] = mod
    # this must be done AFTER adding mod to its parent, so that the full
    # name is correct:
    all_hash[mod.full_name] = mod
    if @store.unmatched_constant_alias[mod.full_name] then
      to, file = @store.unmatched_constant_alias[mod.full_name]
      add_module_alias mod, mod.name, to, file
    end
  end

  mod
end

#add_constant(constant)

Adds constant if not already there. If it is, updates the comment, value and/or is_alias_for of the known constant if they were empty/nil.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 429


def add_constant constant
  return constant unless @document_self

  # HACK: avoid duplicate 'PI' & 'E' in math.c (1.8.7 source code)
  # (this is a #ifdef: should be handled by the C parser)
  known = @constants_hash[constant.name]

  if known then
    known.comment = constant.comment if known.comment.empty?

    known.value = constant.value if
      known.value.nil? or known.value.strip.empty?

    known.is_alias_for ||= constant.is_alias_for
  else
    @constants_hash[constant.name] = constant
    add_to @constants, constant
  end

  constant
end

#add_extend(ext)

Adds extension module ext which should be an Extend

[ GitHub ]

# File 'lib/rdoc/context.rb', line 463


def add_extend ext
  add_to @extends, ext

  ext
end

#add_include(include)

Adds included module include which should be an Include

[ GitHub ]

# File 'lib/rdoc/context.rb', line 454


def add_include include
  add_to @includes, include

  include
end

#add_method(method)

Adds method if not already there. If it is (as method or attribute), updates the comment if it was empty.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 473


def add_method method
  return method unless @document_self

  # HACK: avoid duplicate 'new' in io.c & struct.c (1.8.7 source code)
  key = method.pretty_name
  known = @methods_hash[key]

  if known then
    if @store then # otherwise we are loading
      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}"
    end
  else
    @methods_hash[key] = method
    if @current_line_visibility
      method.visibility, @current_line_visibility = @current_line_visibility, nil
    else
      method.visibility = @visibility
    end
    add_to @method_list, method
    resolve_aliases method
  end

  method
end

#add_module(class_type, name)

Adds a module named #name. If RDoc already knows #name is a class then that class is returned instead. See also #add_class.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 506


def add_module(class_type, name)
  mod = @classes[name] || @modules[name]
  return mod if mod

  full_name = child_name name
  mod = @store.modules_hash[full_name] || class_type.new(name)

  add_class_or_module mod, @modules, @store.modules_hash
end

#add_module_alias(from, from_name, to, file)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 527


def add_module_alias from, from_name, to, file
  return from if @done_documenting

  to_full_name = child_name to.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 is a class when we find
  # BasicObject = BlankSlate
  return from if @store.find_class_or_module to_full_name

  unless from
    @store.unmatched_constant_alias[child_name(from_name)] = [to, file]
    return to
  end

  new_to = from.dup
  new_to.name = to.name
  new_to.full_name = nil

  if new_to.module? then
    @store.modules_hash[to_full_name] = new_to
    @modules[to.name] = new_to
  else
    @store.classes_hash[to_full_name] = new_to
    @classes[to.name] = new_to
  end

  # 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 to.name, nil, new_to.comment
  const.record_location file
  const.is_alias_for = from
  add_constant const

  new_to
end

#add_module_by_normal_module(mod)

Adds a module by NormalModule instance. See also #add_module.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 519


def add_module_by_normal_module(mod)
  add_class_or_module mod, @modules, @store.modules_hash
end

#add_require(require)

Adds require to this context’s top level

[ GitHub ]

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


def add_require(require)
  return require unless @document_self

  if RDoc::TopLevel === self then
    add_to @requires, require
  else
    parent.add_require require
  end
end

#add_section(title, comment = nil)

Returns a section with title, creating it if it doesn’t already exist. comment will be appended to the section’s comment.

A section with a title of nil will return the default section.

#add_to(array, thing)

Adds thing to the collection array

[ GitHub ]

# File 'lib/rdoc/context.rb', line 600


def add_to array, thing
  array << thing if @document_self

  thing.parent  = self
  thing.store   = @store if @store
  thing.section = current_section
end

#any_content(includes = true)

Is there any content?

This means any of: comment, aliases, methods, attributes, external aliases, require, constant.

Includes and extends are also checked unless includes == false.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 616


def any_content(includes = true)
  @any_content ||= !(
    @comment.empty? &&
    @method_list.empty? &&
    @attributes.empty? &&
    @aliases.empty? &&
    @external_aliases.empty? &&
    @requires.empty? &&
    @constants.empty?
  )
  @any_content || (includes && !(@includes + @extends).empty? )
end

#child_name(name)

Creates the full name for a child with #name

[ GitHub ]

# File 'lib/rdoc/context.rb', line 632


def child_name name
  if name =~ /^:+/
    $'  #'
  elsif RDoc::TopLevel === self then
    name
  else
    "#{self.full_name}::#{name}"
  end
end

#class_attributes

Class attributes

[ GitHub ]

# File 'lib/rdoc/context.rb', line 645


def class_attributes
  @class_attributes ||= attributes.select { |a| a.singleton }
end

#class_method_list

Class methods

[ GitHub ]

# File 'lib/rdoc/context.rb', line 652


def class_method_list
  @class_method_list ||= method_list.select { |a| a.singleton }
end

#classes

Array of classes in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 659


def classes
  @classes.values
end

#classes_and_modules

All classes and modules in this namespace

[ GitHub ]

# File 'lib/rdoc/context.rb', line 666


def classes_and_modules
  classes + modules
end

#classes_hash

Hash of classes keyed by class name

[ GitHub ]

# File 'lib/rdoc/context.rb', line 673


def classes_hash
  @classes
end

#defined_in?(file) ⇒ `Boolean`

Is part of this thing was defined in file?

[ GitHub ]

# File 'lib/rdoc/context.rb', line 694


def defined_in?(file)
  @in_files.include?(file)
end

#display(method_attr)

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 698


def display(method_attr) # :nodoc:
  if method_attr.is_a? RDoc::Attr
    "#{method_attr.definition} #{method_attr.pretty_name}"
  else
    "method #{method_attr.pretty_name}"
  end
end

#each_ancestor

This method is for internal use only.

Iterator for ancestors for duck-typing. Does nothing. See ClassModule#each_ancestor.

This method exists to make it easy to work with Context subclasses that aren’t part of RDoc.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 713


def each_ancestor # :nodoc:
end

#each_attribute

Iterator for attributes

[ GitHub ]

# File 'lib/rdoc/context.rb', line 719


def each_attribute # :yields: attribute
  @attributes.each { |a| yield a }
end

#each_classmodule(&block)

Iterator for classes and modules

[ GitHub ]

# File 'lib/rdoc/context.rb', line 726


def each_classmodule(&block) # :yields: module
  classes_and_modules.sort.each(&block)
end

#each_constant

Iterator for constants

[ GitHub ]

# File 'lib/rdoc/context.rb', line 733


def each_constant # :yields: constant
  @constants.each {|c| yield c}
end

#each_extend

Iterator for extension modules

[ GitHub ]

# File 'lib/rdoc/context.rb', line 747


def each_extend # :yields: extend
  @extends.each do |e| yield e end
end

#each_include

Iterator for included modules

[ GitHub ]

# File 'lib/rdoc/context.rb', line 740


def each_include # :yields: include
  @includes.each do |i| yield i end
end

#each_method

Iterator for methods

[ GitHub ]

# File 'lib/rdoc/context.rb', line 754


def each_method # :yields: method
  return enum_for __method__ unless block_given?

  @method_list.sort.each { |m| yield m }
end

#each_section

Iterator for each section’s contents sorted by title. The section, the section’s #constants and the sections #attributes are yielded. The #constants and #attributes collections are sorted.

To retrieve methods in a section use #methods_by_type with the optional section parameter.

NOTE: Do not edit collections yielded by this method

[ GitHub ]

# File 'lib/rdoc/context.rb', line 770


def each_section # :yields: section, constants, attributes
  return enum_for __method__ unless block_given?

  constants  = @constants.group_by  do |constant|  constant.section end
  attributes = @attributes.group_by do |attribute| attribute.section end

  constants.default  = []
  attributes.default = []

  sort_sections.each do |section|
    yield section, constants[section].select(&:display?).sort, attributes[section].select(&:display?).sort
  end
end

#find_attribute(name, singleton)

Finds an attribute #name with singleton value singleton.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 787


def find_attribute(name, singleton)
  name = $1 if name =~ /^(.*)=$/
  @attributes.find { |a| a.name == name && a.singleton == singleton }
end

#find_attribute_named(name)

Finds an attribute with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 795


def find_attribute_named(name)
  case name
  when /\A#/ then
    find_attribute name[1..-1], false
  when /\A::/ then
    find_attribute name[2..-1], true
  else
    @attributes.find { |a| a.name == name }
  end
end

#find_class_method_named(name)

Finds a class method with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 809


def find_class_method_named(name)
  @method_list.find { |meth| meth.singleton && meth.name == name }
end

#find_constant_named(name)

Finds a constant with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 816


def find_constant_named(name)
  @constants.find do |m|
    m.name == name || m.full_name == name
  end
end

#find_enclosing_module_named(name)

Find a module at a higher scope

[ GitHub ]

# File 'lib/rdoc/context.rb', line 825


def find_enclosing_module_named(name)
  parent && parent.find_module_named(name)
end

#find_external_alias(name, singleton)

Finds an external alias #name with singleton value singleton.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 832


def find_external_alias(name, singleton)
  @external_aliases.find { |m| m.name == name && m.singleton == singleton }
end

#find_external_alias_named(name)

Finds an external alias with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 839


def find_external_alias_named(name)
  case name
  when /\A#/ then
    find_external_alias name[1..-1], false
  when /\A::/ then
    find_external_alias name[2..-1], true
  else
    @external_aliases.find { |a| a.name == name }
  end
end

#find_file_named(name)

Finds a file with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 853


def find_file_named name
  @store.find_file_named name
end

#find_instance_method_named(name)

Finds an instance method with #name in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 860


def find_instance_method_named(name)
  @method_list.find { |meth| !meth.singleton && meth.name == name }
end

#find_local_symbol(symbol)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 868


def find_local_symbol(symbol)
  find_method_named(symbol) or
  find_constant_named(symbol) or
  find_attribute_named(symbol) or
  find_external_alias_named(symbol) or
  find_module_named(symbol) or
  find_file_named(symbol)
end

#find_method(name, singleton)

Finds a method named #name with singleton value singleton.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 880


def find_method(name, singleton)
  @method_list.find { |m|
    if m.singleton
      m.name == name && m.singleton == singleton
    else
      m.name == name && !m.singleton && !singleton
    end
  }
end

#find_method_named(name)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 893


def find_method_named(name)
  case name
  when /\A#/ then
    find_method name[1..-1], false
  when /\A::/ then
    find_method name[2..-1], true
  else
    @method_list.find { |meth| meth.name == name }
  end
end

#find_module_named(name)

Find a module with #name using ruby’s scoping rules

[ GitHub ]

# File 'lib/rdoc/context.rb', line 907


def find_module_named(name)
  res = @modules[name] || @classes[name]
  return res if res
  return self if self.name == name
  find_enclosing_module_named name
end

#find_symbol(symbol)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 917


def find_symbol(symbol)
  find_symbol_module(symbol) || find_local_symbol(symbol)
end

#find_symbol_module(symbol)

Look up a module named symbol.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 924


def find_symbol_module(symbol)
  result = nil

  # look for a class or module 'symbol'
  case symbol
  when /^::/ then
    result = @store.find_class_or_module symbol
  when /^(\w):(.+)$/
    suffix = $2
    top = $1
    searched = self
    while searched do
      mod = searched.find_module_named(top)
      break unless mod
      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
    while searched do
      result = searched.find_module_named(symbol)
      break if result || searched.is_a?(RDoc::TopLevel)
      searched = searched.parent
    end
  end

  result
end

#full_name

The full name for this context. This method is overridden by subclasses.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 957


def full_name
  '(unknown)'
end

#http_url(prefix)

URL for this with a prefix

[ GitHub ]

# File 'lib/rdoc/context.rb', line 976


def http_url(prefix)
  path = name_for_path
  path = path.gsub(/<<\s*(\w*)/, 'from-\1') if path =~ /<</
  path = [prefix] + path.split('::')

  File.join(*path.compact) + '.html'
end

#initialize_methods_etc

Sets the defaults for methods and so-forth

[ GitHub ]

# File 'lib/rdoc/context.rb', line 145


def initialize_methods_etc
  @method_list = []
  @attributes  = []
  @aliases     = []
  @requires    = []
  @includes    = []
  @extends     = []
  @constants   = []
  @external_aliases = []
  @current_line_visibility = nil

  # This Hash maps a method name to a list of unmatched aliases (aliases of
  # a method not yet encountered).
  @unmatched_alias_lists = {}

  @methods_hash   = {}
  @constants_hash = {}

  @params = nil

  @store ||= nil
end

#instance_attributes

Instance attributes

[ GitHub ]

# File 'lib/rdoc/context.rb', line 987


def instance_attributes
  @instance_attributes ||= attributes.reject { |a| a.singleton }
end

#instance_method_list

Instance methods

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1003


def instance_method_list
  warn '#instance_method_list is obsoleted, please use #instance_methods'
  @instance_methods ||= method_list.reject { |a| a.singleton }
end

#instance_methods

Instance methods

[ GitHub ]

# File 'lib/rdoc/context.rb', line 994


def instance_methods
  @instance_methods ||= method_list.reject { |a| a.singleton }
end

#methods_by_type(section = nil)

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

If section is provided only methods in that Context::Section will be returned.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1015


def methods_by_type section = nil
  methods = {}

  TYPES.each do |type|
    visibilities = {}
    RDoc::VISIBILITIES.each do |vis|
      visibilities[vis] = []
    end

    methods[type] = visibilities
  end

  each_method do |method|
    next if section and not method.section == section
    methods[method.type][method.visibility] << method
  end

  methods
end

#methods_matching(methods, singleton = false, &block)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1038


def methods_matching(methods, singleton = false, &block)
  (@method_list + @attributes).each do |m|
    yield m if methods.include?(m.name) and m.singleton == singleton
  end

  each_ancestor do |parent|
    parent.methods_matching(methods, singleton, &block)
  end
end

#modules

Array of modules in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1051


def modules
  @modules.values
end

#modules_hash

Hash of modules keyed by module name

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1058


def modules_hash
  @modules
end

#name_for_path

Name to use to generate the url. #full_name by default.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1066


def name_for_path
  full_name
end

#record_location(top_level)

Record #top_level as a file self is in.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1080


def record_location(top_level)
  @in_files << top_level unless @in_files.include?(top_level)
end

#remove_invisible(min_visibility)

Removes methods and attributes with a visibility less than min_visibility.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1107


def remove_invisible min_visibility
  return if [:private, :nodoc].include? min_visibility
  remove_invisible_in @method_list, min_visibility
  remove_invisible_in @attributes, min_visibility
  remove_invisible_in @constants, min_visibility
end

#remove_invisible_in(array, min_visibility)

This method is for internal use only.

Only called when min_visibility == :public or :private

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1117


def remove_invisible_in array, min_visibility # :nodoc:
  if min_visibility == :public then
    array.reject! { |e|
      e.visibility != :public and not e.force_documentation
    }
  else
    array.reject! { |e|
      e.visibility == :private and not e.force_documentation
    }
  end
end

#resolve_aliases(added)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1133


def resolve_aliases added
  # resolve any pending unmatched aliases
  key = added.pretty_name
  unmatched_alias_list = @unmatched_alias_lists[key]
  return unless unmatched_alias_list
  unmatched_alias_list.each do |unmatched_alias|
    added.add_alias unmatched_alias, self
    @external_aliases.delete unmatched_alias
  end
  @unmatched_alias_lists.delete key
end

#section_contents

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1149


def section_contents
  used_sections = {}

  each_method do |method|
    next unless method.display?

    used_sections[method.section] = true
  end

  # order found sections
  sections = sort_sections.select do |section|
    used_sections[section]
  end

  # only the default section is used
  return [] if
    sections.length == 1 and not sections.first.title

  sections
end

#sections

Sections in this context

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1173


def sections
  @sections.values
end

#sections_hash

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1177


def sections_hash # :nodoc:
  @sections
end

#set_constant_visibility_for(names, visibility)

Given an array names of constants, set the visibility of each constant to #visibility

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1202


def set_constant_visibility_for(names, visibility)
  names.each do |name|
    constant = @constants_hash[name] or next
    constant.visibility = visibility
  end
end

#set_current_section(title, comment)

Sets the current section to a section with title. See also #add_section

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1184


def set_current_section title, comment
  @current_section = add_section title, comment
end

#set_visibility_for(methods, visibility, singleton = false)

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1192


def set_visibility_for(methods, visibility, singleton = false)
  methods_matching methods, singleton do |m|
    m.visibility = visibility
  end
end

#sort_sections

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

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1213


def sort_sections
  titles = @sections.map { |title, _| title }

  if titles.length > 1 and
     TOMDOC_TITLES_SORT ==
       (titles | TOMDOC_TITLES).sort_by { |title| title.to_s } then
    @sections.values_at(*TOMDOC_TITLES).compact
  else
    @sections.sort_by { |title, _|
      title.to_s
    }.map { |_, section|
      section
    }
  end
end

#to_s

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1229


def to_s # :nodoc:
  "#{self.class.name} #{self.full_name}"
end

#top_level

Return the TopLevel that owns us

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1239


def top_level
  return @top_level if defined? @top_level
  @top_level = self
  @top_level = @top_level.parent until RDoc::TopLevel === @top_level
  @top_level
end

#upgrade_to_class(mod, class_type, enclosing)

Upgrades NormalModule mod in enclosing to a class_type

[ GitHub ]

# File 'lib/rdoc/context.rb', line 1249


def upgrade_to_class mod, class_type, enclosing
  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
  @store.classes_hash[mod.full_name] = klass
  enclosing.classes_hash[mod.name]   = klass

  klass
end

Class: RDoc::Context

Overview

Constant Summary

Text - Included

Class Method Summary

CodeObject - Inherited

Instance Attribute Summary

CodeObject - Inherited

Text - Included

Instance Method Summary

CodeObject - Inherited

Generator::Markup - Included

Text - Included

Constructor Details

.new ⇒ Context

Instance Attribute Details

#aliases (readonly)

#attributes (readonly)

#block_params (rw)

#constants (readonly)

#constants_hash (readonly)

#current_line_visibility=(value) (writeonly)

#current_section (rw)

#current_section=(value) (rw)

#extends (readonly)

#external_aliases (readonly)

#fully_documented? ⇒ Boolean (readonly)

#in_files (readonly)

#includes (readonly)

#method_list (readonly)

#methods_hash (readonly)

#name (readonly)

#ongoing_visibility=(visibility) (writeonly)

#params (rw)

#remove_from_documentation? ⇒ Boolean (readonly)

#requires (readonly)

#temporary_section (rw)

#unmatched_alias_lists (rw)

#visibility (rw)

Instance Method Details

#<=>(other)

#add(klass, name, comment)

#add_alias(an_alias)

#add_attribute(attribute)

#add_class(class_type, given_name, superclass = '::Object')

#add_class_or_module(mod, self_hash, all_hash)

#add_constant(constant)

#add_extend(ext)

#add_include(include)

#add_method(method)

#add_module(class_type, name)

#add_module_alias(from, from_name, to, file)

#add_module_by_normal_module(mod)

#add_require(require)

#add_section(title, comment = nil)

#add_to(array, thing)

#any_content(includes = true)

#child_name(name)

#class_attributes

#class_method_list

#classes

#classes_and_modules

#classes_hash

#defined_in?(file) ⇒ Boolean

#display(method_attr)

#each_ancestor

#each_attribute

#each_classmodule(&block)

#each_constant

#each_extend

#each_include

#each_method

#each_section

#find_attribute(name, singleton)

#find_attribute_named(name)

#find_class_method_named(name)

#find_constant_named(name)

#find_enclosing_module_named(name)

#find_external_alias(name, singleton)

#find_external_alias_named(name)

`Text` - Included

`CodeObject` - Inherited

`CodeObject` - Inherited

`Text` - Included

`CodeObject` - Inherited

`Generator::Markup` - Included

`Text` - Included

.new ⇒ `Context`

#fully_documented? ⇒ `Boolean` (readonly)

#remove_from_documentation? ⇒ `Boolean` (readonly)

#defined_in?(file) ⇒ `Boolean`