Object
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:
Creates a new CodeObject that will document itself and its children
# File rdoc/code_object.rb, line 105 def initialize @metadata = {} @comment = '' @parent = nil @file = nil @full_name = nil @document_children = true @document_self = true @done_documenting = false @force_documentation = false @received_nodoc = false @ignored = false end
Replaces our comment with comment
, unless it is empty.
# File rdoc/code_object.rb, line 123 def comment=(comment) @comment = case comment when NilClass then '' when RDoc::Markup::Document then comment else if comment and not comment.empty? then normalize_comment comment else # TODO is this sufficient? # HACK correct fix is to have #initialize create @comment # with the correct encoding if String === @comment and Object.const_defined? :Encoding and @comment.empty? then @comment.force_encoding comment.encoding end @comment end end end
Should this CodeObject be shown in documentation?
# File rdoc/code_object.rb, line 146 def display? @document_self and not @ignored end
Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc:
# File rdoc/code_object.rb, line 154 def document_children=(document_children) @document_children = document_children unless @done_documenting end
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 rdoc/code_object.rb, line 163 def document_self=(document_self) return if @done_documenting @document_self = document_self @received_nodoc = true if document_self.nil? end
Does this object have a comment with content or is received_nodoc true?
# File rdoc/code_object.rb, line 173 def documented? @received_nodoc or !@comment.empty? end
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 rdoc/code_object.rb, line 186 def done_documenting=(value) @done_documenting = value @document_self = !value @document_children = @document_self end
Yields each parent of this CodeObject. See also RDoc::ClassModule#each_ancestor
# File rdoc/code_object.rb, line 196 def each_parent code_object = self while code_object = code_object.parent do yield code_object end self end
File name where this CodeObject was found.
See also RDoc::Context#in_files
# File rdoc/code_object.rb, line 211 def file_name return unless @file @file.absolute_name end
Force the documentation of this object unless documentation has been turned off by :endoc:
# File rdoc/code_object.rb, line 223 def force_documentation=(value) @force_documentation = value unless @done_documenting end
Sets the full_name overriding any computed full name.
Set to nil
to clear RDoc’s cached value
# File rdoc/code_object.rb, line 232 def full_name= full_name @full_name = full_name end
Use this to ignore a CodeObject and all its children until found again (#record_location is called). An ignored item will not be shown 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 shown. If a class was ignored and never reopened it should not be shown. The ignore flag allows this to occur.
# File rdoc/code_object.rb, line 251 def ignore @ignored = true stop_doc end
Has this class been ignored?
# File rdoc/code_object.rb, line 260 def ignored? @ignored end
File name of our parent
# File rdoc/code_object.rb, line 267 def parent_file_name @parent ? @parent.base_name : '(unknown)' end
Name of our parent
# File rdoc/code_object.rb, line 274 def parent_name @parent ? @parent.full_name : '(unknown)' end
Records the RDoc::TopLevel (file) where this code object was defined
# File rdoc/code_object.rb, line 281 def record_location top_level @ignored = false @file = top_level 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.
Our comment