Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more

In Files

  • rdoc/code_object.rb

Class/Module Index [+]



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:



Our comment


Do we document our children?


Do we document ourselves?


Are we done documenting (ie, did we come across a :enddoc:)?


Which file this code object was defined in


Force documentation of this CodeObject


Line in file where this CodeObject was defined


Hash of arbitrary metadata for this CodeObject


Offset in file where this CodeObject was defined


Our parent CodeObject


Did we ever receive a :nodoc: directive?


Which section are we in


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.

Public Class Methods

new() click to toggle source

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

Public Instance Methods

comment=(comment) click to toggle source

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
               if comment and not comment.empty? then
                 normalize_comment comment
                 # 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
display?() click to toggle source

Should this CodeObject be shown in documentation?

               # File rdoc/code_object.rb, line 146
def display?
  @document_self and not @ignored
document_children=(document_children) click to toggle source

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
document_self=(document_self) click to toggle source

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?
documented?() click to toggle source

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?
done_documenting=(value) click to toggle source

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
each_parent() click to toggle source

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

file_name() click to toggle source

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

force_documentation=(value) click to toggle source

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
full_name=(full_name) click to toggle source

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
ignore() click to toggle source

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

ignored?() click to toggle source

Has this class been ignored?

               # File rdoc/code_object.rb, line 260
def ignored?
parent_file_name() click to toggle source

File name of our parent

               # File rdoc/code_object.rb, line 267
def parent_file_name
  @parent ? @parent.base_name : '(unknown)'
parent_name() click to toggle source

Name of our parent

               # File rdoc/code_object.rb, line 274
def parent_name
  @parent ? @parent.full_name : '(unknown)'
record_location(top_level) click to toggle source

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
start_doc() click to toggle source

Enable capture of documentation unless documentation has been turned off by :endoc:

               # File rdoc/code_object.rb, line 290
def start_doc
  return if @done_documenting

  @document_self = true
  @document_children = true
  @ignored = false
stop_doc() click to toggle source

Disable capture of documentation

               # File rdoc/code_object.rb, line 301
def stop_doc
  @document_self = false
  @document_children = false

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 visit Documenting-ruby.org.

blog comments powered by Disqus