Class: RDoc::CodeObject

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses: Alias, AnonClass, AnyMethod, Attr, ClassModule, Constant, Context, Extend, GhostMethod, Include, MetaMethod, MethodAttr, Mixin, NormalClass, NormalModule, Require, SingleClass, TopLevel
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `Generator::Markup`, `Text`
Inherits:	Object
Defined in:	lib/rdoc/code_object.rb, lib/rdoc/generator/markup.rb

Overview

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:

Context
- RDoc::TopLevel
- RDoc::ClassModule
  - RDoc::AnonClass (never used so far)
  - RDoc::NormalClass
  - RDoc::NormalModule
  - RDoc::SingleClass
MethodAttr
- RDoc::Attr
- RDoc::AnyMethod
  - RDoc::GhostMethod
  - RDoc::MetaMethod
Alias
Constant
Mixin
- RDoc::Require
- RDoc::Include

Constant Summary

`Text` - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Method Summary

.new ⇒ CodeObject constructor

Creates a new CodeObject that will document itself and its children.

Instance Attribute Summary

#comment rw

Our comment.
#comment=(comment) rw

Replaces our comment with #comment, unless it is empty.
#display? ⇒ Boolean readonly

Should this CodeObject be displayed in output?
#document_children rw

Do we document our children?
#document_children=(document_children) rw

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

Do we document ourselves?
#document_self=(document_self) rw

Enables or disables documentation of this CodeObject unless it has been turned off by :enddoc:.
#documented? ⇒ Boolean readonly

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

Are we done documenting (ie, did we come across a :enddoc:)?
#done_documenting=(value) rw

Turns documentation on/off, and turns on/off #document_self and #document_children.
#file readonly

Which file this code object was defined in.
#force_documentation rw

Force documentation of this CodeObject.
#force_documentation=(value) rw

Force the documentation of this object unless documentation has been turned off by :enddoc:
#full_name=(full_name) writeonly

Sets the full_name overriding any computed full name.
#ignored? ⇒ Boolean readonly

Has this class been ignored?
#line rw

Line in #file where this CodeObject was defined.
#metadata readonly

Hash of arbitrary metadata for this CodeObject.
#parent rw

Our parent CodeObject.
#parent=(value) rw

Sets the parent CodeObject.
#received_nodoc readonly

Did we ever receive a :nodoc: directive?
#section rw

The section this CodeObject is in.
#section=(value) rw

Set the section this CodeObject is in.
#store rw

The Store for this object.
#store=(store) rw

Sets the #store that contains this CodeObject.
#suppressed? ⇒ Boolean readonly

Has this class been suppressed?
#viewer rw

We are the model of the code, but we know that at some point we will be worked on by viewers.

Instance Method Summary

#each_parent

Yields each parent of this CodeObject.
#file_name

File name where this CodeObject was found.
#ignore

