rdoc-3.12 Documentation

Attributes

absolute_name[RW]: Absolute name of this file
classes_or_modules[R]: All the classes or modules that were declared in this file. These are assigned to either #classes_hash or #modules_hash once we know what they really are.
file_stat[RW]: This TopLevel’s File::Stat struct
parser[RW]: The parser that processed this file
relative_name[RW]: Relative name of this file

Public Class Methods

all_classes()

Returns all classes discovered by RDoc

# File lib/rdoc/top_level.rb, line 38
def self.all_classes
  @all_classes_hash.values
end

Also aliased as: classes

all_classes_and_modules()

Returns all classes and modules discovered by RDoc

# File lib/rdoc/top_level.rb, line 45
def self.all_classes_and_modules
  @all_classes_hash.values + @all_modules_hash.values
end

all_classes_hash()

Hash of all classes known to RDoc

# File lib/rdoc/top_level.rb, line 52
def self.all_classes_hash
  @all_classes_hash
end

Also aliased as: classes_hash

all_files()

All TopLevels known to RDoc

# File lib/rdoc/top_level.rb, line 59
def self.all_files
  @all_files_hash.values
end

Also aliased as: files

all_files_hash()

Hash of all files known to RDoc

# File lib/rdoc/top_level.rb, line 66
def self.all_files_hash
  @all_files_hash
end

Also aliased as: files_hash

all_modules()

Returns all modules discovered by RDoc

# File lib/rdoc/top_level.rb, line 73
def self.all_modules
  all_modules_hash.values
end

Also aliased as: modules

all_modules_hash()

Hash of all modules known to RDoc

# File lib/rdoc/top_level.rb, line 80
def self.all_modules_hash
  @all_modules_hash
end

Also aliased as: modules_hash

classes()

Alias for: all_classes

classes_hash()

Alias for: all_classes_hash

complete(min_visibility)

Prepares the RDoc code object tree for use by a generator.

It finds unique classes/modules defined, and replaces classes/modules that are aliases for another one by a copy with RDoc::ClassModule#is_alias_for set.

It updates the RDoc::ClassModule#constant_aliases attribute of “real” classes or modules.

It also completely removes the classes and modules that should be removed from the documentation and the methods that have a visibility below min_visibility, which is the --visibility option.

# File lib/rdoc/top_level.rb, line 100
def self.complete min_visibility
  fix_basic_object_inheritance

  # cache included modules before they are removed from the documentation
  all_classes_and_modules.each { |cm| cm.ancestors }

  remove_nodoc @all_classes_hash
  remove_nodoc @all_modules_hash

  @unique_classes = find_unique @all_classes_hash
  @unique_modules = find_unique @all_modules_hash

  unique_classes_and_modules.each do |cm|
    cm.complete min_visibility
  end

  @all_files_hash.each_key do |file_name|
    tl = @all_files_hash[file_name]

    unless tl.text? then
      tl.modules_hash.clear
      tl.classes_hash.clear

      tl.classes_or_modules.each do |cm|
        name = cm.full_name
        if cm.type == 'class' then
          tl.classes_hash[name] = cm if @all_classes_hash[name]
        else
          tl.modules_hash[name] = cm if @all_modules_hash[name]
        end
      end
    end
  end
end

files()

Alias for: all_files

files_hash()

Alias for: all_files_hash

find_class_named(name)

Finds the class with name in all discovered classes

# File lib/rdoc/top_level.rb, line 138
def self.find_class_named(name)
  @all_classes_hash[name]
end

find_class_named_from(name, from)

Finds the class with name starting in namespace from

# File lib/rdoc/top_level.rb, line 145
def self.find_class_named_from name, from
  from = find_class_named from unless RDoc::Context === from

  until RDoc::TopLevel === from do
    return nil unless from

    klass = from.find_class_named name
    return klass if klass

    from = from.parent
  end

  find_class_named name
end

find_class_or_module(name)

Finds the class or module with name

# File lib/rdoc/top_level.rb, line 163
def self.find_class_or_module(name)
  name = $' if name =~ %r^::/
  RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
end

find_file_named(name)

Finds the file with name in all discovered files

