Class: RDoc::CodeObject

Inherits:
Object
  • Object
show all
Includes:
Text
Defined in:
lib/rdoc/code_object.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::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::Require

  • RDoc::Include

Direct Known Subclasses

Alias, Constant, Context, Include, MethodAttr, Require

Constant Summary

Constants included from Text

Text::TO_HTML_CHARACTERS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Text

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

Constructor Details

#initialize ⇒ CodeObject

Creates a new CodeObject that will document itself and its children



105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/rdoc/code_object.rb', line 105

def initialize
  @metadata  = {}
  @comment   = ''
  @parent    = nil
  @file      = nil
  @full_name = nil

  @document_children   = true
  @document_self       = true
  @done_documenting    = false
  @force_documentation = false
  @received_nodoc      = false
  @ignored             = false
end

Instance Attribute Details

#comment ⇒ Object

Our comment



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

def comment
  @comment
end

#document_children ⇒ Object

Do we document our children?



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

def document_children
  @document_children
end

#document_self ⇒ Object

Do we document ourselves?



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

def document_self
  @document_self
end

#done_documenting ⇒ Object

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



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

def done_documenting
  @done_documenting
end

#file ⇒ Object (readonly)

Which file this code object was defined in



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

def file
  @file
end

#force_documentation ⇒ Object

Force documentation of this CodeObject



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

def force_documentation
  @force_documentation
end

#line ⇒ Object

Line in #file where this CodeObject was defined



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

def line
  @line
end

#metadata ⇒ Object (readonly)

Hash of arbitrary metadata for this CodeObject



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

def metadata
  @metadata
end

#offset ⇒ Object

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



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

def offset
  @offset
end

#parent ⇒ Object

Our parent CodeObject



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

def parent
  @parent
end

#received_nodoc ⇒ Object (readonly)

Did we ever receive a :nodoc: directive?



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

def received_nodoc
  @received_nodoc
end

#section ⇒ Object

Which section are we in



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

def section
  @section
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.



100
101
102
 
# File 'lib/rdoc/code_object.rb', line 100

def viewer
  @viewer
end

Instance Method Details

#display? ⇒ Boolean

Should this CodeObject be shown in documentation?

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/rdoc/code_object.rb', line 146

def display?
  @document_self and not @ignored
end

#documented? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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

#each_parent ⇒ Object

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



196
197
198
199
200
201
202
203
204
 
# File 'lib/rdoc/code_object.rb', line 196

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



211
212
213
214
215
 
# File 'lib/rdoc/code_object.rb', line 211

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



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

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 shown 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 shown. If a class was ignored and never reopened it should not be shown. The ignore flag allows this to occur.



251
252
253
254
255
 
# File 'lib/rdoc/code_object.rb', line 251

def ignore
  @ignored = true

  stop_doc
end

#ignored? ⇒ Boolean

Has this class been ignored?

Returns:

  • (Boolean) 


260
261
262
 
# File 'lib/rdoc/code_object.rb', line 260

def ignored?
  @ignored
end

#parent_file_name ⇒ Object

File name of our parent



267
268
269
 
# File 'lib/rdoc/code_object.rb', line 267

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

#parent_name ⇒ Object

Name of our parent



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

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



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

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

#start_doc ⇒ Object

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



290
291
292
293
294
295
296
 
# File 'lib/rdoc/code_object.rb', line 290

def start_doc
  return if @done_documenting

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

#stop_doc ⇒ Object

Disable capture of documentation



301
302
303
304
 
# File 'lib/rdoc/code_object.rb', line 301

def stop_doc
  @document_self = false
  @document_children = false
end