123456789_123456789_123456789_123456789_123456789_

Class: RDoc::CodeObject

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
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

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

.newCodeObject

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?

See also #ignore

[ GitHub ]

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

def ignored?
  @ignored
end

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

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

See also #suppress

[ GitHub ]

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

def suppressed?
  @suppressed
end

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

See also Context#in_files

[ GitHub ]

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

def file_name
  return unless @file

  @file.absolute_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.

[ 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