Skip to Content Skip to Search

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:

Methods
C
D
E
F
I
N
O
P
R
S
Included Modules

Attributes

[R] comment

Our comment
[R] document_children

Do we document our children?
[R] document_self

Do we document ourselves?
[R] done_documenting

Are we done documenting (ie, did we come across a :enddoc:)?
[R] file

Which file this code object was defined in
[R] force_documentation

Force documentation of this CodeObject
[RW] line

Line in file where this CodeObject was defined
[R] metadata

Hash of arbitrary metadata for this CodeObject
[W] parent

Sets the parent CodeObject
[R] received_nodoc

Did we ever receive a :nodoc: directive?
[W] section

Set the section this CodeObject is in
[R] store

The RDoc::Store for this object.
[RW] viewer

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.

Class Public methods

new()

Creates a new CodeObject that will document itself and its children

Source: show | on GitHub 

# File ruby/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 Public methods

comment=(comment)

Replaces our comment with comment, unless it is empty.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 135
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?()

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

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 163
def display?
  @document_self and not @ignored and
    (documented? or not @suppressed)
end

document_children=(document_children)

Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc:

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 172
def document_children=(document_children)
  return unless @track_visibility

  @document_children = document_children unless @done_documenting
end

document_self=(document_self)

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:.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 183
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?()

Does this object have a comment with content or is received_nodoc true?

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 194
def documented?
  @received_nodoc or !@comment.empty?
end

done_documenting=(value)

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.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 207
def done_documenting=(value)
  return unless @track_visibility
  @done_documenting  = value
  @document_self     = !value
  @document_children = @document_self
end

each_parent()

Yields each parent of this CodeObject. See also RDoc::ClassModule#each_ancestor

Source: show | on GitHub 

# File ruby/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()

File name where this CodeObject was found.

See also RDoc::Context#in_files

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 233
def file_name
  return unless @file

  @file.absolute_name
end

force_documentation=(value)

Force the documentation of this object unless documentation has been turned off by :enddoc:

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 245
def force_documentation=(value)
  @force_documentation = value unless @done_documenting
end

full_name=(full_name)

Sets the full_name overriding any computed full name.

Set to nil to clear RDoc’s cached value

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 254
def full_name= full_name
  @full_name = full_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.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 274
def ignore
  return unless @track_visibility

  @ignored = true

  stop_doc
end

ignored?()

Has this class been ignored?

See also ignore

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 287
def ignored?
  @ignored
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

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 297
def options
  if @store and @store.rdoc then
    @store.rdoc.options
  else
    RDoc::Options.new
  end
end

parent()

Our parent CodeObject. The parent may be missing for classes loaded from legacy RI data stores.

Source: show | on GitHub 

# File ruby/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

parent_file_name()

File name of our parent

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 331
def parent_file_name
  @parent ? @parent.base_name : '(unknown)'
end

parent_name()

Name of our parent

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 338
def parent_name
  @parent ? @parent.full_name : '(unknown)'
end

record_location(top_level)

Records the RDoc::TopLevel (file) where this code object was defined

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 345
def record_location top_level
  @ignored    = false
  @suppressed = false
  @file       = top_level
end

section()

The section this CodeObject is in. Sections allow grouping of constants, attributes and methods inside a class or module.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 355
def section
  return @section if @section

  @section = parent.add_section @section_title if parent
end

start_doc()

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

Source: show | on GitHub 

# File ruby/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()

Disable capture of documentation

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 377
def stop_doc
  return unless @track_visibility

  @document_self = false
  @document_children = false
end

store=(store)

Sets the store that contains this CodeObject

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 387
def store= store
  @store = store

  return unless @track_visibility

  if :nodoc == options.visibility then
    initialize_visibility
    @track_visibility = false
  end
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.

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 404
def suppress
  return unless @track_visibility

  @suppressed = true

  stop_doc
end

suppressed?()

Has this class been suppressed?

See also suppress

Source: show | on GitHub 

# File ruby/lib/rdoc/code_object.rb, line 417
def suppressed?
  @suppressed
end