rdoc-3.12 Documentation

Attributes

comment[R]: Our comment
document_children[R]: Do we document our children?
document_self[R]: Do we document ourselves?
done_documenting[R]: Are we done documenting (ie, did we come across a :enddoc:)?
file[R]: Which file this code object was defined in
force_documentation[R]: Force documentation of this CodeObject
line[RW]: Line in file where this CodeObject was defined
metadata[R]: Hash of arbitrary metadata for this CodeObject
offset[RW]: Offset in file where this CodeObject was defined
parent[RW]: Our parent CodeObject
received_nodoc[R]: Did we ever receive a :nodoc: directive?
section[RW]: Which section are we in
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.

Public Class Methods

new()

Creates a new CodeObject that will document itself and its children

# File lib/rdoc/code_object.rb, line 102
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

Public Instance Methods

comment=(comment)

Replaces our comment with comment, unless it is empty.

# File lib/rdoc/code_object.rb, line 120
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
                 # 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

display?()

Should this CodeObject be shown in documentation?

# File lib/rdoc/code_object.rb, line 144
def display?
  @document_self and not @ignored
end

document_children=(document_children)

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

# File lib/rdoc/code_object.rb, line 152
def document_children=(document_children)
  @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:.

# File lib/rdoc/code_object.rb, line 161
def document_self=(document_self)
  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?

# File lib/rdoc/code_object.rb, line 171
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.

# File lib/rdoc/code_object.rb, line 184
def done_documenting=(value)
  @done_documenting = value
  @document_self = !value
  @document_children = @document_self
end

each_parent() { |code_object| ... }

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

# File lib/rdoc/code_object.rb, line 194
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

# File lib/rdoc/code_object.rb, line 209
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 :endoc:

# File lib/rdoc/code_object.rb, line 221
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

# File lib/rdoc/code_object.rb, line 230
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 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 lib/rdoc/code_object.rb, line 249
def ignore
  @ignored = true

  stop_doc
end

ignored?()

Has this class been ignored?

# File lib/rdoc/code_object.rb, line 258
def ignored?
  @ignored
end

parent_file_name()

File name of our parent

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

parent_name()

Name of our parent

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

record_location(top_level)

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

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

start_doc()

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

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

  @document_self = true
  @document_children = true
  @ignored = false
end

stop_doc()

Disable capture of documentation

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

/	Search
?	Show this help

Keyboard Shortcuts