Class: RDoc::CodeObject (Ruby 2.4.2)
Description: Class : RDoc::CodeObject - Ruby 2.4.2

Support for the Ruby 2.4 series has ended. See here for reference.

### Home Classes Methods

### In Files

- rdoc/code_object.rb
- rdoc/generator/markup.rb

### Parent

Object

### Methods

- ::new
- #comment=
- #display?
- #document_children=
- #document_self=
- #documented?
- #done_documenting=
- #each_parent
- #file_name
- #force_documentation=
- #full_name=
- #ignore
- #ignored?
- #options
- #parent
- #parent_file_name
- #parent_name
- #record_location
- #section
- #start_doc
- #stop_doc
- #store=
- #suppress
- #suppressed?

### Included Modules

- RDoc::Text
- RDoc::Generator::Markup

### Class/Module Index

Quicksearch

- RDoc
- RDoc::Alias
- RDoc::AnonClass
- RDoc::AnyMethod
- RDoc::Attr
- RDoc::ClassModule
- RDoc::CodeObject
- RDoc::Comment
- RDoc::Constant
- RDoc::Context
- RDoc::Context::Section
- RDoc::CrossReference
- RDoc::ERBIO
- RDoc::ERBPartial
- RDoc::Encoding
- RDoc::Error
- RDoc::Extend
- RDoc::Generator
- RDoc::Generator::Darkfish
- RDoc::Generator::JsonIndex
- RDoc::Generator::Markup
- RDoc::Generator::POT
- RDoc::Generator::POT::MessageExtractor
- RDoc::Generator::POT::PO
- RDoc::Generator::POT::POEntry
- RDoc::Generator::RI
- RDoc::GhostMethod
- RDoc::I18n
- RDoc::I18n::Locale
- RDoc::I18n::Text
- RDoc::Include
- RDoc::Markdown
- RDoc::Markdown::Literals
- RDoc::Markup
- RDoc::Markup::AttrChanger
- RDoc::Markup::AttrSpan
- RDoc::Markup::AttributeManager
- RDoc::Markup::Attributes
- RDoc::Markup::BlankLine
- RDoc::Markup::BlockQuote
- RDoc::Markup::Document
- RDoc::Markup::Formatter
- RDoc::Markup::FormatterTestCase
- RDoc::Markup::HardBreak
- RDoc::Markup::Include
- RDoc::Markup::IndentedParagraph
- RDoc::Markup::List
- RDoc::Markup::ListItem
- RDoc::Markup::Paragraph
- RDoc::Markup::Parser
- RDoc::Markup::Parser::Error
- RDoc::Markup::Parser::ParseError
- RDoc::Markup::PreProcess
- RDoc::Markup::Raw
- RDoc::Markup::Rule
- RDoc::Markup::Special
- RDoc::Markup::TextFormatterTestCase
- RDoc::Markup::ToAnsi
- RDoc::Markup::ToBs
- RDoc::Markup::ToHtml
- RDoc::Markup::ToHtmlCrossref
- RDoc::Markup::ToHtmlSnippet
- RDoc::Markup::ToJoinedParagraph
- RDoc::Markup::ToLabel
- RDoc::Markup::ToMarkdown
- RDoc::Markup::ToRdoc
- RDoc::Markup::ToTableOfContents
- RDoc::Markup::ToTest
- RDoc::Markup::ToTtOnly
- RDoc::Markup::Verbatim
- RDoc::MetaMethod
- RDoc::MethodAttr
- RDoc::Mixin
- RDoc::NormalClass
- RDoc::NormalModule
- RDoc::Options
- RDoc::Parser
- RDoc::Parser::C
- RDoc::Parser::ChangeLog
- RDoc::Parser::Markdown
- RDoc::Parser::RD
- RDoc::Parser::Ruby
- RDoc::Parser::RubyTools
- RDoc::Parser::Simple
- RDoc::Parser::Text
- RDoc::RD
- RDoc::RD::BlockParser
- RDoc::RD::Inline
- RDoc::RD::InlineParser
- RDoc::RDoc
- RDoc::RI
- RDoc::RI::Driver
- RDoc::RI::Driver::Error
- RDoc::RI::Driver::NotFoundError
- RDoc::RI::Error
- RDoc::RI::Paths
- RDoc::RI::Task
- RDoc::Require
- RDoc::RubyLex
- RDoc::RubyLex::Error
- RDoc::RubyToken
- RDoc::RubygemsHook
- RDoc::Servlet
- RDoc::SingleClass
- RDoc::Stats
- RDoc::Stats::Normal
- RDoc::Stats::Quiet
- RDoc::Stats::Verbose
- RDoc::Store
- RDoc::Store::Error
- RDoc::Store::MissingFileError
- RDoc::Task
- RDoc::TestCase
- RDoc::Text
- RDoc::TokenStream
- RDoc::TomDoc
- RDoc::TopLevel
- RDocTask