# File lib/rdoc/top_level.rb, line 171
def self.find_file_named(name)
  @all_files_hash[name]
end

find_module_named(name)

Finds the module with name in all discovered modules

# File lib/rdoc/top_level.rb, line 178
def self.find_module_named(name)
  modules_hash[name]
end

find_unique(all_hash)

Finds unique classes/modules defined in all_hash, and returns them as an array. Performs the alias updates in all_hash: see ::complete.

# File lib/rdoc/top_level.rb, line 189
def self.find_unique(all_hash)
  unique = []

  all_hash.each_pair do |full_name, cm|
    unique << cm if full_name == cm.full_name
  end

  unique
end

fix_basic_object_inheritance()

Fixes the erroneous BasicObject < Object in 1.9.

Because we assumed all classes without a stated superclass inherit from Object, we have the above wrong inheritance.

We fix BasicObject right away if we are running in a Ruby version >= 1.9. If not, we may be documenting 1.9 source while running under 1.8: we search the files of BasicObject for “object.c”, and fix the inheritance if we find it.

# File lib/rdoc/top_level.rb, line 210
def self.fix_basic_object_inheritance
  basic = all_classes_hash['BasicObject']
  return unless basic
  if RUBY_VERSION >= '1.9'
    basic.superclass = nil
  elsif basic.in_files.any? { |f| File.basename(f.full_name) == 'object.c' }
    basic.superclass = nil
  end
end

modules()

Alias for: all_modules

modules_hash()

Alias for: all_modules_hash

new(file_name)

Creates a new RDoc::TopLevel with file_name only if one with the same name does not exist in all_files.

# File lib/rdoc/top_level.rb, line 224
def self.new file_name
  if top_level = @all_files_hash[file_name] then
    top_level
  else
    top_level = super
    @all_files_hash[file_name] = top_level
    top_level
  end
end

new(file_name)

Creates a new TopLevel for file_name

# File lib/rdoc/top_level.rb, line 305
def initialize(file_name)
  super()
  @name = nil
  @relative_name = file_name
  @absolute_name = file_name
  @file_stat     = File.stat(file_name) rescue nil # HACK for testing
  @diagram       = nil
  @parser        = nil

  @classes_or_modules = []

  RDoc::TopLevel.files_hash[file_name] = self
end

page(name)

Returns the RDoc::TopLevel that has the given name

# File lib/rdoc/top_level.rb, line 237
def self.page name
  @all_files_hash.each_value.find do |file|
    file.text? and file.page_name == name
  end
end

remove_nodoc(all_hash)

Removes from all_hash the contexts that are nodoc or have no content.

See RDoc::Context#remove_from_documentation?

# File lib/rdoc/top_level.rb, line 248
def self.remove_nodoc(all_hash)
  all_hash.keys.each do |name|
    context = all_hash[name]
    all_hash.delete(name) if context.remove_from_documentation?
  end
end

reset()

Empties RDoc of stored class, module and file information

# File lib/rdoc/top_level.rb, line 258
def self.reset
  @all_classes_hash = {}
  @all_modules_hash = {}
  @all_files_hash   = {}
end

unique_classes()

Returns the unique classes discovered by RDoc.

::complete must have been called prior to using this method.

# File lib/rdoc/top_level.rb, line 269
def self.unique_classes
  @unique_classes
end

unique_classes_and_modules()

Returns the unique classes and modules discovered by RDoc. ::complete must have been called prior to using this method.

# File lib/rdoc/top_level.rb, line 277
def self.unique_classes_and_modules
  @unique_classes + @unique_modules
end

unique_modules()

Returns the unique modules discovered by RDoc. ::complete must have been called prior to using this method.

# File lib/rdoc/top_level.rb, line 285
def self.unique_modules
  @unique_modules
end

Public Instance Methods

==(other)

An RDoc::TopLevel is equal to another with the same #absolute_name

# File lib/rdoc/top_level.rb, line 322
def == other
  self.class === other and @absolute_name == other.absolute_name
end

Also aliased as: eql?

add_alias(an_alias)

Adds an_alias to Object instead of self.

