Class: RDoc::CodeObject
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
Generator::Markup ,
Text
|
|
Inherits: | Object |
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::TopLevel
-
RDoc::ClassModule
-
RDoc::AnonClass (never used so far)
-
RDoc::NormalClass
-
RDoc::NormalModule
-
RDoc::SingleClass
-
-
-
-
RDoc::Attr
-
RDoc::AnyMethod
-
RDoc::GhostMethod
-
RDoc::MetaMethod
-
-
-
-
RDoc::Require
-
RDoc::Include
-
Constant Summary
Text
- Included
MARKUP_FORMAT, SPACE_SEPARATED_LETTER_CLASS, TO_HTML_CHARACTERS
Class Method Summary
-
.new ⇒ CodeObject
constructor
Creates a new
CodeObject
that will document itself and its children.
Instance Attribute Summary
-
#comment
rw
Our comment.
-
#comment=(comment)
rw
Replaces our comment with #comment, unless it is empty.
-
#display? ⇒ Boolean
readonly
Should this
CodeObject
be displayed in output? -
#document_children
rw
Do we document our children?
-
#document_children=(document_children)
rw
Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc:
-
#document_self
rw
Do we document ourselves?
-
#document_self=(document_self)
rw
Enables or disables documentation of this
CodeObject
unless it has been turned off by :enddoc:. -
#documented? ⇒ Boolean
readonly
Does this object have a comment with content or is #received_nodoc true?
-
#done_documenting
rw
Are we done documenting (ie, did we come across a :enddoc:)?
-
#done_documenting=(value)
rw
Turns documentation on/off, and turns on/off #document_self and #document_children.
-
#file
readonly
Which file this code object was defined in.
-
#force_documentation
rw
Force documentation of this
CodeObject
. -
#force_documentation=(value)
rw
Force the documentation of this object unless documentation has been turned off by :enddoc:
-
#full_name=(full_name)
writeonly
Sets the full_name overriding any computed full name.
-
#ignored? ⇒ Boolean
readonly
Has this class been ignored?
-
#line
rw
Line in #file where this
CodeObject
was defined. -
#metadata
readonly
Hash of arbitrary metadata for this
CodeObject
. -
#mixin_from
rw
When mixed-in to a class, this points to the
Context
in which it was originally defined. -
#parent
rw
Our parent
CodeObject
. -
#parent=(value)
rw
Sets the parent
CodeObject
. -
#received_nodoc
readonly
Did we ever receive a
:nodoc:
directive? -
#section
rw
The section this
CodeObject
is in. -
#section=(value)
rw
Set the section this
CodeObject
is in. -
#store
rw
The
Store
for this object. -
#store=(store)
rw
Sets the #store that contains this
CodeObject
. -
#suppressed? ⇒ Boolean
readonly
Has this class been suppressed?
-
#viewer
rw
We are the model of the code, but we know that at some point we will be worked on by viewers.
Text
- Included
#language | The language for this text. |
Instance Method Summary
-
#each_parent
Yields each parent of this
CodeObject
. -
#file_name
File name where this
CodeObject
was found. -
#ignore
Use this to ignore a
CodeObject
and all its children until found again (#record_location is called). -
#options
The options instance from the store this
CodeObject
is attached to, or a default options instance if theCodeObject
is not attached. -
#parent_file_name
File name of our parent.
-
#parent_name
Name of our parent.
-
#record_location(top_level)
Records the
TopLevel
(file) where this code object was defined. -
#start_doc
Enable capture of documentation unless documentation has been turned off by :enddoc:
-
#stop_doc
Disable capture of documentation.
-
#suppress
Use this to suppress a
CodeObject
and all its children until the next file it is seen in or documentation is discovered. -
#initialize_visibility
Internal use only
Initializes state for visibility of this
CodeObject
and its children.
Generator::Markup
- Included
#aref_to | Generates a relative URL from this object’s path to |
#as_href | Generates a relative URL from |
#cvs_url | Build a webcvs URL starting for the given |
#description | Handy wrapper for marking up this object’s comment. |
#formatter | Creates an |
Text
- Included
#expand_tabs | Expands tab characters in |
#flush_left | Flush |
#markup | Convert a string in markup format into HTML. |
#normalize_comment | Strips hashes, expands tabs then flushes |
#parse | Normalizes |
#snippet | The first |
#strip_hashes | Strips leading # characters from |
#strip_newlines | Strips leading and trailing n characters from |
#strip_stars | Strips /* */ style comments. |
#to_html | Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in |
#wrap | Wraps |
Constructor Details
.new ⇒ CodeObject
Creates a new CodeObject
that will document itself and its children
# File 'lib/rdoc/code_object.rb', line 107
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 @mixin_from = nil initialize_visibility end
Instance Attribute Details
#comment (rw)
Our comment
# File 'lib/rdoc/code_object.rb', line 35
attr_reader :comment
#comment=(comment) (rw)
Replaces our comment with #comment, unless it is empty.
# File 'lib/rdoc/code_object.rb', line 141
def comment=(comment) @comment = case comment when NilClass then '' when RDoc::Markup::Document then comment when RDoc::Comment then comment.normalize else if comment and not comment.empty? then normalize_comment comment else # HACK correct fix is to have #initialize create @comment # with the correct encoding if String === @comment and @comment.empty? then @comment = RDoc::Encoding.change_encoding @comment, comment.encoding end @comment end end end
#display? ⇒ Boolean
(readonly)
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
# File 'lib/rdoc/code_object.rb', line 169
def display? @document_self and not @ignored and (documented? or not @suppressed) end
#document_children (rw)
Do we document our children?
# File 'lib/rdoc/code_object.rb', line 40
attr_reader :document_children
#document_children=(document_children) (rw)
Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc:
# File 'lib/rdoc/code_object.rb', line 178
def document_children=(document_children) return unless @track_visibility @document_children = document_children unless @done_documenting end
#document_self (rw)
Do we document ourselves?
# File 'lib/rdoc/code_object.rb', line 45
attr_reader :document_self
#document_self=(document_self) (rw)
Enables or disables documentation of this CodeObject
unless it has been turned off by :enddoc:. If the argument is nil
it means the documentation is turned off by :nodoc:
.
# File 'lib/rdoc/code_object.rb', line 189
def document_self=(document_self) return unless @track_visibility return if @done_documenting @document_self = document_self @received_nodoc = true if document_self.nil? end
#documented? ⇒ Boolean
(readonly)
Does this object have a comment with content or is #received_nodoc true?
# File 'lib/rdoc/code_object.rb', line 200
def documented? @received_nodoc or !@comment.empty? end
#done_documenting (rw)
Are we done documenting (ie, did we come across a :enddoc:)?
# File 'lib/rdoc/code_object.rb', line 50
attr_reader :done_documenting
#done_documenting=(value) (rw)
Turns documentation on/off, and turns on/off #document_self and #document_children.
Once documentation has been turned off (by :enddoc:
), the object will refuse to turn #document_self or #document_children on, so :doc:
and :start_doc:
directives will have no effect in the current file.
# File 'lib/rdoc/code_object.rb', line 213
def done_documenting=(value) return unless @track_visibility @done_documenting = value @document_self = !value @document_children = @document_self end
#file (readonly)
Which file this code object was defined in
# File 'lib/rdoc/code_object.rb', line 55
attr_reader :file
#force_documentation (rw)
Force documentation of this CodeObject
# File 'lib/rdoc/code_object.rb', line 60
attr_reader :force_documentation
#force_documentation=(value) (rw)
Force the documentation of this object unless documentation has been turned off by :enddoc:
# File 'lib/rdoc/code_object.rb', line 251
def force_documentation=(value) @force_documentation = value unless @done_documenting end
#full_name=(full_name) (writeonly)
Sets the full_name overriding any computed full name.
Set to nil
to clear RDoc’s cached value
# File 'lib/rdoc/code_object.rb', line 260
def full_name= full_name @full_name = full_name end
#ignored? ⇒ Boolean
(readonly)
Has this class been ignored?
See also #ignore
# File 'lib/rdoc/code_object.rb', line 293
def ignored? @ignored end
#line (rw)
Line in #file where this CodeObject
was defined
# File 'lib/rdoc/code_object.rb', line 65
attr_accessor :line
#metadata (readonly)
Hash of arbitrary metadata for this CodeObject
# File 'lib/rdoc/code_object.rb', line 70
attr_reader :
#mixin_from (rw)
When mixed-in to a class, this points to the Context
in which it was originally defined.
# File 'lib/rdoc/code_object.rb', line 102
attr_accessor :mixin_from
#parent (rw)
Our parent CodeObject
. The parent may be missing for classes loaded from legacy RI
data stores.
# File 'lib/rdoc/code_object.rb', line 315
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
#parent=(value) (rw)
Sets the parent CodeObject
# File 'lib/rdoc/code_object.rb', line 75
attr_writer :parent
#received_nodoc (readonly)
Did we ever receive a :nodoc:
directive?
# File 'lib/rdoc/code_object.rb', line 80
attr_reader :received_nodoc
#section (rw)
The section this CodeObject
is in. Sections allow grouping of constants, attributes and methods inside a class or module.
#section=(value) (rw)
Set the section this CodeObject
is in
# File 'lib/rdoc/code_object.rb', line 85
attr_writer :section
#store (rw)
The Store
for this object.
# File 'lib/rdoc/code_object.rb', line 90
attr_reader :store
#store=(store) (rw)
Sets the #store that contains this CodeObject
# File 'lib/rdoc/code_object.rb', line 393
def store= store @store = store return unless @track_visibility if :nodoc == .visibility then initialize_visibility @track_visibility = false end end
#suppressed? ⇒ Boolean
(readonly)
Has this class been suppressed?
See also #suppress
# File 'lib/rdoc/code_object.rb', line 423
def suppressed? @suppressed end
#viewer (rw)
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.
# File 'lib/rdoc/code_object.rb', line 97
attr_accessor :viewer
Instance Method Details
#each_parent
Yields each parent of this CodeObject
. See also ClassModule#each_ancestor
# File 'lib/rdoc/code_object.rb', line 224
def each_parent code_object = self while code_object = code_object.parent do yield code_object end self end
#file_name
File name where this CodeObject
was found.
See also Context#in_files
# File 'lib/rdoc/code_object.rb', line 239
def file_name return unless @file @file.absolute_name end
#ignore
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.
# File 'lib/rdoc/code_object.rb', line 280
def ignore return unless @track_visibility @ignored = true stop_doc end
#initialize_visibility
Initializes state for visibility of this CodeObject
and its children.
# File 'lib/rdoc/code_object.rb', line 127
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
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
#parent_file_name
File name of our parent
# File 'lib/rdoc/code_object.rb', line 337
def parent_file_name @parent ? @parent.base_name : '(unknown)' end
#parent_name
Name of our parent
# File 'lib/rdoc/code_object.rb', line 344
def parent_name @parent ? @parent.full_name : '(unknown)' end
#record_location(top_level)
Records the TopLevel
(file) where this code object was defined
# File 'lib/rdoc/code_object.rb', line 351
def record_location top_level @ignored = false @suppressed = false @file = top_level end
#start_doc
Enable capture of documentation unless documentation has been turned off by :enddoc:
# File 'lib/rdoc/code_object.rb', line 371
def start_doc return if @done_documenting @document_self = true @document_children = true @ignored = false @suppressed = false end
#stop_doc
Disable capture of documentation
# File 'lib/rdoc/code_object.rb', line 383
def stop_doc return unless @track_visibility @document_self = false @document_children = false end
#suppress
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.
# File 'lib/rdoc/code_object.rb', line 410
def suppress return unless @track_visibility @suppressed = true stop_doc end