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

frozen_string_literal: false

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

Direct Known Subclasses

Alias, Constant, Context, MethodAttr, Mixin, Require

Constant Summary

Constants included from Text

Text::MARKUP_FORMAT, Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Generator::Markup

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

Methods included from Text

encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #parse, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap

Constructor Details

#initialize ⇒ CodeObject

Creates a new CodeObject that will document itself and its children



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/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

Instance Attribute Details

#comment ⇒ Object

Our comment



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

def comment
  @comment
end

#document_children ⇒ Object

Do we document our children?



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

def document_children
  @document_children
end

#document_self ⇒ Object

Do we document ourselves?



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

def document_self
  @document_self
end

#done_documenting ⇒ Object

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



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

def done_documenting
  @done_documenting
end

#file ⇒ Object (readonly)

Which file this code object was defined in



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

def file
  @file
end

#force_documentation ⇒ Object

Force documentation of this CodeObject



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

def force_documentation
  @force_documentation
end

#line ⇒ Object

Line in #file where this CodeObject was defined



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

def line
  @line
end

#metadata ⇒ Object (readonly)

Hash of arbitrary metadata for this CodeObject



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

def metadata
  @metadata
end

#offset ⇒ Object

Offset in #file where this CodeObject was defined – TODO character or byte?



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

def offset
  @offset
end

#parent ⇒ Object

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



317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/rdoc/code_object.rb', line 317

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?



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

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.



363
364
365
366
367
 
# File 'lib/rdoc/code_object.rb', line 363

def section
  return @section if @section

  @section = parent.add_section @section_title if parent
end

#store ⇒ Object

The RDoc::Store for this object.



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

def store
  @store
end

#viewer ⇒ Object

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.



104
105
106
 
# File 'lib/rdoc/code_object.rb', line 104

def viewer
  @viewer
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) 


171
172
173
174
 
# File 'lib/rdoc/code_object.rb', line 171

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) 


202
203
204
 
# File 'lib/rdoc/code_object.rb', line 202

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

#each_parent ⇒ Object

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



226
227
228
229
230
231
232
233
234
 
# File 'lib/rdoc/code_object.rb', line 226

def each_parent
  code_object = self

  while code_object = code_object.parent do
    yield code_object
  end

  self
end

#file_name ⇒ Object

File name where this CodeObject was found.

See also RDoc::Context#in_files



241
242
243
244
245
 
# File 'lib/rdoc/code_object.rb', line 241

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



262
263
264
 
# File 'lib/rdoc/code_object.rb', line 262

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.



282
283
284
285
286
287
288
 
# File 'lib/rdoc/code_object.rb', line 282

def ignore
  return unless @track_visibility

  @ignored = true

  stop_doc
end

#ignored? ⇒ Boolean

Has this class been ignored?

See also #ignore

Returns:

  • (Boolean) 


295
296
297
 
# File 'lib/rdoc/code_object.rb', line 295

def ignored?
  @ignored
end

#initialize_visibility ⇒ Object

Initializes state for visibility of this CodeObject and its children.



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/rdoc/code_object.rb', line 128

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.

This is used by Text#snippet



305
306
307
308
309
310
311
 
# File 'lib/rdoc/code_object.rb', line 305

def options
  if @store and @store.rdoc then
    @store.rdoc.options
  else
    RDoc::Options.new
  end
end

#parent_file_name ⇒ Object

File name of our parent



339
340
341
 
# File 'lib/rdoc/code_object.rb', line 339

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

#parent_name ⇒ Object

Name of our parent



346
347
348
 
# File 'lib/rdoc/code_object.rb', line 346

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



353
354
355
356
357
 
# File 'lib/rdoc/code_object.rb', line 353

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:



373
374
375
376
377
378
379
380
 
# File 'lib/rdoc/code_object.rb', line 373

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



385
386
387
388
389
390
 
# File 'lib/rdoc/code_object.rb', line 385

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.



412
413
414
415
416
417
418
 
# File 'lib/rdoc/code_object.rb', line 412

def suppress
  return unless @track_visibility

  @suppressed = true

  stop_doc
end

#suppressed? ⇒ Boolean

Has this class been suppressed?

See also #suppress

Returns:

  • (Boolean) 


425
426
427
 
# File 'lib/rdoc/code_object.rb', line 425

def suppressed?
  @suppressed
end