# File lib/rdoc/top_level.rb, line 331
def add_alias(an_alias)
  object_class.record_location self
  return an_alias unless @document_self
  object_class.add_alias an_alias
end

add_constant(constant)

Adds constant to Object instead of self.

# File lib/rdoc/top_level.rb, line 340
def add_constant constant
  object_class.record_location self
  return constant unless @document_self
  object_class.add_constant constant
end

add_include(include)

Adds include to Object instead of self.

# File lib/rdoc/top_level.rb, line 349
def add_include(include)
  object_class.record_location self
  return include unless @document_self
  object_class.add_include include
end

add_method(method)

Adds method to Object instead of self.

# File lib/rdoc/top_level.rb, line 358
def add_method(method)
  object_class.record_location self
  return method unless @document_self
  object_class.add_method method
end

add_to_classes_or_modules(mod)

Adds class or module mod. Used in the building phase by the ruby parser.

# File lib/rdoc/top_level.rb, line 368
def add_to_classes_or_modules mod
  @classes_or_modules << mod
end

base_name()

Base name of this file

# File lib/rdoc/top_level.rb, line 375
def base_name
  File.basename @absolute_name
end

Also aliased as: name

cvs_url()

Returns a URL for this source file on some web repository. Use the -W command line option to set.

# File lib/rdoc/generator/markup.rb, line 160
def cvs_url
  url = RDoc::RDoc.current.options.webcvs

  if %r%s/ =~ url then
    url % @absolute_name
  else
    url + @absolute_name
  end
end

display?()

Only a TopLevel that contains text file) will be displayed. See also RDoc::CodeObject#display?

# File lib/rdoc/top_level.rb, line 385
def display?
  text? and super
end

eql?(other)

Alias for: ==

find_class_or_module(name)

See ::find_class_or_module

# File lib/rdoc/top_level.rb, line 395
def find_class_or_module name
  RDoc::TopLevel.find_class_or_module name
end

find_local_symbol(symbol)

Finds a class or module named symbol

# File lib/rdoc/top_level.rb, line 402
def find_local_symbol(symbol)
  find_class_or_module(symbol) || super
end

find_module_named(name)

Finds a module or class with name

# File lib/rdoc/top_level.rb, line 409
def find_module_named(name)
  find_class_or_module(name)
end

full_name()

Returns the relative name of this file

# File lib/rdoc/top_level.rb, line 416
def full_name
  @relative_name
end

hash()

An RDoc::TopLevel has the same hash as another with the same #absolute_name

# File lib/rdoc/top_level.rb, line 424
def hash
  @absolute_name.hash
end

http_url(prefix)

URL for this with a prefix

# File lib/rdoc/top_level.rb, line 431
def http_url(prefix)
  path = [prefix, @relative_name.tr('.', '_')]

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

last_modified()

Time this file was last modified, if known

# File lib/rdoc/top_level.rb, line 449
def last_modified
  @file_stat ? file_stat.mtime : nil
end

name()

Alias for: base_name

object_class()

Returns the NormalClass “Object”, creating it if not found.

Records self as a location in “Object”.

# File lib/rdoc/top_level.rb, line 458
def object_class
  @object_class ||= begin
    oc = self.class.find_class_named('Object') || add_class(RDoc::NormalClass, 'Object')
    oc.record_location self
    oc
  end
end

page_name()

Base name of this file without the extension

# File lib/rdoc/top_level.rb, line 469
def page_name
  basename = File.basename @absolute_name
  basename =~ %r\.[^.]*$/

  $` || basename
end

path()

Path to this file

# File lib/rdoc/top_level.rb, line 479
def path
  http_url RDoc::RDoc.current.generator.file_dir
end

search_record()

Search record used by RDoc::Generator::JsonIndex

# File lib/rdoc/top_level.rb, line 497
def search_record
  return unless @parser < RDoc::Parser::Text

  [
    page_name,
    '',
    page_name,
    '',
    path,
    '',
    snippet(@comment),
  ]
end

text?()

Is this TopLevel from a text file instead of a source code file?

# File lib/rdoc/top_level.rb, line 514
def text?
  @parser and @parser.ancestors.include? RDoc::Parser::Text
end

/	Search
?	Show this help

Keyboard Shortcuts