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.
- data/.ruby +59 -0
- data/HISTORY.rdoc +14 -0
- data/LICENSE.txt +29 -0
- data/README.rdoc +6 -0
- data/bin/shomen-rdoc +3 -0
- data/lib/shomen-rdoc.rb +26 -0
- data/lib/shomen-rdoc.yml +59 -0
- data/lib/shomen-rdoc/command.rb +151 -0
- data/lib/shomen-rdoc/generator.rb +900 -0
- data/lib/shomen-rdoc/rdoc_ext.rb +149 -0
- data/spec/02_class.rdoc +63 -0
- data/spec/03_module.rdoc +59 -0
- data/spec/04_constant.rdoc +59 -0
- data/spec/05_method.rdoc +286 -0
- data/spec/10_interface_overloading.rdoc +94 -0
- data/spec/applique/ae.rb +1 -0
- data/spec/applique/shomen.rb +24 -0
- data/spec/fixture/lib/example.rb +52 -0
- metadata +105 -0
@@ -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
|
+
|
data/spec/02_class.rdoc
ADDED
@@ -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
|
+
|
data/spec/03_module.rdoc
ADDED
@@ -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
|
+
|
data/spec/05_method.rdoc
ADDED
@@ -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
|
+
|