Class: RDoc::CodeObject

Inherits:
Object
  • Object
show all
Includes:
Generator::Markup, Text
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:

  • RDoc::Context

    • RDoc::TopLevel

    • RDoc::ClassModule

      • RDoc::NormalClass

      • RDoc::NormalModule

      • RDoc::SingleClass

  • RDoc::MethodAttr

    • RDoc::Attr

    • RDoc::AnyMethod

  • RDoc::Alias

  • RDoc::Constant

  • RDoc::Require

  • RDoc::Mixin

    • RDoc::Include

    • RDoc::Extend

Direct Known Subclasses

Alias, Constant, Context, MethodAttr, Mixin, Require

Constant Summary

Constants included from Text

Text::MARKUP_FORMAT, Text::SPACE_SEPARATED_LETTER_CLASS

Instance Attribute Summary collapse

Attributes included from Text

#language

Instance Method Summary collapse

Methods included from Generator::Markup

#aref_to, #as_href, #canonical_url, #cvs_url, #description, #formatter

Methods included from Text

decode_legacy_label, expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, to_anchor, #wrap

Constructor Details

#initialize ⇒ CodeObject

Creates a new CodeObject that will document itself and its children



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/rdoc/code_object.rb', line 98

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
  @mixin_from       = nil

  initialize_visibility
end

Instance Attribute Details

#comment ⇒ Object

Our comment



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

def comment
  @comment
end

#document_children ⇒ Object

Do we document our children?



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

def document_children
  @document_children
end

#document_self ⇒ Object

Do we document ourselves?



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

def document_self
  @document_self
end

#done_documenting ⇒ Object

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



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

def done_documenting
  @done_documenting
end

#file ⇒ Object (readonly)

Which file this code object was defined in



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

def file
  @file
end

#force_documentation ⇒ Object

Force documentation of this CodeObject



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

def force_documentation
  @force_documentation
end

#line ⇒ Object

Line in #file where this CodeObject was defined



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

def line
  @line
end

#metadata ⇒ Object (readonly)

Hash of arbitrary metadata for this CodeObject



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

def metadata
  @metadata
end

#mixin_from ⇒ Object

When mixed-in to a class, this points to the Context in which it was originally defined.



93
94
95
 
# File 'lib/rdoc/code_object.rb', line 93

def mixin_from
  @mixin_from
end

#parent ⇒ Object

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



288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'lib/rdoc/code_object.rb', line 288

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

#received_nodoc ⇒ Object (readonly)

Did we ever receive a :nodoc: directive?



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

def received_nodoc
  @received_nodoc
end

#section ⇒ Object

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



327
328
329
330
331
 
# File 'lib/rdoc/code_object.rb', line 327

def section
  return @section if @section

  @section = parent.add_section @section_title if parent
end

#store ⇒ Object

The RDoc::Store for this object.



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

def store
  @store
end

Instance Method Details

#display? ⇒ Boolean

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

Returns:

  • (Boolean) 


159
160
161
162
 
# File 'lib/rdoc/code_object.rb', line 159

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

#documented? ⇒ Boolean

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

Returns:

  • (Boolean) 


190
191
192
 
# File 'lib/rdoc/code_object.rb', line 190

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

#file_name ⇒ Object

File name where this CodeObject was found.

See also RDoc::Context#in_files



215
216
217
218
219
 
# File 'lib/rdoc/code_object.rb', line 215

def file_name
  return unless @file

  @file.absolute_name
end

#full_name=(full_name) ⇒ Object

Sets the full_name overriding any computed full name.

Set to nil to clear RDoc’s cached value



236
237
238
 
# File 'lib/rdoc/code_object.rb', line 236

def full_name=(full_name)
  @full_name = full_name
end

#ignore ⇒ Object

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.



256
257
258
259
260
261
262
 
# File 'lib/rdoc/code_object.rb', line 256

def ignore
  return unless @track_visibility

  @ignored = true

  stop_doc
end

#ignored? ⇒ Boolean

Has this class been ignored?

See also #ignore

Returns:

  • (Boolean) 


269
270
271
 
# File 'lib/rdoc/code_object.rb', line 269

def ignored?
  @ignored
end

#initialize_visibility ⇒ Object

Initializes state for visibility of this CodeObject and its children.



118
119
120
121
122
123
124
125
126
127
 
# File 'lib/rdoc/code_object.rb', line 118

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 ⇒ Object

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

Used by: store= (visibility check), ClassModule#path, TopLevel#path,

ClassModule#embed_mixins



280
281
282
 
# File 'lib/rdoc/code_object.rb', line 280

def options
  @store&.options || RDoc::Options.new
end

#parent_name ⇒ Object

Name of our parent



310
311
312
 
# File 'lib/rdoc/code_object.rb', line 310

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

#record_location(top_level) ⇒ Object

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



317
318
319
320
321
 
# File 'lib/rdoc/code_object.rb', line 317

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

#start_doc ⇒ Object

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



337
338
339
340
341
342
343
344
 
# File 'lib/rdoc/code_object.rb', line 337

def start_doc
  return if @done_documenting

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

#stop_doc ⇒ Object

Disable capture of documentation



349
350
351
352
353
354
 
# File 'lib/rdoc/code_object.rb', line 349

def stop_doc
  return unless @track_visibility

  @document_self = false
  @document_children = false
end

#suppress ⇒ Object

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.



376
377
378
379
380
381
382
 
# File 'lib/rdoc/code_object.rb', line 376

def suppress
  return unless @track_visibility

  @suppressed = true

  stop_doc
end

#suppressed? ⇒ Boolean

Has this class been suppressed?

See also #suppress

Returns:

  • (Boolean) 


389
390
391
 
# File 'lib/rdoc/code_object.rb', line 389

def suppressed?
  @suppressed
end