shomen-rdoc 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,149 @@
1
+ require 'rdoc'
2
+
3
+ class RDoc::TopLevel
4
+ #
5
+ def to_h
6
+ {
7
+ :path => path,
8
+ :name => base_name,
9
+ :fullname => full_name,
10
+ :rootname => absolute_name,
11
+ :modified => last_modified,
12
+ :diagram => diagram
13
+ }
14
+ end
15
+
16
+ #
17
+ #def to_json
18
+ # to_h.to_json
19
+ #end
20
+ end
21
+
22
+
23
+ class RDoc::ClassModule
24
+ #
25
+ def with_documentation?
26
+ document_self_or_methods || classes_and_modules.any?{ |c| c.with_documentation? }
27
+ end
28
+
29
+ #
30
+ def document_self_or_methods
31
+ document_self || method_list.any?{ |m| m.document_self }
32
+ end
33
+
34
+ # #
35
+ # def to_h
36
+ # {
37
+ # :name => name,
38
+ # :fullname => full_name,
39
+ # :type => type,
40
+ # :path => path,
41
+ # :superclass => module? ? nil : superclass
42
+ # }
43
+ # end
44
+ #
45
+ # def to_json
46
+ # to_h.to_json
47
+ # end
48
+ end
49
+
50
+
51
+ module RDoc::SourceCodeAccess
52
+
53
+ #
54
+ def source_code_raw
55
+ return '' unless @token_stream
56
+ src = ""
57
+ @token_stream.each do |t|
58
+ next unless t
59
+ src << t.text
60
+ end
61
+ #add_line_numbers(src)
62
+ src
63
+ end
64
+
65
+ #
66
+ def source_code_location
67
+ src = source_code_raw
68
+ if md = /File (.*?), line (\d+)/.match(src)
69
+ file = md[1]
70
+ line = md[2]
71
+ else
72
+ file = "(unknown)"
73
+ line = 0
74
+ end
75
+ return file, line
76
+ end
77
+
78
+ end
79
+
80
+
81
+ class RDoc::AnyMethod
82
+ include RDoc::SourceCodeAccess
83
+
84
+ # # NOTE: dont_rename_initialize isn't used
85
+ # def to_h
86
+ # {
87
+ # :name => name,
88
+ # :fullname => full_name,
89
+ # :prettyname => pretty_name,
90
+ # :path => path,
91
+ # :type => type,
92
+ # :visibility => visibility,
93
+ # :blockparams => block_params,
94
+ # :singleton => singleton,
95
+ # :text => text,
96
+ # :aliases => aliases,
97
+ # :aliasfor => is_alias_for,
98
+ # :aref => aref,
99
+ # :parms => params,
100
+ # :callseq => call_seq
101
+ # #:paramseq => param_seq,
102
+ # }
103
+ # end
104
+
105
+ # #
106
+ # def to_json
107
+ # to_h.to_json
108
+ # end
109
+ end
110
+
111
+ class RDoc::Attr
112
+ include RDoc::SourceCodeAccess
113
+ end
114
+
115
+ =begin
116
+
117
+ # DEPRECATE ASAP
118
+ require "rdoc/parser/c"
119
+ # New RDoc somehow misses class comemnts.
120
+ # copyied this function from "2.2.2"
121
+ if ['2.4.2', '2.4.3'].include? RDoc::VERSION
122
+ class RDoc::Parser::C
123
+ def find_class_comment(class_name, class_meth)
124
+ comment = nil
125
+ if @content =~ %r{((?>/\*.*?\*/\s+))
126
+ (static\s+)?void\s+Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)\)}xmi then
127
+ comment = $1
128
+ elsif @content =~ %r{Document-(?:class|module):\s#{class_name}\s*?(?:<\s+[:,\w]+)?\n((?>.*?\*/))}m
129
+ comment = $1
130
+ else
131
+ if @content =~ /rb_define_(class|module)/m then
132
+ class_name = class_name.split("::").last
133
+ comments = []
134
+ @content.split(/(\/\*.*?\*\/)\s*?\n/m).each_with_index do |chunk, index|
135
+ comments[index] = chunk
136
+ if chunk =~ /rb_define_(class|module).*?"(#{class_name})"/m then
137
+ comment = comments[index-1]
138
+ break
139
+ end
140
+ end
141
+ end
142
+ end
143
+ class_meth.comment = mangle_comment(comment) if comment
144
+ end
145
+ end
146
+ end
147
+
148
+ =end
149
+
@@ -0,0 +1,63 @@
1
+ == Class Documentation
2
+
3
+ === Simple Example with a Barren Class
4
+
5
+ Given a file +lib/example.rb+ containing a minimally documented and
6
+ essentially barren class:
7
+
8
+ # This class is documented.
9
+ class ExampleClass
10
+ end
11
+
12
+ Running the script through shomen command line interface, regardless of which
13
+ underlying parser is used, should produce a data structure conforming to the
14
+ Shomen standard data format having the following characteristics.
15
+
16
+ The data structure should have three entries.
17
+
18
+ @shomen.keys.assert.include?('(metadata)')
19
+ @shomen.keys.assert.include?('ExampleClass')
20
+ @shomen.keys.assert.include?('/lib/example.rb')
21
+
22
+ The `ExampleClass` entry should have a "bang" type of `class`.
23
+
24
+ @shomen['ExampleClass']['!'] #=> 'class'
25
+
26
+ It should have a name of `ExampleClass`.
27
+
28
+ @shomen['ExampleClass']['name'] #=> 'ExampleClass'
29
+
30
+ While the namespace should be an empty string because the class is defined
31
+ at the toplevel.
32
+
33
+ @shomen['ExampleClass']['namespace'] #=> ''
34
+
35
+ The full `path` field will be the same as the name for the same reason.
36
+
37
+ @shomen['ExampleClass']['path'] #=> 'ExampleClass'
38
+
39
+ The `superclass` will be Object.
40
+
41
+ @shomen['ExampleClass']['superclass'] #=> 'Object'
42
+
43
+ The `comment` field will as given in the script.
44
+
45
+ @shomen['ExampleClass']['comment'] #=> "This class is documented."
46
+
47
+ And the `files` field should list only `/lib/example.rb`.
48
+
49
+ @shomen['ExampleClass']['files'] #=> ['/lib/example.rb']
50
+
51
+ Notice that the leading root slash `/` is part of the file name. This refers
52
+ to the root of the project, as opposed to the root of one's file system, and
53
+ makes it easier to lookup files in the index, the the root slash is used to
54
+ distinguish file names from other entries.
55
+
56
+ Since out example class is barren the remaining fields will either be
57
+ missing (i.e. `nil`) or empty collections.
58
+
59
+ @shomen['ExampleClass']['constants'].to_a #=> []
60
+ @shomen['ExampleClass']['modules'].to_a #=> []
61
+ @shomen['ExampleClass']['classes'].to_a #=> []
62
+ @shomen['ExampleClass']['methods'].to_a #=> []
63
+
@@ -0,0 +1,59 @@
1
+ == Module Documentation
2
+
3
+ === Simple Example with a Barren Module
4
+
5
+ Given a file +lib/example.rb+ containing a minimally documented and
6
+ essentially barren class:
7
+
8
+ # This module is documented.
9
+ module ExampleModule
10
+ end
11
+
12
+ Running the script through shomen command line interface, regardless of which
13
+ underlying parser is used, should produce a data structure conforming to the
14
+ Shomen standard data format having the following characteristics.
15
+
16
+ The data structure should have three entries.
17
+
18
+ @shomen.keys.assert.include?('(metadata)')
19
+ @shomen.keys.assert.include?('ExampleModule')
20
+ @shomen.keys.assert.include?('/lib/example.rb')
21
+
22
+ The `ExampleModule` entry should have a "bang" type of `module`.
23
+
24
+ @shomen['ExampleModule']['!'] #=> 'module'
25
+
26
+ It should have a name of `ExampleModule`.
27
+
28
+ @shomen['ExampleModule']['name'] #=> 'ExampleModule'
29
+
30
+ While the namespace should be an empty string because the class is defined
31
+ at the toplevel.
32
+
33
+ @shomen['ExampleModule']['namespace'] #=> ''
34
+
35
+ The full `path` field will be the same as the name for the same reason.
36
+
37
+ @shomen['ExampleModule']['path'] #=> 'ExampleModule'
38
+
39
+ As a module it should not have a `superclass` entry.
40
+
41
+ @shomen['ExampleModule'].refute.key?('superclass')
42
+
43
+ The `comment` field will as given in the script.
44
+
45
+ @shomen['ExampleModule']['comment'] #=> "This module is documented."
46
+
47
+ And the `files` field should list only `lib/example.rb`.
48
+
49
+ @shomen['ExampleModule']['files'] #=> ['/lib/example.rb']
50
+
51
+ Since out example class is barren the remaining fields will either be
52
+ missing (i.e. `nil`) or empty collections.
53
+
54
+ @shomen['ExampleModule']['constants'].to_a #=> []
55
+ @shomen['ExampleModule']['modules'].to_a #=> []
56
+ @shomen['ExampleModule']['classes'].to_a #=> []
57
+ @shomen['ExampleModule']['methods'].to_a #=> []
58
+ @shomen['ExampleModule']['class-methods'].to_a #=> []
59
+
@@ -0,0 +1,59 @@
1
+ == Constant Documentation
2
+
3
+ === Class/Module Constant
4
+
5
+ Given a file +lib/example.rb+ containing a documented constant in a class
6
+ (or module):
7
+
8
+ class ExampleClass
9
+ # This constant is documented.
10
+ ExampleConstant = "example"
11
+ end
12
+
13
+ Running the script through shomen command line interface, regardless of which
14
+ underlying parser is used, should produce a data structure conforming to the
15
+ Shomen standard data format having the following characteristics.
16
+
17
+ The data structure should have four entries.
18
+
19
+ @shomen.keys.size #=> 4
20
+
21
+ @shomen.keys.assert.include?('(metadata)')
22
+ @shomen.keys.assert.include?('ExampleClass')
23
+ @shomen.keys.assert.include?('ExampleClass::ExampleConstant')
24
+ @shomen.keys.assert.include?('/lib/example.rb')
25
+
26
+ We want to inspect the constant entry itself, so we will assign the entry
27
+ to a variable to ease readability.
28
+
29
+ constant = @shomen['ExampleClass::ExampleConstant']
30
+
31
+ The `ExampleConstant` entry should have a "bang" type of `constant`.
32
+
33
+ constant['!'] #=> 'constant'
34
+
35
+ It should have a name of `ExampleConstant`.
36
+
37
+ constant['name'] #=> 'ExampleConstant'
38
+
39
+ While the namespace should be `ExampleClass`.
40
+
41
+ constant['namespace'] #=> 'ExampleClass'
42
+
43
+ The full `path` field will be the same as the name for the same reason.
44
+
45
+ constant['path'] #=> 'ExampleClass::ExampleConstant'
46
+
47
+ The `comment` field will as given in the script.
48
+
49
+ constant['comment'] #=> "This constant is documented."
50
+
51
+ And the `files` field should list only `lib/example.rb`.
52
+
53
+ constant['files'] #=> ['/lib/example.rb']
54
+
55
+ Lastly, the `value` field should contain the value the literal representation
56
+ of the value to which the constant is set.
57
+
58
+ constant['value'] #=> '"example"'
59
+
@@ -0,0 +1,286 @@
1
+ = Method Documentation
2
+
3
+ == Instance Method
4
+
5
+ === Instance Method without Arguments
6
+
7
+ Given a file +lib/example.rb+ containing a class with a documented method:
8
+
9
+ # This class is documented.
10
+ class ExampleClass
11
+ # This method is documented.
12
+ def example_method
13
+ end
14
+ end
15
+
16
+ Running the script through shomen command line interface, regardless of which
17
+ underlying parser is used, should produce a data structure conforming to the
18
+ Shomen standard data format having the following characteristics.
19
+
20
+ The data structure should have four entries.
21
+
22
+ @shomen.keys.assert.include?('(metadata)')
23
+ @shomen.keys.assert.include?('/lib/example.rb')
24
+ @shomen.keys.assert.include?('ExampleClass')
25
+ @shomen.keys.assert.include?('ExampleClass#example_method')
26
+
27
+ In the following assertions we will repeatedly refer to the `ExampleClass#example_method`
28
+ entry, so lets create a short-hnad variable to ease our reeading
29
+
30
+ example = @shomen['ExampleClass#example_method']
31
+
32
+ The example method entry should have a "bang" type of `method`.
33
+
34
+ example['!'] #=> 'method'
35
+
36
+ It should also have a name of `example_method`.
37
+
38
+ example['name'] #=> 'example_method'
39
+
40
+ While the namespace should be the name of the class it is defined within.
41
+
42
+ example['namespace'] #=> 'ExampleClass'
43
+
44
+ The full `path` field will be the class name combined with the method's name.
45
+
46
+ example['path'] #=> 'ExampleClass#example_method'
47
+
48
+ The `comment` field will as given.
49
+
50
+ example['comment'] #=> "This method is documented."
51
+
52
+ The entry will also nThe methods declarations in this case should be the defaults.
53
+
54
+ example['declarations'].assert.include?('public')
55
+ example['declarations'].assert.include?('instance')
56
+ ot be marked as `singleton`.
57
+
58
+ example['singleton'] #=> false
59
+
60
+ The methods declarations in this case should be the defaults.
61
+
62
+ example['declarations'].assert.include?('public')
63
+ example['declarations'].assert.include?('instance')
64
+
65
+ Technically these declaraitons could be left out becuse they are the defaults,
66
+ but our Shomen parser includes them for clarity.
67
+
68
+ The `file` field should list only `/lib/example.rb`.
69
+
70
+ example['file'] #=> '/lib/example.rb'
71
+
72
+ The `line` field gives the line number on which the method is defined.
73
+
74
+ example['line'] #=> 4
75
+
76
+ The interfaces list will have only one entry which will be essentially empty
77
+ since our example method has no arguments.
78
+
79
+ example['interfaces'][0]['signature'] #=> 'example_method()'
80
+ example['interfaces'][0]['arguments'].to_a #=> []
81
+ example['interfaces'][0]['parameters'].to_a #=> []
82
+
83
+ Sine the method does not take a block the block value should be `nil`.
84
+
85
+ example['interfaces'][0]['block'] #=> nil
86
+
87
+ === Instance Method with Arguments
88
+
89
+ Given a file +lib/example.rb+ containing a class with a documented method which
90
+ has arguments:
91
+
92
+ # This class is documented.
93
+ class ExampleClass
94
+ # This method is documented.
95
+ def example_method(a=1,o={},&b)
96
+ end
97
+ end
98
+
99
+ Using RDoc, Running the script through shomen command line interface will not
100
+ give us much signature information b/c RDoc has no structured support for
101
+ documenting argument details. But it will still provide some basic
102
+ information.
103
+
104
+ The interfaces list will have only one entry.
105
+
106
+ example = @shomen['ExampleClass#example_method']
107
+ example['interfaces'].size #=> 1
108
+
109
+ Lets get a closer look at this signature.
110
+
111
+ signature = example['interfaces'].first
112
+
113
+ The signature itself should match the literal definition.
114
+
115
+ signature['signature'] #=> 'example_method(a=1,o={},&b)'
116
+
117
+ Each argument should be in the arguments list, but without
118
+ a comment since RDoc does not provide any support for specifying
119
+ an argument comment.
120
+
121
+ signature['arguments'][0]['name'] #=> 'a'
122
+ signature['arguments'][0]['default'] #=> '1'
123
+ signature['arguments'][0]['comment'] #=> nil
124
+
125
+ signature['arguments'][1]['name'] #=> 'o'
126
+ signature['arguments'][1]['default'] #=> '{}'
127
+ signature['arguments'][1]['comment'] #=> nil
128
+
129
+ RDoc also does not provide support for describing named parameters,
130
+ so the list will be `nil` or an empty array.
131
+
132
+ signature['parameters'].to_a #=> []
133
+
134
+ And the block argument should provide the name of the block argument
135
+ but again RDoc does not support a block argument comment.
136
+
137
+ signature['block']['name'] #=> '&b'
138
+ signature['block']['comment'] #=> nil
139
+
140
+
141
+ == Class Methods
142
+
143
+ === Class Method without Arguments
144
+
145
+ Given a file +lib/example.rb+ containing a class with a documented class method:
146
+
147
+ # This class is documented.
148
+ class ExampleClass
149
+ # This class method is documented.
150
+ def self.example_class_method()
151
+ end
152
+ end
153
+
154
+ Running the script through shomen command line interface, regardless of which
155
+ underlying parser is used, should produce a data structure conforming to the
156
+ Shomen standard data format having the following characteristics.
157
+
158
+ The data structure should have four entries: the metadata entry, an entry
159
+ for the source file, an entry for the class and an entry for the class method.
160
+
161
+ @shomen.keys.assert.include?('(metadata)')
162
+ @shomen.keys.assert.include?('/lib/example.rb')
163
+ @shomen.keys.assert.include?('ExampleClass')
164
+ @shomen.keys.assert.include?('ExampleClass.example_class_method')
165
+
166
+ In the following assertions we will repeatedly refer to the `ExampleClass#example_class_method`
167
+ entry, so lets create a short-hnad variable to ease our reeading
168
+
169
+ example = @shomen['ExampleClass.example_class_method']
170
+
171
+ The example method entry should have a "bang" type of `class-method`.
172
+
173
+ example['!'] #=> 'method'
174
+
175
+ It should also have a name of `example_class_method`.
176
+
177
+ example['name'] #=> 'example_class_method'
178
+
179
+ While the namespace should be the name of the class it is defined within.
180
+
181
+ example['namespace'] #=> 'ExampleClass'
182
+
183
+ The full `path` field will be the class name combined with the method's name.
184
+
185
+ example['path'] #=> 'ExampleClass.example_class_method'
186
+
187
+ The `comment` field will as given.
188
+
189
+ example['comment'] #=> "This class method is documented."
190
+
191
+ The entry will also be marked as `singleton`.
192
+
193
+ example['singleton'] #=> true
194
+
195
+ The methods declarations in this case should contain `class`, since this
196
+ is a class method after all.
197
+
198
+ example['declarations'].assert.include?('class')
199
+
200
+ The `file` field should list only `lib/example.rb`.
201
+
202
+ example['file'] #=> '/lib/example.rb'
203
+
204
+ The `line` field gives the line number on which the method is defined.
205
+
206
+ example['line'] #=> 4
207
+
208
+ The interfaces list will have only one entry.
209
+
210
+ example['interfaces'].size #=> 1
211
+
212
+ Let's make it easier to get a closer look at this signature by assigning
213
+ it to a temporary variable.
214
+
215
+ sig = example['interfaces'].first
216
+
217
+ The signature image will be given verbatim.
218
+
219
+ sig['signature'].assert == 'example_class_method()'
220
+
221
+ While arguments and parameters will be empty since our example method has
222
+ no arguments.
223
+
224
+ sig['arguments'].to_a #=> []
225
+ sig['parameters'].to_a #=> []
226
+
227
+ And since the method does not take a block the block value should be `nil`.
228
+
229
+ sig['block'] #=> nil
230
+
231
+ === Class Method with Arguments
232
+
233
+ Given a file +lib/example.rb+ containing a class with a documented method which
234
+ has arguments:
235
+
236
+ # This class is documented.
237
+ class ExampleClass
238
+ # This class method is documented.
239
+ def self.example_class_method(a=1,o={},&b)
240
+ end
241
+ end
242
+
243
+ Running the script through shomen command line interface will not
244
+ give us much signature information b/c RDoc does not support
245
+ documenting argument details and in this case we have not provided
246
+ any YARD specific tags for doing so. But it will still provide some
247
+ basic information.
248
+
249
+ The interfaces list will have only one entry.
250
+
251
+ example = @shomen['ExampleClass.example_class_method']
252
+
253
+ example['interfaces'].size #=> 1
254
+
255
+ Lets get a closer look at this signature.
256
+
257
+ signature = example['interfaces'].last
258
+
259
+ The signature itself should match the literal definition.
260
+
261
+ signature['signature'] #=> 'example_class_method(a=1,o={},&b)'
262
+
263
+ Each argument should be in the arguments list, but without
264
+ a comment since RDoc does not provide any support for specifying
265
+ an argument comment.
266
+
267
+ signature['arguments'][0]['name'] #=> 'a'
268
+ signature['arguments'][0]['default'] #=> '1'
269
+ signature['arguments'][0]['comment'] #=> nil
270
+
271
+ signature['arguments'][1]['name'] #=> 'o'
272
+ signature['arguments'][1]['default'] #=> '{}'
273
+ signature['arguments'][1]['comment'] #=> nil
274
+
275
+ RDoc also does not provide support for describing named parameters,
276
+ so the list will be `nil` or an empty array.
277
+
278
+ signature['parameters'].to_a #=> []
279
+
280
+ And the block argument should provide the name of the block argument
281
+ but again RDoc does not support a block argument comment.
282
+
283
+ signature['block']['name'] #=> '&b'
284
+ signature['block']['comment'] #=> nil
285
+
286
+