summaryrefslogtreecommitdiff
path: root/jni/ruby/lib/rdoc/code_object.rb
blob: 4620fa586da65f6be0ed7a6a3bee1d7d444bd886 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
##
# 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

class RDoc::CodeObject

  include RDoc::Text

  ##
  # Our comment

  attr_reader :comment

  ##
  # Do we document our children?

  attr_reader :document_children

  ##
  # Do we document ourselves?

  attr_reader :document_self

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

  attr_reader :done_documenting

  ##
  # Which file this code object was defined in

  attr_reader :file

  ##
  # Force documentation of this CodeObject

  attr_reader :force_documentation

  ##
  # Line in #file where this CodeObject was defined

  attr_accessor :line

  ##
  # Hash of arbitrary metadata for this CodeObject

  attr_reader :metadata

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

  attr_accessor :offset

  ##
  # Sets the parent CodeObject

  attr_writer :parent

  ##
  # Did we ever receive a +:nodoc:+ directive?

  attr_reader :received_nodoc

  ##
  # Set the section this CodeObject is in

  attr_writer :section

  ##
  # The RDoc::Store for this object.

  attr_reader :store

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

  attr_accessor :viewer

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

  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

  ##
  # Initializes state for visibility of this CodeObject and its children.

  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

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

  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
                      Object.const_defined? :Encoding and @comment.empty? then
                     @comment.force_encoding comment.encoding
                   end
                   @comment
                 end
               end
  end

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

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

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

  def document_children=(document_children)
    return unless @track_visibility

    @document_children = document_children unless @done_documenting
  end

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

  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

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

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

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

  def done_documenting=(value)
    return unless @track_visibility
    @done_documenting  = value
    @document_self     = !value
    @document_children = @document_self
  end

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

  def each_parent
    code_object = self

    while code_object = code_object.parent do
      yield code_object
    end

    self
  end

  ##
  # File name where this CodeObject was found.
  #
  # See also RDoc::Context#in_files

  def file_name
    return unless @file

    @file.absolute_name
  end

  ##
  # Force the documentation of this object unless documentation
  # has been turned off by :enddoc:
  #--
  # HACK untested, was assigning to an ivar

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

  ##
  # Sets the full_name overriding any computed full name.
  #
  # Set to +nil+ to clear RDoc's cached value

  def full_name= full_name
    @full_name = full_name
  end

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

  def ignore
    return unless @track_visibility

    @ignored = true

    stop_doc
  end

  ##
  # Has this class been ignored?
  #
  # See also #ignore

  def ignored?
    @ignored
  end

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

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

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

  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

  ##
  # File name of our parent

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

  ##
  # Name of our parent

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

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

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

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

  def section
    return @section if @section

    @section = parent.add_section @section_title if parent
  end

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

  def start_doc
    return if @done_documenting

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

  ##
  # Disable capture of documentation

  def stop_doc
    return unless @track_visibility

    @document_self = false
    @document_children = false
  end

  ##
  # Sets the +store+ that contains this CodeObject

  def store= store
    @store = store

    return unless @track_visibility

    if :nodoc == options.visibility then
      initialize_visibility
      @track_visibility = false
    end
  end

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

  def suppress
    return unless @track_visibility

    @suppressed = true

    stop_doc
  end

  ##
  # Has this class been suppressed?
  #
  # See also #suppress

  def suppressed?
    @suppressed
  end

end