blob: 2fcc92e8b511a16ed4dac8a32d3198bea69aa5af (
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
|
require 'rdoc'
require 'rdoc/text'
##
# 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)
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_accessor :done_documenting
##
# Force documentation of this CodeObject
attr_accessor :force_documentation
##
# Our parent CodeObject
attr_accessor :parent
##
# Which section are we in
attr_accessor :section
##
# 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
##
# There's a wee trick we pull. Comment blocks can have directives that
# override the stuff we extract during the parse. So, we have a special
# class method, attr_overridable, that lets code objects list those
# directives. When a comment is assigned, we then extract out any matching
# directives and update our object
def self.attr_overridable(name, *aliases)
@overridables ||= {}
attr_accessor name
aliases.unshift name
aliases.each do |directive_name|
@overridables[directive_name.to_s] = name
end
end
##
# Creates a new CodeObject that will document itself and its children
def initialize
@comment = ''
@document_children = true
@document_self = true
@done_documenting = false
@force_documentation = false
@parent = nil
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
else
if comment and not comment.empty? then
normalize_comment comment
else
@comment
end
end
end
##
# Enables or disables documentation of this CodeObject's children. Calls
# remove_classes_and_modules when disabling.
def document_children=(document_children)
@document_children = document_children
remove_classes_and_modules unless document_children
end
##
# Enables or disables documentation of this CodeObject. Calls
# remove_methods_etc when disabling.
def document_self=(document_self)
@document_self = document_self
remove_methods_etc unless document_self
end
##
# Does this class have a comment with content or is document_self false.
def documented?
!(@document_self and @comment.empty?)
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
##
# Callback called upon disabling documentation of children. See
# #document_children=
def remove_classes_and_modules
end
##
# Callback called upon disabling documentation of ourself. See
# #document_self=
def remove_methods_etc
end
##
# Enable capture of documentation
def start_doc
@document_self = true
@document_children = true
end
##
# Disable capture of documentation
def stop_doc
@document_self = false
@document_children = false
end
end
|