# class RDoc::CodeObject

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

  - RDoc::TopLevel

  - RDoc::ClassModule

    - RDoc::AnonClass (never used so far)

    - RDoc::NormalClass

    - RDoc::NormalModule

    - RDoc::SingleClass

- RDoc::MethodAttr

  - RDoc::Attr

  - RDoc::AnyMethod

    - RDoc::GhostMethod

    - RDoc::MetaMethod

- RDoc::Alias

- RDoc::Constant

- RDoc::Require

- RDoc::Include

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

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

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

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

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

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) 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 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| ... } click to toggle source

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

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

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

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

      stop_doc
    end

ignored?() click to toggle source

Has this class been ignored?

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

parent_file_name() click to toggle source

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

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

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

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

Disable capture of documentation

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