A TopLevel context is a representation of the contents of a single file
Returns all classes discovered by RDoc
# File rdoc/top_level.rb, line 40 def self.all_classes @all_classes_hash.values end
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
Hash of all classes known to RDoc
# File rdoc/top_level.rb, line 54 def self.all_classes_hash @all_classes_hash end
All TopLevels known to RDoc
# File rdoc/top_level.rb, line 61 def self.all_files @all_files_hash.values end
Hash of all files known to RDoc
# File rdoc/top_level.rb, line 68 def self.all_files_hash @all_files_hash end
Returns all modules discovered by RDoc
# File rdoc/top_level.rb, line 75 def self.all_modules all_modules_hash.values end
Hash of all modules known to RDoc
# File rdoc/top_level.rb, line 82 def self.all_modules_hash @all_modules_hash end
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.
See also RDoc::Context#remove_from_documentation?
# 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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 of this file
# File rdoc/top_level.rb, line 368 def base_name File.basename @absolute_name end
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
# File rdoc/top_level.rb, line 380 def find_class_or_module name RDoc::TopLevel.find_class_or_module name end
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
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
Returns the relative name of this file
# File rdoc/top_level.rb, line 401 def full_name @relative_name end
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
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
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
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
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.