No matching classes.

# 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::Mixin`

  - `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[W]

Sets the parent `CodeObject`

received_nodoc[R]

Did we ever receive a `:nodoc:` directive?

section[W]

Set the section this `CodeObject` is in

store[R]

The `RDoc::Store` for this object.

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 rdoc/code_object.rb, line 109
    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

### Public Instance Methods

comment=(comment) click to toggle source

Replaces our comment with `comment`, unless it is empty.

                   # File rdoc/code_object.rb, line 142
    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.force_encoding comment.encoding
                     end
                     @comment
                   end
                 end
    end

display?() click to toggle source

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

                   # File rdoc/code_object.rb, line 170
    def display?
      @document_self and not @ignored and
        (documented? or not @suppressed)
    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 rdoc/code_object.rb, line 179
    def document_children=(document_children)
      return unless @track_visibility

      @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 rdoc/code_object.rb, line 190
    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?() click to toggle source

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

                   # File rdoc/code_object.rb, line 201
    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 rdoc/code_object.rb, line 214
    def done_documenting=(value)
      return unless @track_visibility
      @done_documenting  = value
      @document_self     = !value
      @document_children = @document_self
    end

each_parent() click to toggle source

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

                   # File rdoc/code_object.rb, line 225
    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 rdoc/code_object.rb, line 240
    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 :enddoc:

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

                   # File rdoc/code_object.rb, line 281
    def ignore
      return unless @track_visibility

      @ignored = true

      stop_doc
    end

ignored?() click to toggle source

Has this class been ignored?

See also `ignore`

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

options() click to toggle source

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

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

parent() click to toggle source

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

                   # File rdoc/code_object.rb, line 316
    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() click to toggle source

File name of our parent

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

parent_name() click to toggle source

Name of our parent

                   # File rdoc/code_object.rb, line 345
    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 rdoc/code_object.rb, line 352
    def record_location top_level
      @ignored    = false
      @suppressed = false
      @file       = top_level
    end

section() click to toggle source

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

                   # File rdoc/code_object.rb, line 362
    def section
      return @section if @section

      @section = parent.add_section @section_title if parent
    end

start_doc() click to toggle source

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

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

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

stop_doc() click to toggle source

Disable capture of documentation

                   # File rdoc/code_object.rb, line 384
    def stop_doc
      return unless @track_visibility

      @document_self = false
      @document_children = false
    end

store=(store) click to toggle source

Sets the `store` that contains this `CodeObject`

                   # File rdoc/code_object.rb, line 394
    def store= store
      @store = store

      return unless @track_visibility

      if :nodoc == options.visibility then
        initialize_visibility
        @track_visibility = false
      end
    end

suppress() click to toggle source

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.

                   # File rdoc/code_object.rb, line 411
    def suppress
      return unless @track_visibility

      @suppressed = true

      stop_doc
    end

suppressed?() click to toggle source

Has this class been suppressed?

See also `suppress`

                   # File rdoc/code_object.rb, line 424
    def suppressed?
      @suppressed
    end