Use this to ignore a CodeObject and all its children until found again (#record_location is called).
#options

The options instance from the store this CodeObject is attached to, or a default options instance if the CodeObject is not attached.
#parent_file_name

File name of our parent.
#parent_name

Name of our parent.
#record_location(top_level)

Records the TopLevel (file) where this code object was defined.
#start_doc

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

Disable capture of documentation.
#suppress

Use this to suppress a CodeObject and all its children until the next file it is seen in or documentation is discovered.
#initialize_visibility Internal use only

Initializes state for visibility of this CodeObject and its children.

`Generator::Markup` - Included

#aref_to	Generates a relative URL from this object’s path to `target_path`
#as_href	Generates a relative URL from `from_path` to this object’s path.
#cvs_url	Build a webcvs URL starting for the given `url` with `full_path` appended as the destination path.
#description	Handy wrapper for marking up this object’s comment.
#formatter	Creates an `Markup::ToHtmlCrossref` formatter.

`Text` - Included

#expand_tabs	Expands tab characters in `text` to eight spaces.
#flush_left	Flush `text` left based on the shortest line.
#markup	Convert a string in markup format into HTML.
#normalize_comment	Strips hashes, expands tabs then flushes `text` to the left.
#parse	Normalizes `text` then builds a `Markup::Document` from it.
#snippet	The first `limit` characters of `text` as HTML.
#strip_hashes	Strips leading # characters from `text`
#strip_newlines	Strips leading and trailing n characters from `text`
#strip_stars	Strips /* */ style comments.
#to_html	Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in `text` to properly encoded characters.
#wrap	Wraps `txt` to `line_len`

Constructor Details

.new ⇒ `CodeObject`

Creates a new CodeObject that will document itself and its children

[ GitHub ]

# File '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 Attribute Details

#comment (rw)

Our comment

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 35


attr_reader :comment

#comment=(comment) (rw)

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

[ GitHub ]

# File '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? ⇒ `Boolean` (readonly)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 163


def display?
  @document_self and not @ignored and
    (documented? or not @suppressed)
end

#document_children (rw)

Do we document our children?

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 40


attr_reader :document_children

#document_children=(document_children) (rw)

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

[ GitHub ]

# File '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 (rw)

Do we document ourselves?

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 45


attr_reader :document_self

#document_self=(document_self) (rw)

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

[ GitHub ]

# File '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? ⇒ `Boolean` (readonly)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 194


def documented?
  @received_nodoc or !@comment.empty?
end

#done_documenting (rw)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 50


attr_reader :done_documenting

#done_documenting=(value) (rw)

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.

[ GitHub ]

# File '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

#file (readonly)

Which file this code object was defined in

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 55


attr_reader :file

#force_documentation (rw)

Force documentation of this CodeObject

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 60


attr_reader :force_documentation

#force_documentation=(value) (rw)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 245


def force_documentation=(value)
  @force_documentation = value unless @done_documenting
end

#full_name=(full_name) (writeonly)

Sets the full_name overriding any computed full name.

Set to nil to clear RDoc’s cached value

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 254


def full_name= full_name
  @full_name = full_name
end

#ignored? ⇒ `Boolean` (readonly)

Has this class been ignored?

#line (rw)

Line in #file where this CodeObject was defined

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 65


attr_accessor :line

#metadata (readonly)

Hash of arbitrary metadata for this CodeObject

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 70


attr_reader :metadata

#parent (rw)

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

[ GitHub ]

# File '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=(value) (rw)

Sets the parent CodeObject

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 75


attr_writer :parent

#received_nodoc (readonly)

Did we ever receive a :nodoc: directive?

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 80


attr_reader :received_nodoc

#section (rw)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 355


def section
  return @section if @section

  @section = parent.add_section @section_title if parent
end

#section=(value) (rw)

Set the section this CodeObject is in

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 85


attr_writer :section

#store (rw)

The Store for this object.

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 90


attr_reader :store

#store=(store) (rw)

Sets the #store that contains this CodeObject

[ GitHub ]

# File '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

#suppressed? ⇒ `Boolean` (readonly)

Has this class been suppressed?

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 97


attr_accessor :viewer

Instance Method Details

#each_parent

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

[ GitHub ]

# File '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.

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 274


def ignore
  return unless @track_visibility

  @ignored = true

  stop_doc
end

#initialize_visibility

This method is for internal use only.

Initializes state for visibility of this CodeObject and its children.

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 121


def initialize_visibility # :nodoc:
  @document_children   = true
  @document_self       = true
  @done_documenting    = false
  @force_documentation = false
  @received_nodoc      = false
  @ignored             = false
  @suppressed          = false
  @track_visibility    = true
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

[ GitHub ]

# File '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_file_name

File name of our parent

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 331


def parent_file_name
  @parent ? @parent.base_name : '(unknown)'
end

#parent_name

Name of our parent

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 338


def parent_name
  @parent ? @parent.full_name : '(unknown)'
end

#record_location(top_level)

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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 345


def record_location top_level
  @ignored    = false
  @suppressed = false
  @file       = top_level
end

#start_doc

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

[ GitHub ]

# File '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

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 377


def stop_doc
  return unless @track_visibility

  @document_self = false
  @document_children = false
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.

[ GitHub ]

# File 'lib/rdoc/code_object.rb', line 404


def suppress
  return unless @track_visibility

  @suppressed = true

  stop_doc
end

Class: RDoc::CodeObject

Overview

Constant Summary

Text - Included

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Generator::Markup - Included

Text - Included

Constructor Details

.new ⇒ CodeObject

Instance Attribute Details

#comment (rw)

#comment=(comment) (rw)

#display? ⇒ Boolean (readonly)

#document_children (rw)

#document_children=(document_children) (rw)

#document_self (rw)

#document_self=(document_self) (rw)

#documented? ⇒ Boolean (readonly)

#done_documenting (rw)

#done_documenting=(value) (rw)

#file (readonly)

#force_documentation (rw)

#force_documentation=(value) (rw)

#full_name=(full_name) (writeonly)

#ignored? ⇒ Boolean (readonly)

#line (rw)

#metadata (readonly)

#parent (rw)

#parent=(value) (rw)

#received_nodoc (readonly)

#section (rw)

#section=(value) (rw)

#store (rw)

#store=(store) (rw)

#suppressed? ⇒ Boolean (readonly)

#viewer (rw)

Instance Method Details

#each_parent

#file_name

#ignore

#initialize_visibility

#options

#parent_file_name

#parent_name

#record_location(top_level)

#start_doc

#stop_doc

#suppress

`Text` - Included

`Generator::Markup` - Included

`Text` - Included

.new ⇒ `CodeObject`

#display? ⇒ `Boolean` (readonly)

#documented? ⇒ `Boolean` (readonly)

#ignored? ⇒ `Boolean` (readonly)

#suppressed? ⇒ `Boolean` (readonly)