RDoc::TopLevel

A TopLevel context is a representation of the contents of a single file

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() click to toggle source

Returns all classes discovered by RDoc

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

Also aliased as: classes

all_classes_and_modules() click to toggle source

Returns all classes and modules discovered by RDoc

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

all_classes_hash() click to toggle source

Hash of all classes known to RDoc

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

Also aliased as: classes_hash

all_files() click to toggle source

All TopLevels known to RDoc

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

Also aliased as: files

all_files_hash() click to toggle source

Hash of all files known to RDoc

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

Also aliased as: files_hash

all_modules() click to toggle source

Returns all modules discovered by RDoc

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

Also aliased as: modules

all_modules_hash() click to toggle source

Hash of all modules known to RDoc

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

Also aliased as: modules_hash

classes() click to toggle source

Alias for: all_classes

classes_hash() click to toggle source

Alias for: all_classes_hash

complete(min_visibility) click to toggle source

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 rdoc/top_level.rb, line 102
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 RDoc::Parser::Simple === tl.parser 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() click to toggle source

Alias for: all_files

files_hash() click to toggle source

Alias for: all_files_hash

find_class_named(name) click to toggle source

Finds the class with name in all discovered classes

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

find_class_named_from(name, from) click to toggle source

Finds the class with name starting in namespace from

 
               # File rdoc/top_level.rb, line 147
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) click to toggle source

Finds the class or module with name

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

find_file_named(name) click to toggle source

Finds the file with name in all discovered files

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

find_module_named(name) click to toggle source

Finds the module with name in all discovered modules

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

find_unique(all_hash) click to toggle source

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

 
               # File rdoc/top_level.rb, line 191
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() click to toggle source

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 rdoc/top_level.rb, line 212
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() click to toggle source

Alias for: all_modules

modules_hash() click to toggle source

Alias for: all_modules_hash

new(file_name) click to toggle source

Creates a new TopLevel for file_name

 
               # File rdoc/top_level.rb, line 298
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

new(file_name) click to toggle source

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

 
               # File rdoc/top_level.rb, line 226
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

remove_nodoc(all_hash) click to toggle source

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

See RDoc::Context#remove_from_documentation?

 
               # File rdoc/top_level.rb, line 241
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() click to toggle source

Empties RDoc of stored class, module and file information

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

unique_classes() click to toggle source

Returns the unique classes discovered by RDoc.

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

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

unique_classes_and_modules() click to toggle source

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

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

unique_modules() click to toggle source

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

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

Public Instance Methods

==(other) click to toggle source

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

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

Also aliased as: eql?

add_alias(an_alias) click to toggle source

Adds an_alias to Object instead of self.

 
               # File rdoc/top_level.rb, line 324
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) click to toggle source

Adds constant to Object instead of self.

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

add_include(include) click to toggle source

Adds include to Object instead of self.

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

add_method(method) click to toggle source

Adds method to Object instead of self.

 
               # File rdoc/top_level.rb, line 351
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) click to toggle source

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

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

base_name() click to toggle source

Base name of this file

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

Also aliased as: name

cvs_url() click to toggle source

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

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

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

eql?(other) click to toggle source

Alias for: ==

find_class_or_module(name) click to toggle source

See ::find_class_or_module

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

find_local_symbol(symbol) click to toggle source

Finds a class or module named symbol

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

find_module_named(name) click to toggle source

Finds a module or class with name

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

full_name() click to toggle source

Returns the relative name of this file

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

hash() click to toggle source

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

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

http_url(prefix) click to toggle source

URL for this with a prefix

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

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

last_modified() click to toggle source

Time this file was last modified, if known

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

name() click to toggle source

Alias for: base_name

object_class() click to toggle source

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

Records self as a location in “Object”.

 
               # File rdoc/top_level.rb, line 443
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

path() click to toggle source

Path to this file

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

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Class/Module Index

RDoc::TopLevel

Attributes

Public Class Methods

Public Instance Methods