Class: RDoc::CodeObject
- Inherits:
-
Object
- Object
- RDoc::CodeObject
- Includes:
- Generator::Markup, Text
- Defined in:
- lib/rdoc/code_object.rb,
lib/rdoc/generator/markup.rb
Overview
Base class for the RDoc code tree.
We contain the common stuff for contexts (which are containers) and other elements (methods, attributes and so on)
Here’s the tree of the CodeObject subclasses:
-
RDoc::Context
-
RDoc::TopLevel
-
RDoc::ClassModule
-
RDoc::AnonClass (never used so far)
-
RDoc::NormalClass
-
RDoc::NormalModule
-
RDoc::SingleClass
-
-
-
RDoc::MethodAttr
-
RDoc::Attr
-
RDoc::AnyMethod
-
RDoc::GhostMethod
-
RDoc::MetaMethod
-
-
-
RDoc::Alias
-
RDoc::Constant
-
RDoc::Mixin
-
RDoc::Require
-
RDoc::Include
-
Constant Summary
Constants included from Text
Text::MARKUP_FORMAT, Text::SPACE_SEPARATED_LETTER_CLASS, Text::TO_HTML_CHARACTERS
Instance Attribute Summary collapse
-
#comment ⇒ Object
Our comment.
-
#document_children ⇒ Object
Do we document our children?.
-
#document_self ⇒ Object
Do we document ourselves?.
-
#done_documenting ⇒ Object
Are we done documenting (ie, did we come across a :enddoc:)?.
-
#file ⇒ Object
readonly
Which file this code object was defined in.
-
#force_documentation ⇒ Object
Force documentation of this CodeObject.
-
#line ⇒ Object
Line in #file where this CodeObject was defined.
-
#metadata ⇒ Object
readonly
Hash of arbitrary metadata for this CodeObject.
-
#parent ⇒ Object
Our parent CodeObject.
-
#received_nodoc ⇒ Object
readonly
Did we ever receive a
:nodoc:
directive?. -
#section ⇒ Object
The section this CodeObject is in.
-
#store ⇒ Object
The RDoc::Store for this object.
-
#viewer ⇒ Object
We are the model of the code, but we know that at some point we will be worked on by viewers.
Attributes included from Text
Instance Method Summary collapse
-
#display? ⇒ Boolean
Should this CodeObject be displayed in output?.
-
#documented? ⇒ Boolean
Does this object have a comment with content or is #received_nodoc true?.
-
#each_parent ⇒ Object
Yields each parent of this CodeObject.
-
#file_name ⇒ Object
File name where this CodeObject was found.
-
#full_name=(full_name) ⇒ Object
Sets the full_name overriding any computed full name.
-
#ignore ⇒ Object
Use this to ignore a CodeObject and all its children until found again (#record_location is called).
-
#ignored? ⇒ Boolean
Has this class been ignored?.
-
#initialize ⇒ CodeObject
constructor
Creates a new CodeObject that will document itself and its children.
-
#initialize_visibility ⇒ Object
Initializes state for visibility of this CodeObject and its children.
-
#options ⇒ Object
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 ⇒ Object
File name of our parent.
-
#parent_name ⇒ Object
Name of our parent.
-
#record_location(top_level) ⇒ Object
Records the RDoc::TopLevel (file) where this code object was defined.
-
#start_doc ⇒ Object
Enable capture of documentation unless documentation has been turned off by :enddoc:.
-
#stop_doc ⇒ Object
Disable capture of documentation.
-
#suppress ⇒ Object
Use this to suppress a CodeObject and all its children until the next file it is seen in or documentation is discovered.
-
#suppressed? ⇒ Boolean
Has this class been suppressed?.
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 ⇒ CodeObject
Creates a new CodeObject that will document itself and its children
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 |
# File 'lib/rdoc/code_object.rb', line 102 def initialize @metadata = {} @comment = '' @parent = nil @parent_name = nil # for loading @parent_class = nil # for loading @section = nil @section_title = nil # for loading @file = nil @full_name = nil @store = nil @track_visibility = true initialize_visibility end |
Instance Attribute Details
#comment ⇒ Object
Our comment
35 36 37 |
# File 'lib/rdoc/code_object.rb', line 35 def comment @comment end |
#document_children ⇒ Object
Do we document our children?
40 41 42 |
# File 'lib/rdoc/code_object.rb', line 40 def document_children @document_children end |
#document_self ⇒ Object
Do we document ourselves?
45 46 47 |
# File 'lib/rdoc/code_object.rb', line 45 def document_self @document_self end |
#done_documenting ⇒ Object
Are we done documenting (ie, did we come across a :enddoc:)?
50 51 52 |
# File 'lib/rdoc/code_object.rb', line 50 def done_documenting @done_documenting end |
#file ⇒ Object (readonly)
Which file this code object was defined in
55 56 57 |
# File 'lib/rdoc/code_object.rb', line 55 def file @file end |
#force_documentation ⇒ Object
Force documentation of this CodeObject
60 61 62 |
# File 'lib/rdoc/code_object.rb', line 60 def force_documentation @force_documentation end |
#line ⇒ Object
Line in #file where this CodeObject was defined
65 66 67 |
# File 'lib/rdoc/code_object.rb', line 65 def line @line end |
#metadata ⇒ Object (readonly)
Hash of arbitrary metadata for this CodeObject
70 71 72 |
# File 'lib/rdoc/code_object.rb', line 70 def @metadata end |
#parent ⇒ Object
Our parent CodeObject. The parent may be missing for classes loaded from legacy RI data stores.
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 |
# File 'lib/rdoc/code_object.rb', line 309 def parent return @parent if @parent return nil unless @parent_name if @parent_class == RDoc::TopLevel then @parent = @store.add_file @parent_name else @parent = @store.find_class_or_module @parent_name return @parent if @parent begin @parent = @store.load_class @parent_name rescue RDoc::Store::MissingFileError nil end end end |
#received_nodoc ⇒ Object (readonly)
Did we ever receive a :nodoc:
directive?
80 81 82 |
# File 'lib/rdoc/code_object.rb', line 80 def received_nodoc @received_nodoc end |
#section ⇒ Object
The section this CodeObject is in. Sections allow grouping of constants, attributes and methods inside a class or module.
355 356 357 358 359 |
# File 'lib/rdoc/code_object.rb', line 355 def section return @section if @section @section = parent.add_section @section_title if parent end |
#store ⇒ Object
The RDoc::Store for this object.
90 91 92 |
# File 'lib/rdoc/code_object.rb', line 90 def store @store end |
#viewer ⇒ Object
We are the model of the code, but we know that at some point we will be worked on by viewers. By implementing the Viewable protocol, viewers can associated themselves with these objects.
97 98 99 |
# File 'lib/rdoc/code_object.rb', line 97 def viewer @viewer end |
Instance Method Details
#display? ⇒ Boolean
Should this CodeObject be displayed in output?
A code object should be displayed if:
-
The item didn’t have a nodoc or wasn’t in a container that had nodoc
-
The item wasn’t ignored
-
The item has documentation and was not suppressed
163 164 165 166 |
# File 'lib/rdoc/code_object.rb', line 163 def display? @document_self and not @ignored and (documented? or not @suppressed) end |
#documented? ⇒ Boolean
Does this object have a comment with content or is #received_nodoc true?
194 195 196 |
# File 'lib/rdoc/code_object.rb', line 194 def documented? @received_nodoc or !@comment.empty? end |
#each_parent ⇒ Object
Yields each parent of this CodeObject. See also RDoc::ClassModule#each_ancestor
218 219 220 221 222 223 224 225 226 |
# File 'lib/rdoc/code_object.rb', line 218 def each_parent code_object = self while code_object = code_object.parent do yield code_object end self end |
#file_name ⇒ Object
File name where this CodeObject was found.
See also RDoc::Context#in_files
233 234 235 236 237 |
# File 'lib/rdoc/code_object.rb', line 233 def file_name return unless @file @file.absolute_name end |
#full_name=(full_name) ⇒ Object
Sets the full_name overriding any computed full name.
Set to nil
to clear RDoc’s cached value
254 255 256 |
# File 'lib/rdoc/code_object.rb', line 254 def full_name= full_name @full_name = full_name end |
#ignore ⇒ Object
Use this to ignore a CodeObject and all its children until found again (#record_location is called). An ignored item will not be displayed in documentation.
See github issue #55
The ignored status is temporary in order to allow implementation details to be hidden. At the end of processing a file RDoc allows all classes and modules to add new documentation to previously created classes.
If a class was ignored (via stopdoc) then reopened later with additional documentation it should be displayed. If a class was ignored and never reopened it should not be displayed. The ignore flag allows this to occur.
274 275 276 277 278 279 280 |
# File 'lib/rdoc/code_object.rb', line 274 def ignore return unless @track_visibility @ignored = true stop_doc end |
#ignored? ⇒ Boolean
Has this class been ignored?
See also #ignore
287 288 289 |
# File 'lib/rdoc/code_object.rb', line 287 def ignored? @ignored end |
#initialize_visibility ⇒ Object
Initializes state for visibility of this CodeObject and its children.
121 122 123 124 125 126 127 128 129 130 |
# File 'lib/rdoc/code_object.rb', line 121 def initialize_visibility # :nodoc: @document_children = true @document_self = true @done_documenting = false @force_documentation = false @received_nodoc = false @ignored = false @suppressed = false @track_visibility = true end |
#options ⇒ Object
The options instance from the store this CodeObject is attached to, or a default options instance if the CodeObject is not attached.
This is used by Text#snippet
297 298 299 300 301 302 303 |
# File 'lib/rdoc/code_object.rb', line 297 def if @store and @store.rdoc then @store.rdoc. else RDoc::Options.new end end |
#parent_file_name ⇒ Object
File name of our parent
331 332 333 |
# File 'lib/rdoc/code_object.rb', line 331 def parent_file_name @parent ? @parent.base_name : '(unknown)' end |
#parent_name ⇒ Object
Name of our parent
338 339 340 |
# File 'lib/rdoc/code_object.rb', line 338 def parent_name @parent ? @parent.full_name : '(unknown)' end |
#record_location(top_level) ⇒ Object
Records the RDoc::TopLevel (file) where this code object was defined
345 346 347 348 349 |
# File 'lib/rdoc/code_object.rb', line 345 def record_location top_level @ignored = false @suppressed = false @file = top_level end |
#start_doc ⇒ Object
Enable capture of documentation unless documentation has been turned off by :enddoc:
365 366 367 368 369 370 371 372 |
# File 'lib/rdoc/code_object.rb', line 365 def start_doc return if @done_documenting @document_self = true @document_children = true @ignored = false @suppressed = false end |
#stop_doc ⇒ Object
Disable capture of documentation
377 378 379 380 381 382 |
# File 'lib/rdoc/code_object.rb', line 377 def stop_doc return unless @track_visibility @document_self = false @document_children = false end |
#suppress ⇒ Object
Use this to suppress a CodeObject and all its children until the next file it is seen in or documentation is discovered. A suppressed item with documentation will be displayed while an ignored item with documentation may not be displayed.
404 405 406 407 408 409 410 |
# File 'lib/rdoc/code_object.rb', line 404 def suppress return unless @track_visibility @suppressed = true stop_doc end |
#suppressed? ⇒ Boolean
Has this class been suppressed?
See also #suppress
417 418 419 |
# File 'lib/rdoc/code_object.rb', line 417 def suppressed? @suppressed end |