Class: RDoc::Context
- Inherits:
-
CodeObject
- Object
- CodeObject
- RDoc::Context
- Includes:
- Comparable
- 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.
Direct Known Subclasses
Defined Under Namespace
Classes: Section
Constant Summary collapse
- TYPES =
Types of methods
%w[class instance]
- TOMDOC_TITLES =
If a context has these titles it will be sorted in this order.
[nil, 'Public', 'Internal', 'Deprecated']
- TOMDOC_TITLES_SORT =
:nodoc:
TOMDOC_TITLES.sort_by { |title| title.to_s }
Constants included from Text
Text::MARKUP_FORMAT, Text::TO_HTML_CHARACTERS
Instance Attribute Summary collapse
-
#aliases ⇒ Object
readonly
Class/module aliases.
-
#attributes ⇒ Object
readonly
All attr* methods.
-
#block_params ⇒ Object
Block params to be used in the next MethodAttr parsed under this context.
-
#constants ⇒ Object
readonly
Constants defined.
-
#constants_hash ⇒ Object
readonly
Hash of registered constants.
-
#current_section ⇒ Object
The current documentation section that new items will be added to.
-
#extends ⇒ Object
readonly
Modules this context is extended with.
-
#external_aliases ⇒ Object
readonly
Aliases that could not be resolved.
-
#in_files ⇒ Object
readonly
Files this context is found in.
-
#includes ⇒ Object
readonly
Modules this context includes.
-
#method_list ⇒ Object
readonly
Methods defined in this context.
-
#methods_hash ⇒ Object
readonly
Hash of registered methods.
-
#name ⇒ Object
readonly
Name of this class excluding namespace.
-
#params ⇒ Object
Params to be used in the next MethodAttr parsed under this context.
-
#requires ⇒ Object
readonly
Files this context requires.
-
#temporary_section ⇒ Object
Use this section for the next method, attribute or constant added.
-
#unmatched_alias_lists ⇒ Object
Hash
old_name => [aliases]
, for aliases that haven’t (yet) been resolved to a method/attribute. -
#visibility ⇒ Object
Current visibility of this context.
Attributes inherited from CodeObject
#comment, #document_children, #document_self, #done_documenting, #file, #force_documentation, #line, #metadata, #offset, #parent, #received_nodoc, #section, #store, #viewer
Instance Method Summary collapse
-
#<=>(other) ⇒ Object
Contexts are sorted by full_name.
-
#add_alias(an_alias) ⇒ Object
Adds
an_alias
that is automatically resolved. -
#add_attribute(attribute) ⇒ Object
Adds
attribute
if not already there. -
#add_class(class_type, given_name, superclass = '::Object') ⇒ Object
Adds a class named
given_name
withsuperclass
. -
#add_class_or_module(mod, self_hash, all_hash) ⇒ Object
Adds the class or module
mod
to the modules or classes Hashself_hash
, and toall_hash
(eitherTopLevel::modules_hash
orTopLevel::classes_hash
), unless #done_documenting istrue
. -
#add_constant(constant) ⇒ Object
Adds
constant
if not already there. -
#add_extend(ext) ⇒ Object
Adds extension module
ext
which should be an RDoc::Extend. -
#add_include(include) ⇒ Object
Adds included module
include
which should be an RDoc::Include. -
#add_method(method) ⇒ Object
Adds
method
if not already there. -
#add_module(class_type, name) ⇒ Object
Adds a module named
name
. -
#add_module_alias(from, name, file) ⇒ Object
Adds an alias from
from
(a class or module) toname
which was defined infile
. -
#add_require(require) ⇒ Object
Adds
require
to this context’s top level. -
#add_section(title, comment = nil) ⇒ Object
Returns a section with
title
, creating it if it doesn’t already exist. -
#add_to(array, thing) ⇒ Object
Adds
thing
to the collectionarray
. -
#any_content(includes = true) ⇒ Object
Is there any content?.
-
#child_name(name) ⇒ Object
Creates the full name for a child with
name
. -
#class_attributes ⇒ Object
Class attributes.
-
#class_method_list ⇒ Object
Class methods.
-
#classes ⇒ Object
Array of classes in this context.
-
#classes_and_modules ⇒ Object
All classes and modules in this namespace.
-
#classes_hash ⇒ Object
Hash of classes keyed by class name.
-
#defined_in?(file) ⇒ Boolean
Is part of this thing was defined in
file
?. -
#display(method_attr) ⇒ Object
:nodoc:.
-
#each_ancestor ⇒ Object
Iterator for ancestors for duck-typing.
-
#each_attribute ⇒ Object
Iterator for attributes.
-
#each_classmodule(&block) ⇒ Object
Iterator for classes and modules.
-
#each_constant ⇒ Object
Iterator for constants.
-
#each_extend ⇒ Object
Iterator for extension modules.
-
#each_include ⇒ Object
Iterator for included modules.
-
#each_method ⇒ Object
Iterator for methods.
-
#each_section ⇒ Object
Iterator for each section’s contents sorted by title.
-
#find_attribute(name, singleton) ⇒ Object
Finds an attribute
name
with singleton valuesingleton
. -
#find_attribute_named(name) ⇒ Object
Finds an attribute with
name
in this context. -
#find_class_method_named(name) ⇒ Object
Finds a class method with
name
in this context. -
#find_constant_named(name) ⇒ Object
Finds a constant with
name
in this context. -
#find_enclosing_module_named(name) ⇒ Object
Find a module at a higher scope.
-
#find_external_alias(name, singleton) ⇒ Object
Finds an external alias
name
with singleton valuesingleton
. -
#find_external_alias_named(name) ⇒ Object
Finds an external alias with
name
in this context. -
#find_file_named(name) ⇒ Object
Finds a file with
name
in this context. -
#find_instance_method_named(name) ⇒ Object
Finds an instance method with
name
in this context. -
#find_local_symbol(symbol) ⇒ Object
Finds a method, constant, attribute, external alias, module or file named
symbol
in this context. -
#find_method(name, singleton) ⇒ Object
Finds a method named
name
with singleton valuesingleton
. -
#find_method_named(name) ⇒ Object
Finds a instance or module method with
name
in this context. -
#find_module_named(name) ⇒ Object
Find a module with
name
using ruby’s scoping rules. -
#find_symbol(symbol) ⇒ Object
Look up
symbol
, first as a module, then as a local symbol. -
#find_symbol_module(symbol) ⇒ Object
Look up a module named
symbol
. -
#full_name ⇒ Object
The full name for this context.
-
#fully_documented? ⇒ Boolean
Does this context and its methods and constants all have documentation?.
-
#http_url(prefix) ⇒ Object
URL for this with a
prefix
. -
#initialize ⇒ Context
constructor
Creates an unnamed empty context with public current visibility.
-
#initialize_methods_etc ⇒ Object
Sets the defaults for methods and so-forth.
-
#instance_attributes ⇒ Object
Instance attributes.
-
#instance_method_list ⇒ Object
Instance methods – TODO rename to instance_methods.
-
#methods_by_type(section = nil) ⇒ Object
Breaks method_list into a nested hash by type (
'class'
or'instance'
) and visibility (:public
,:protected
,:private
). -
#methods_matching(methods, singleton = false, &block) ⇒ Object
Yields AnyMethod and Attr entries matching the list of names in
methods
. -
#modules ⇒ Object
Array of modules in this context.
-
#modules_hash ⇒ Object
Hash of modules keyed by module name.
-
#name_for_path ⇒ Object
Name to use to generate the url.
-
#ongoing_visibility=(visibility) ⇒ Object
Changes the visibility for new methods to
visibility
. -
#record_location(top_level) ⇒ Object
Record
top_level
as a fileself
is in. -
#remove_from_documentation? ⇒ Boolean
Should we remove this context from the documentation?.
-
#remove_invisible(min_visibility) ⇒ Object
Removes methods and attributes with a visibility less than
min_visibility
. -
#remove_invisible_in(array, min_visibility) ⇒ Object
Only called when min_visibility == :public or :private.
-
#resolve_aliases(added) ⇒ Object
Tries to resolve unmatched aliases when a method or attribute has just been added.
-
#section_contents ⇒ Object
Returns RDoc::Context::Section objects referenced in this context for use in a table of contents.
-
#sections ⇒ Object
Sections in this context.
-
#sections_hash ⇒ Object
:nodoc:.
-
#set_current_section(title, comment) ⇒ Object
Sets the current section to a section with
title
. -
#set_visibility_for(methods, visibility, singleton = false) ⇒ Object
Given an array
methods
of method names, set the visibility of each tovisibility
. -
#sort_sections ⇒ Object
Sorts sections alphabetically (default) or in TomDoc fashion (none, Public, Internal, Deprecated).
-
#to_s ⇒ Object
:nodoc:.
-
#top_level ⇒ Object
Return the TopLevel that owns us – FIXME we can be ‘owned’ by several TopLevel (see #record_location & #in_files).
-
#upgrade_to_class(mod, class_type, enclosing) ⇒ Object
Upgrades NormalModule
mod
inenclosing
to aclass_type
.
Methods inherited from CodeObject
#display?, #documented?, #each_parent, #file_name, #full_name=, #ignore, #ignored?, #initialize_visibility, #parent_file_name, #parent_name, #start_doc, #stop_doc
Methods included from Generator::Markup
#aref_to, #as_href, #cvs_url, #description, #formatter
Methods included from Text
encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap
Constructor Details
#initialize ⇒ Context
Creates an unnamed empty context with public current visibility
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 |
# File 'lib/rdoc/context.rb', line 119 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 ⇒ Object (readonly)
Class/module aliases
26 27 28 |
# File 'lib/rdoc/context.rb', line 26 def aliases @aliases end |
#attributes ⇒ Object (readonly)
All attr* methods
31 32 33 |
# File 'lib/rdoc/context.rb', line 31 def attributes @attributes end |
#block_params ⇒ Object
Block params to be used in the next MethodAttr parsed under this context
36 37 38 |
# File 'lib/rdoc/context.rb', line 36 def block_params @block_params end |
#constants ⇒ Object (readonly)
Constants defined
41 42 43 |
# File 'lib/rdoc/context.rb', line 41 def constants @constants end |
#constants_hash ⇒ Object (readonly)
Hash of registered constants.
114 115 116 |
# File 'lib/rdoc/context.rb', line 114 def constants_hash @constants_hash end |
#current_section ⇒ Object
The current documentation section that new items will be added to. If temporary_section is available it will be used.
634 635 636 637 638 639 640 641 642 |
# File 'lib/rdoc/context.rb', line 634 def current_section if section = @temporary_section then @temporary_section = nil else section = @current_section end section end |
#extends ⇒ Object (readonly)
Modules this context is extended with
61 62 63 |
# File 'lib/rdoc/context.rb', line 61 def extends @extends end |
#external_aliases ⇒ Object (readonly)
Aliases that could not be resolved.
93 94 95 |
# File 'lib/rdoc/context.rb', line 93 def external_aliases @external_aliases end |
#in_files ⇒ Object (readonly)
Files this context is found in
51 52 53 |
# File 'lib/rdoc/context.rb', line 51 def in_files @in_files end |
#includes ⇒ Object (readonly)
Modules this context includes
56 57 58 |
# File 'lib/rdoc/context.rb', line 56 def includes @includes end |
#method_list ⇒ Object (readonly)
Methods defined in this context
66 67 68 |
# File 'lib/rdoc/context.rb', line 66 def method_list @method_list end |
#methods_hash ⇒ Object (readonly)
Hash of registered methods. Attributes are also registered here, twice if they are RW.
104 105 106 |
# File 'lib/rdoc/context.rb', line 104 def methods_hash @methods_hash end |
#name ⇒ Object (readonly)
Name of this class excluding namespace. See also full_name
71 72 73 |
# File 'lib/rdoc/context.rb', line 71 def name @name end |
#params ⇒ Object
Params to be used in the next MethodAttr parsed under this context
109 110 111 |
# File 'lib/rdoc/context.rb', line 109 def params @params end |
#requires ⇒ Object (readonly)
Files this context requires
76 77 78 |
# File 'lib/rdoc/context.rb', line 76 def requires @requires end |
#temporary_section ⇒ Object
Use this section for the next method, attribute or constant added.
81 82 83 |
# File 'lib/rdoc/context.rb', line 81 def temporary_section @temporary_section end |
#unmatched_alias_lists ⇒ Object
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.)
88 89 90 |
# File 'lib/rdoc/context.rb', line 88 def unmatched_alias_lists @unmatched_alias_lists end |
#visibility ⇒ Object
Current visibility of this context
98 99 100 |
# File 'lib/rdoc/context.rb', line 98 def visibility @visibility end |
Instance Method Details
#<=>(other) ⇒ Object
Contexts are sorted by full_name
166 167 168 |
# File 'lib/rdoc/context.rb', line 166 def <=>(other) full_name <=> other.full_name end |
#add_alias(an_alias) ⇒ Object
Adds an_alias
that is automatically resolved
173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 |
# File 'lib/rdoc/context.rb', line 173 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) ⇒ Object
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.
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 |
# File 'lib/rdoc/context.rb', line 200 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') ⇒ 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.
263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 |
# File 'lib/rdoc/context.rb', line 263 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 superclass = nil if full_name == 'BasicObject' superclass = nil if full_name == 'Object' and defined?(::BasicObject) superclass = '::BasicObject' if defined?(::BasicObject) and full_name == 'Object' # 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) ⇒ Object
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
.
378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 |
# File 'lib/rdoc/context.rb', line 378 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.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 end mod end |
#add_constant(constant) ⇒ Object
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.
398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 |
# File 'lib/rdoc/context.rb', line 398 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) ⇒ Object
Adds extension module ext
which should be an RDoc::Extend
432 433 434 435 436 |
# File 'lib/rdoc/context.rb', line 432 def add_extend ext add_to @extends, ext ext end |
#add_include(include) ⇒ Object
Adds included module include
which should be an RDoc::Include
423 424 425 426 427 |
# File 'lib/rdoc/context.rb', line 423 def add_include include add_to @includes, include include end |
#add_method(method) ⇒ Object
Adds method
if not already there. If it is (as method or attribute), updates the comment if it was empty.
442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 |
# File 'lib/rdoc/context.rb', line 442 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..warn \ "Duplicate method #{known.full_name} in #{method.file}#{previously}" end else @methods_hash[key] = method method.visibility = @visibility add_to @method_list, method resolve_aliases method end method end |
#add_module(class_type, name) ⇒ Object
Adds a module named name
. If RDoc already knows name
is a class then that class is returned instead. See also #add_class.
471 472 473 474 475 476 477 478 479 |
# File 'lib/rdoc/context.rb', line 471 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, name, file) ⇒ Object
Adds an alias from from
(a class or module) to name
which was defined in file
.
485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 |
# File 'lib/rdoc/context.rb', line 485 def add_module_alias from, name, file return from if @done_documenting to_name = child_name 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_name to = from.dup to.name = name to.full_name = nil if to.module? then @store.modules_hash[to_name] = to @modules[name] = to else @store.classes_hash[to_name] = to @classes[name] = 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 name, nil, to.comment const.record_location file const.is_alias_for = from add_constant const to end |
#add_require(require) ⇒ Object
Adds require
to this context’s top level
521 522 523 524 525 526 527 528 529 |
# File 'lib/rdoc/context.rb', line 521 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) ⇒ Object
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.
See also RDoc::Context::Section
539 540 541 542 543 544 545 546 547 548 |
# File 'lib/rdoc/context.rb', line 539 def add_section title, comment = nil if section = @sections[title] then section.add_comment comment if comment else section = Section.new self, title, comment @sections[title] = section end section end |
#add_to(array, thing) ⇒ Object
Adds thing
to the collection array
553 554 555 556 557 558 559 |
# File 'lib/rdoc/context.rb', line 553 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) ⇒ Object
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
.
569 570 571 572 573 574 575 576 577 578 579 580 |
# File 'lib/rdoc/context.rb', line 569 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) ⇒ Object
Creates the full name for a child with name
585 586 587 588 589 590 591 592 593 |
# File 'lib/rdoc/context.rb', line 585 def child_name name if name =~ /^:+/ $' #' elsif RDoc::TopLevel === self then name else "#{self.full_name}::#{name}" end end |
#class_attributes ⇒ Object
Class attributes
598 599 600 |
# File 'lib/rdoc/context.rb', line 598 def class_attributes @class_attributes ||= attributes.select { |a| a.singleton } end |
#class_method_list ⇒ Object
Class methods
605 606 607 |
# File 'lib/rdoc/context.rb', line 605 def class_method_list @class_method_list ||= method_list.select { |a| a.singleton } end |
#classes ⇒ Object
Array of classes in this context
612 613 614 |
# File 'lib/rdoc/context.rb', line 612 def classes @classes.values end |
#classes_and_modules ⇒ Object
All classes and modules in this namespace
619 620 621 |
# File 'lib/rdoc/context.rb', line 619 def classes_and_modules classes + modules end |
#classes_hash ⇒ Object
Hash of classes keyed by class name
626 627 628 |
# File 'lib/rdoc/context.rb', line 626 def classes_hash @classes end |
#defined_in?(file) ⇒ Boolean
Is part of this thing was defined in file
?
647 648 649 |
# File 'lib/rdoc/context.rb', line 647 def defined_in?(file) @in_files.include?(file) end |
#display(method_attr) ⇒ Object
:nodoc:
651 652 653 654 655 656 657 |
# File 'lib/rdoc/context.rb', line 651 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 ⇒ Object
Iterator for ancestors for duck-typing. Does nothing. See RDoc::ClassModule#each_ancestor.
This method exists to make it easy to work with Context subclasses that aren’t part of RDoc.
666 667 |
# File 'lib/rdoc/context.rb', line 666 def each_ancestor # :nodoc: end |
#each_attribute ⇒ Object
Iterator for attributes
672 673 674 |
# File 'lib/rdoc/context.rb', line 672 def each_attribute # :yields: attribute @attributes.each { |a| yield a } end |
#each_classmodule(&block) ⇒ Object
Iterator for classes and modules
679 680 681 |
# File 'lib/rdoc/context.rb', line 679 def each_classmodule(&block) # :yields: module classes_and_modules.sort.each(&block) end |
#each_constant ⇒ Object
Iterator for constants
686 687 688 |
# File 'lib/rdoc/context.rb', line 686 def each_constant # :yields: constant @constants.each {|c| yield c} end |
#each_extend ⇒ Object
Iterator for extension modules
700 701 702 |
# File 'lib/rdoc/context.rb', line 700 def each_extend # :yields: extend @extends.each do |e| yield e end end |
#each_include ⇒ Object
Iterator for included modules
693 694 695 |
# File 'lib/rdoc/context.rb', line 693 def each_include # :yields: include @includes.each do |i| yield i end end |
#each_method ⇒ Object
Iterator for methods
707 708 709 710 711 |
# File 'lib/rdoc/context.rb', line 707 def each_method # :yields: method return enum_for __method__ unless block_given? @method_list.sort.each { |m| yield m } end |
#each_section ⇒ Object
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
723 724 725 726 727 728 729 730 731 732 733 734 735 |
# File 'lib/rdoc/context.rb', line 723 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].sort, attributes[section].sort end end |
#find_attribute(name, singleton) ⇒ Object
Finds an attribute name
with singleton value singleton
.
740 741 742 743 |
# File 'lib/rdoc/context.rb', line 740 def find_attribute(name, singleton) name = $1 if name =~ /^(.*)=$/ @attributes.find { |a| a.name == name && a.singleton == singleton } end |
#find_attribute_named(name) ⇒ Object
Finds an attribute with name
in this context
748 749 750 751 752 753 754 755 756 757 |
# File 'lib/rdoc/context.rb', line 748 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) ⇒ Object
Finds a class method with name
in this context
762 763 764 |
# File 'lib/rdoc/context.rb', line 762 def find_class_method_named(name) @method_list.find { |meth| meth.singleton && meth.name == name } end |
#find_constant_named(name) ⇒ Object
Finds a constant with name
in this context
769 770 771 |
# File 'lib/rdoc/context.rb', line 769 def find_constant_named(name) @constants.find {|m| m.name == name} end |
#find_enclosing_module_named(name) ⇒ Object
Find a module at a higher scope
776 777 778 |
# File 'lib/rdoc/context.rb', line 776 def find_enclosing_module_named(name) parent && parent.find_module_named(name) end |
#find_external_alias(name, singleton) ⇒ Object
Finds an external alias name
with singleton value singleton
.
783 784 785 |
# File 'lib/rdoc/context.rb', line 783 def find_external_alias(name, singleton) @external_aliases.find { |m| m.name == name && m.singleton == singleton } end |
#find_external_alias_named(name) ⇒ Object
Finds an external alias with name
in this context
790 791 792 793 794 795 796 797 798 799 |
# File 'lib/rdoc/context.rb', line 790 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) ⇒ Object
Finds a file with name
in this context
804 805 806 |
# File 'lib/rdoc/context.rb', line 804 def find_file_named name @store.find_file_named name end |
#find_instance_method_named(name) ⇒ Object
Finds an instance method with name
in this context
811 812 813 |
# File 'lib/rdoc/context.rb', line 811 def find_instance_method_named(name) @method_list.find { |meth| !meth.singleton && meth.name == name } end |
#find_local_symbol(symbol) ⇒ Object
Finds a method, constant, attribute, external alias, module or file named symbol
in this context.
819 820 821 822 823 824 825 826 |
# File 'lib/rdoc/context.rb', line 819 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) ⇒ Object
Finds a method named name
with singleton value singleton
.
831 832 833 |
# File 'lib/rdoc/context.rb', line 831 def find_method(name, singleton) @method_list.find { |m| m.name == name && m.singleton == singleton } end |
#find_method_named(name) ⇒ Object
Finds a instance or module method with name
in this context
838 839 840 841 842 843 844 845 846 847 |
# File 'lib/rdoc/context.rb', line 838 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) ⇒ Object
Find a module with name
using ruby’s scoping rules
852 853 854 855 856 857 |
# File 'lib/rdoc/context.rb', line 852 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) ⇒ Object
Look up symbol
, first as a module, then as a local symbol.
862 863 864 |
# File 'lib/rdoc/context.rb', line 862 def find_symbol(symbol) find_symbol_module(symbol) || find_local_symbol(symbol) end |
#find_symbol_module(symbol) ⇒ Object
Look up a module named symbol
.
869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 |
# File 'lib/rdoc/context.rb', line 869 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 ⇒ Object
The full name for this context. This method is overridden by subclasses.
902 903 904 |
# File 'lib/rdoc/context.rb', line 902 def full_name '(unknown)' end |
#fully_documented? ⇒ Boolean
Does this context and its methods and constants all have documentation?
(Yes, fully documented doesn’t mean everything.)
911 912 913 914 915 916 |
# File 'lib/rdoc/context.rb', line 911 def fully_documented? documented? and attributes.all? { |a| a.documented? } and method_list.all? { |m| m.documented? } and constants.all? { |c| c.documented? } end |
#http_url(prefix) ⇒ Object
URL for this with a prefix
921 922 923 924 925 926 927 |
# File 'lib/rdoc/context.rb', line 921 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 ⇒ Object
Sets the defaults for methods and so-forth
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 |
# File 'lib/rdoc/context.rb', line 141 def initialize_methods_etc @method_list = [] @attributes = [] @aliases = [] @requires = [] @includes = [] @extends = [] @constants = [] @external_aliases = [] # 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 ⇒ Object
Instance attributes
932 933 934 |
# File 'lib/rdoc/context.rb', line 932 def instance_attributes @instance_attributes ||= attributes.reject { |a| a.singleton } end |
#instance_method_list ⇒ Object
Instance methods – TODO rename to instance_methods
941 942 943 |
# File 'lib/rdoc/context.rb', line 941 def instance_method_list @instance_method_list ||= method_list.reject { |a| a.singleton } end |
#methods_by_type(section = nil) ⇒ Object
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 RDoc::Context::Section will be returned.
952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 |
# File 'lib/rdoc/context.rb', line 952 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) ⇒ Object
Yields AnyMethod and Attr entries matching the list of names in methods
.
975 976 977 978 979 980 981 982 983 |
# File 'lib/rdoc/context.rb', line 975 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 ⇒ Object
Array of modules in this context
988 989 990 |
# File 'lib/rdoc/context.rb', line 988 def modules @modules.values end |
#modules_hash ⇒ Object
Hash of modules keyed by module name
995 996 997 |
# File 'lib/rdoc/context.rb', line 995 def modules_hash @modules end |
#name_for_path ⇒ Object
Name to use to generate the url. #full_name
by default.
1003 1004 1005 |
# File 'lib/rdoc/context.rb', line 1003 def name_for_path full_name end |
#ongoing_visibility=(visibility) ⇒ Object
Changes the visibility for new methods to visibility
1010 1011 1012 |
# File 'lib/rdoc/context.rb', line 1010 def ongoing_visibility=(visibility) @visibility = visibility end |
#record_location(top_level) ⇒ Object
Record top_level
as a file self
is in.
1017 1018 1019 |
# File 'lib/rdoc/context.rb', line 1017 def record_location(top_level) @in_files << top_level unless @in_files.include?(top_level) end |
#remove_from_documentation? ⇒ Boolean
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
1031 1032 1033 1034 1035 1036 1037 |
# File 'lib/rdoc/context.rb', line 1031 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 |
#remove_invisible(min_visibility) ⇒ Object
Removes methods and attributes with a visibility less than min_visibility
. – TODO mark the visibility of attributes in the template (if not public?)
1044 1045 1046 1047 1048 |
# File 'lib/rdoc/context.rb', line 1044 def remove_invisible(min_visibility) return if min_visibility == :private remove_invisible_in @method_list, min_visibility remove_invisible_in @attributes, min_visibility end |
#remove_invisible_in(array, min_visibility) ⇒ Object
Only called when min_visibility == :public or :private
1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 |
# File 'lib/rdoc/context.rb', line 1053 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) ⇒ Object
Tries to resolve unmatched aliases when a method or attribute has just been added.
1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 |
# File 'lib/rdoc/context.rb', line 1069 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 ⇒ Object
Returns RDoc::Context::Section objects referenced in this context for use in a table of contents.
1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 |
# File 'lib/rdoc/context.rb', line 1085 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 ⇒ Object
Sections in this context
1109 1110 1111 |
# File 'lib/rdoc/context.rb', line 1109 def sections @sections.values end |
#sections_hash ⇒ Object
:nodoc:
1113 1114 1115 |
# File 'lib/rdoc/context.rb', line 1113 def sections_hash # :nodoc: @sections end |
#set_current_section(title, comment) ⇒ Object
Sets the current section to a section with title
. See also #add_section
1120 1121 1122 |
# File 'lib/rdoc/context.rb', line 1120 def set_current_section title, comment @current_section = add_section title, comment end |
#set_visibility_for(methods, visibility, singleton = false) ⇒ Object
Given an array methods
of method names, set the visibility of each to visibility
1128 1129 1130 1131 1132 |
# File 'lib/rdoc/context.rb', line 1128 def set_visibility_for(methods, visibility, singleton = false) methods_matching methods, singleton do |m| m.visibility = visibility end end |
#sort_sections ⇒ Object
Sorts sections alphabetically (default) or in TomDoc fashion (none, Public, Internal, Deprecated)
1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 |
# File 'lib/rdoc/context.rb', line 1138 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 ⇒ Object
:nodoc:
1154 1155 1156 |
# File 'lib/rdoc/context.rb', line 1154 def to_s # :nodoc: "#{self.class.name} #{self.full_name}" end |
#top_level ⇒ Object
Return the TopLevel that owns us – FIXME we can be ‘owned’ by several TopLevel (see #record_location & #in_files)
1164 1165 1166 1167 1168 1169 |
# File 'lib/rdoc/context.rb', line 1164 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) ⇒ Object
Upgrades NormalModule mod
in enclosing
to a class_type
1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 |
# File 'lib/rdoc/context.rb', line 1174 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 |