puppet-strings 2.4.0 → 2.5.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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +30 -2
- data/lib/puppet-strings.rb +2 -2
- data/lib/puppet-strings/markdown.rb +1 -1
- data/lib/puppet-strings/markdown/base.rb +6 -0
- data/lib/puppet-strings/markdown/data_type.rb +16 -0
- data/lib/puppet-strings/markdown/resource_type.rb +19 -2
- data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +4 -4
- data/lib/puppet-strings/markdown/templates/data_type.erb +11 -4
- data/lib/puppet-strings/markdown/templates/data_type_function.erb +67 -0
- data/lib/puppet-strings/markdown/templates/function.erb +2 -1
- data/lib/puppet-strings/markdown/templates/puppet_task.erb +1 -1
- data/lib/puppet-strings/markdown/templates/resource_type.erb +12 -12
- data/lib/puppet-strings/markdown/templates/table_of_contents.erb +6 -6
- data/lib/puppet-strings/version.rb +1 -1
- data/lib/puppet-strings/yard/code_objects/data_type.rb +26 -6
- data/lib/puppet-strings/yard/code_objects/type.rb +46 -5
- data/lib/puppet-strings/yard/handlers/ruby/data_type_handler.rb +190 -43
- data/lib/puppet-strings/yard/handlers/ruby/type_base.rb +6 -0
- data/lib/puppet-strings/yard/handlers/ruby/type_extras_handler.rb +1 -1
- data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +6 -0
- data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/method_details_list.erb +6 -0
- data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/setup.rb +9 -1
- data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb +3 -1
- metadata +4 -46
- data/CODEOWNERS +0 -1
- data/Gemfile +0 -53
- data/HISTORY.md +0 -218
- data/JSON.md +0 -832
- data/Rakefile +0 -160
- data/codecov.yml +0 -3
- data/misc/ANNOUNCEMENT_TEMPLATE.md +0 -40
- data/spec/acceptance/emit_json_options_spec.rb +0 -69
- data/spec/acceptance/generate_markdown_spec.rb +0 -47
- data/spec/acceptance/running_strings_generate_spec.rb +0 -88
- data/spec/fixtures/acceptance/modules/test/functions/add.pp +0 -9
- data/spec/fixtures/acceptance/modules/test/lib/puppet/functions/4x_function.rb +0 -5
- data/spec/fixtures/acceptance/modules/test/lib/puppet/parser/functions/function3x.rb +0 -2
- data/spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/linux.rb +0 -9
- data/spec/fixtures/acceptance/modules/test/lib/puppet/type/database.rb +0 -15
- data/spec/fixtures/acceptance/modules/test/manifests/init.pp +0 -31
- data/spec/fixtures/acceptance/modules/test/manifests/triple_nested_classes.pp +0 -27
- data/spec/fixtures/acceptance/modules/test/metadata.json +0 -10
- data/spec/fixtures/acceptance/modules/test/types/elephant.pp +0 -2
- data/spec/fixtures/unit/markdown/output.md +0 -561
- data/spec/fixtures/unit/markdown/output_with_data_types.md +0 -606
- data/spec/fixtures/unit/markdown/output_with_plan.md +0 -595
- data/spec/spec_helper.rb +0 -49
- data/spec/spec_helper_acceptance.rb +0 -58
- data/spec/spec_helper_acceptance_local.rb +0 -10
- data/spec/unit/puppet-strings/describe_spec.rb +0 -141
- data/spec/unit/puppet-strings/json_spec.rb +0 -302
- data/spec/unit/puppet-strings/markdown/base_spec.rb +0 -146
- data/spec/unit/puppet-strings/markdown_spec.rb +0 -374
- data/spec/unit/puppet-strings/yard/code_objects/task_spec.rb +0 -92
- data/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb +0 -116
- data/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb +0 -217
- data/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb +0 -65
- data/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb +0 -231
- data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +0 -315
- data/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb +0 -309
- data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +0 -746
- data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +0 -158
- data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +0 -235
- data/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +0 -311
- data/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb +0 -72
- data/spec/unit/puppet-strings/yard/parsers/json/task_statement_spec.rb +0 -56
- data/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb +0 -251
- data/spec/unit/puppet-strings/yard/util_spec.rb +0 -48
@@ -1,231 +0,0 @@
|
|
1
|
-
require 'spec_helper'
|
2
|
-
require 'puppet-strings/yard'
|
3
|
-
|
4
|
-
describe PuppetStrings::Yard::Handlers::Puppet::DefinedTypeHandler do
|
5
|
-
subject {
|
6
|
-
YARD::Parser::SourceParser.parse_string(source, :puppet)
|
7
|
-
YARD::Registry.all(:puppet_defined_type)
|
8
|
-
}
|
9
|
-
|
10
|
-
describe 'parsing source without a defined type definition' do
|
11
|
-
let(:source) { 'notice hi' }
|
12
|
-
|
13
|
-
it 'no defined types should be in the registry' do
|
14
|
-
expect(subject.empty?).to eq(true)
|
15
|
-
end
|
16
|
-
end
|
17
|
-
|
18
|
-
describe 'parsing source with a syntax error' do
|
19
|
-
let(:source) { 'define foo{' }
|
20
|
-
|
21
|
-
it 'should log an error' do
|
22
|
-
expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of (file|input)/).to_stdout_from_any_process
|
23
|
-
expect(subject.empty?).to eq(true)
|
24
|
-
end
|
25
|
-
end
|
26
|
-
|
27
|
-
describe 'parsing a defined type with a missing docstring' do
|
28
|
-
let(:source) { 'define foo{}' }
|
29
|
-
|
30
|
-
it 'should log a warning' do
|
31
|
-
expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet defined type 'foo' at \(stdin\):1\./).to_stdout_from_any_process
|
32
|
-
end
|
33
|
-
end
|
34
|
-
|
35
|
-
describe 'parsing a defined type with a docstring' do
|
36
|
-
let(:source) { <<-SOURCE
|
37
|
-
# A simple foo defined type.
|
38
|
-
# @param name The type name.
|
39
|
-
# @param param1 First param.
|
40
|
-
# @param param2 Second param.
|
41
|
-
# @param param3 Third param.
|
42
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
43
|
-
file { '/tmp/foo':
|
44
|
-
ensure => present
|
45
|
-
}
|
46
|
-
}
|
47
|
-
SOURCE
|
48
|
-
}
|
49
|
-
it 'does not output a warning for title/name' do
|
50
|
-
expect{ subject }.not_to output(/\[warn\].*(name|title).*/).to_stdout_from_any_process
|
51
|
-
end
|
52
|
-
|
53
|
-
it 'should register a defined type object' do
|
54
|
-
expect(subject.size).to eq(1)
|
55
|
-
object = subject.first
|
56
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DefinedType)
|
57
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DefinedTypes.instance)
|
58
|
-
expect(object.name).to eq(:foo)
|
59
|
-
expect(object.statement).not_to eq(nil)
|
60
|
-
expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']])
|
61
|
-
expect(object.docstring).to eq('A simple foo defined type.')
|
62
|
-
expect(object.docstring.tags.size).to eq(5)
|
63
|
-
tags = object.docstring.tags(:param)
|
64
|
-
expect(tags.size).to eq(4)
|
65
|
-
expect(tags[0].name).to eq('name')
|
66
|
-
expect(tags[0].text).to eq('The type name.')
|
67
|
-
expect(tags[0].types).to eq(nil)
|
68
|
-
expect(tags[1].name).to eq('param1')
|
69
|
-
expect(tags[1].text).to eq('First param.')
|
70
|
-
expect(tags[1].types).to eq(['Integer'])
|
71
|
-
expect(tags[2].name).to eq('param2')
|
72
|
-
expect(tags[2].text).to eq('Second param.')
|
73
|
-
expect(tags[2].types).to eq(['Any'])
|
74
|
-
expect(tags[3].name).to eq('param3')
|
75
|
-
expect(tags[3].text).to eq('Third param.')
|
76
|
-
expect(tags[3].types).to eq(['String'])
|
77
|
-
tags = object.docstring.tags(:api)
|
78
|
-
expect(tags.size).to eq(1)
|
79
|
-
expect(tags[0].text).to eq('public')
|
80
|
-
end
|
81
|
-
end
|
82
|
-
|
83
|
-
describe 'parsing a defined type with a missing parameter' do
|
84
|
-
let(:source) { <<-SOURCE
|
85
|
-
# A simple foo defined type.
|
86
|
-
# @param param1 First param.
|
87
|
-
# @param param2 Second param.
|
88
|
-
# @param param3 Third param.
|
89
|
-
# @param param4 missing!
|
90
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
91
|
-
file { '/tmp/foo':
|
92
|
-
ensure => present
|
93
|
-
}
|
94
|
-
}
|
95
|
-
SOURCE
|
96
|
-
}
|
97
|
-
|
98
|
-
it 'should output a warning' do
|
99
|
-
expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):6\./).to_stdout_from_any_process
|
100
|
-
end
|
101
|
-
end
|
102
|
-
|
103
|
-
describe 'parsing a defined type with a missing @param tag' do
|
104
|
-
let(:source) { <<-SOURCE
|
105
|
-
# A simple foo defined type.
|
106
|
-
# @param param1 First param.
|
107
|
-
# @param param2 Second param.
|
108
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
109
|
-
file { '/tmp/foo':
|
110
|
-
ensure => present
|
111
|
-
}
|
112
|
-
}
|
113
|
-
SOURCE
|
114
|
-
}
|
115
|
-
|
116
|
-
it 'should output a warning' do
|
117
|
-
expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):4\./).to_stdout_from_any_process
|
118
|
-
end
|
119
|
-
end
|
120
|
-
|
121
|
-
describe 'parsing a defined type with a typed parameter that also has a @param tag type which matches' do
|
122
|
-
let(:source) { <<-SOURCE
|
123
|
-
# A simple foo defined type.
|
124
|
-
# @param [Integer] param1 First param.
|
125
|
-
# @param param2 Second param.
|
126
|
-
# @param param3 Third param.
|
127
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
128
|
-
file { '/tmp/foo':
|
129
|
-
ensure => present
|
130
|
-
}
|
131
|
-
}
|
132
|
-
SOURCE
|
133
|
-
}
|
134
|
-
|
135
|
-
it 'should respect the type that was documented' do
|
136
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
137
|
-
expect(subject.size).to eq(1)
|
138
|
-
tags = subject.first.tags(:param)
|
139
|
-
expect(tags.size).to eq(3)
|
140
|
-
expect(tags[0].types).to eq(['Integer'])
|
141
|
-
end
|
142
|
-
end
|
143
|
-
|
144
|
-
describe 'parsing a defined type with a typed parameter that also has a @param tag type which does not match' do
|
145
|
-
let(:source) { <<-SOURCE
|
146
|
-
# A simple foo defined type.
|
147
|
-
# @param [Boolean] param1 First param.
|
148
|
-
# @param param2 Second param.
|
149
|
-
# @param param3 Third param.
|
150
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
151
|
-
file { '/tmp/foo':
|
152
|
-
ensure => present
|
153
|
-
}
|
154
|
-
}
|
155
|
-
SOURCE
|
156
|
-
}
|
157
|
-
|
158
|
-
it 'should output a warning' do
|
159
|
-
expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):5: ignoring in favor of parameter type information./).to_stdout_from_any_process
|
160
|
-
end
|
161
|
-
end
|
162
|
-
|
163
|
-
describe 'parsing a defined type with a untyped parameter that also has a @param tag type' do
|
164
|
-
let(:source) { <<-SOURCE
|
165
|
-
# A simple foo defined type.
|
166
|
-
# @param param1 First param.
|
167
|
-
# @param [Boolean] param2 Second param.
|
168
|
-
# @param param3 Third param.
|
169
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
170
|
-
file { '/tmp/foo':
|
171
|
-
ensure => present
|
172
|
-
}
|
173
|
-
}
|
174
|
-
SOURCE
|
175
|
-
}
|
176
|
-
|
177
|
-
it 'should respect the type that was documented' do
|
178
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
179
|
-
expect(subject.size).to eq(1)
|
180
|
-
tags = subject.first.tags(:param)
|
181
|
-
expect(tags.size).to eq(3)
|
182
|
-
expect(tags[1].types).to eq(['Boolean'])
|
183
|
-
end
|
184
|
-
end
|
185
|
-
|
186
|
-
describe 'parsing a defined type with a summary' do
|
187
|
-
|
188
|
-
context 'when the summary has fewer than 140 characters' do
|
189
|
-
let(:source) { <<-SOURCE
|
190
|
-
# A simple foo defined type.
|
191
|
-
# @summary A short summary.
|
192
|
-
# @param param1 First param.
|
193
|
-
# @param [Boolean] param2 Second param.
|
194
|
-
# @param param3 Third param.
|
195
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
196
|
-
file { '/tmp/foo':
|
197
|
-
ensure => present
|
198
|
-
}
|
199
|
-
}
|
200
|
-
SOURCE
|
201
|
-
}
|
202
|
-
|
203
|
-
it 'should parse the summary' do
|
204
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
205
|
-
expect(subject.size).to eq(1)
|
206
|
-
summary = subject.first.tags(:summary)
|
207
|
-
expect(summary.first.text).to eq('A short summary.')
|
208
|
-
end
|
209
|
-
end
|
210
|
-
|
211
|
-
context 'when the summary has more than 140 characters' do
|
212
|
-
let(:source) { <<-SOURCE
|
213
|
-
# A simple foo defined type.
|
214
|
-
# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
|
215
|
-
# @param param1 First param.
|
216
|
-
# @param [Boolean] param2 Second param.
|
217
|
-
# @param param3 Third param.
|
218
|
-
define foo(Integer $param1, $param2, String $param3 = hi) {
|
219
|
-
file { '/tmp/foo':
|
220
|
-
ensure => present
|
221
|
-
}
|
222
|
-
}
|
223
|
-
SOURCE
|
224
|
-
}
|
225
|
-
|
226
|
-
it 'should log a warning' do
|
227
|
-
expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_defined_type 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
|
228
|
-
end
|
229
|
-
end
|
230
|
-
end
|
231
|
-
end
|
@@ -1,315 +0,0 @@
|
|
1
|
-
require 'spec_helper'
|
2
|
-
require 'puppet-strings/yard'
|
3
|
-
|
4
|
-
# Limit this spec to Puppet 4.1+ (when functions in Puppet were implemented)
|
5
|
-
describe PuppetStrings::Yard::Handlers::Puppet::FunctionHandler, if: TEST_PUPPET_FUNCTIONS do
|
6
|
-
subject {
|
7
|
-
YARD::Parser::SourceParser.parse_string(source, :puppet)
|
8
|
-
YARD::Registry.all(:puppet_function)
|
9
|
-
}
|
10
|
-
|
11
|
-
describe 'parsing source without a function definition' do
|
12
|
-
let(:source) { 'notice hi' }
|
13
|
-
|
14
|
-
it 'no functions should be in the registry' do
|
15
|
-
expect(subject.empty?).to eq(true)
|
16
|
-
end
|
17
|
-
end
|
18
|
-
|
19
|
-
describe 'parsing source with a syntax error' do
|
20
|
-
let(:source) { 'function foo{' }
|
21
|
-
|
22
|
-
it 'should log an error' do
|
23
|
-
expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of/).to_stdout_from_any_process
|
24
|
-
expect(subject.empty?).to eq(true)
|
25
|
-
end
|
26
|
-
end
|
27
|
-
|
28
|
-
describe 'parsing a function with a missing docstring' do
|
29
|
-
let(:source) { 'function foo{}' }
|
30
|
-
|
31
|
-
it 'should log a warning' do
|
32
|
-
expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process
|
33
|
-
end
|
34
|
-
end
|
35
|
-
|
36
|
-
describe 'parsing a function with a docstring' do
|
37
|
-
let(:source) { <<-SOURCE
|
38
|
-
# A simple foo function.
|
39
|
-
# @param param1 First param.
|
40
|
-
# @param param2 Second param.
|
41
|
-
# @param param3 Third param.
|
42
|
-
# @return [Undef] Returns nothing.
|
43
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
44
|
-
notice 'hello world'
|
45
|
-
undef
|
46
|
-
}
|
47
|
-
SOURCE
|
48
|
-
}
|
49
|
-
|
50
|
-
it 'should register a function object' do
|
51
|
-
expect(subject.size).to eq(1)
|
52
|
-
object = subject.first
|
53
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
54
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::PUPPET))
|
55
|
-
expect(object.name).to eq(:foo)
|
56
|
-
expect(object.signature).to eq('foo(Integer $param1, Any $param2, String $param3 = hi)')
|
57
|
-
expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']])
|
58
|
-
expect(object.docstring).to eq('A simple foo function.')
|
59
|
-
expect(object.docstring.tags.size).to eq(5)
|
60
|
-
tags = object.docstring.tags(:param)
|
61
|
-
expect(tags.size).to eq(3)
|
62
|
-
expect(tags[0].name).to eq('param1')
|
63
|
-
expect(tags[0].text).to eq('First param.')
|
64
|
-
expect(tags[0].types).to eq(['Integer'])
|
65
|
-
expect(tags[1].name).to eq('param2')
|
66
|
-
expect(tags[1].text).to eq('Second param.')
|
67
|
-
expect(tags[1].types).to eq(['Any'])
|
68
|
-
expect(tags[2].name).to eq('param3')
|
69
|
-
expect(tags[2].text).to eq('Third param.')
|
70
|
-
expect(tags[2].types).to eq(['String'])
|
71
|
-
tags = object.docstring.tags(:return)
|
72
|
-
expect(tags.size).to eq(1)
|
73
|
-
expect(tags[0].tag_name).to eq('return')
|
74
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
75
|
-
expect(tags[0].types).to eq(['Undef'])
|
76
|
-
tags = object.docstring.tags(:api)
|
77
|
-
expect(tags.size).to eq(1)
|
78
|
-
expect(tags[0].text).to eq('public')
|
79
|
-
end
|
80
|
-
end
|
81
|
-
|
82
|
-
describe 'parsing a function with a missing parameter' do
|
83
|
-
let(:source) { <<-SOURCE
|
84
|
-
# A simple foo function.
|
85
|
-
# @param param1 First param.
|
86
|
-
# @param param2 Second param.
|
87
|
-
# @param param3 Third param.
|
88
|
-
# @param param4 missing!
|
89
|
-
# @return [Undef] Returns nothing.
|
90
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
91
|
-
notice 'hello world'
|
92
|
-
}
|
93
|
-
SOURCE
|
94
|
-
}
|
95
|
-
|
96
|
-
it 'should output a warning' do
|
97
|
-
expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):7\./).to_stdout_from_any_process
|
98
|
-
end
|
99
|
-
end
|
100
|
-
|
101
|
-
describe 'parsing a function with a missing @param tag' do
|
102
|
-
let(:source) { <<-SOURCE
|
103
|
-
# A simple foo function.
|
104
|
-
# @param param1 First param.
|
105
|
-
# @param param2 Second param.
|
106
|
-
# @return [Undef] Returns nothing.
|
107
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
108
|
-
notice 'hello world'
|
109
|
-
}
|
110
|
-
SOURCE
|
111
|
-
}
|
112
|
-
|
113
|
-
it 'should output a warning' do
|
114
|
-
expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):5\./).to_stdout_from_any_process
|
115
|
-
end
|
116
|
-
end
|
117
|
-
|
118
|
-
describe 'parsing a function with a typed parameter that also has a @param tag type which matches' do
|
119
|
-
let(:source) { <<-SOURCE
|
120
|
-
# A simple foo function.
|
121
|
-
# @param [Integer] param1 First param.
|
122
|
-
# @param param2 Second param.
|
123
|
-
# @param param3 Third param.
|
124
|
-
# @return [Undef] Returns nothing.
|
125
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
126
|
-
notice 'hello world'
|
127
|
-
}
|
128
|
-
SOURCE
|
129
|
-
}
|
130
|
-
|
131
|
-
it 'should respect the type that was documented' do
|
132
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
133
|
-
expect(subject.size).to eq(1)
|
134
|
-
tags = subject.first.tags(:param)
|
135
|
-
expect(tags.size).to eq(3)
|
136
|
-
expect(tags[0].types).to eq(['Integer'])
|
137
|
-
end
|
138
|
-
end
|
139
|
-
|
140
|
-
describe 'parsing a function with a typed parameter that also has a @param tag type which does not match' do
|
141
|
-
let(:source) { <<-SOURCE
|
142
|
-
# A simple foo function.
|
143
|
-
# @param [Boolean] param1 First param.
|
144
|
-
# @param param2 Second param.
|
145
|
-
# @param param3 Third param.
|
146
|
-
# @return [Undef] Returns nothing.
|
147
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
148
|
-
notice 'hello world'
|
149
|
-
}
|
150
|
-
SOURCE
|
151
|
-
}
|
152
|
-
|
153
|
-
it 'should output a warning' do
|
154
|
-
expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):6: ignoring in favor of parameter type information./).to_stdout_from_any_process
|
155
|
-
end
|
156
|
-
end
|
157
|
-
|
158
|
-
describe 'parsing a function with a untyped parameter that also has a @param tag type' do
|
159
|
-
let(:source) { <<-SOURCE
|
160
|
-
# A simple foo function.
|
161
|
-
# @param param1 First param.
|
162
|
-
# @param [Boolean] param2 Second param.
|
163
|
-
# @param param3 Third param.
|
164
|
-
# @return [Undef] Returns nothing.
|
165
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
166
|
-
notice 'hello world'
|
167
|
-
}
|
168
|
-
SOURCE
|
169
|
-
}
|
170
|
-
|
171
|
-
it 'should respect the type that was documented' do
|
172
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
173
|
-
expect(subject.size).to eq(1)
|
174
|
-
tags = subject.first.tags(:param)
|
175
|
-
expect(tags.size).to eq(3)
|
176
|
-
expect(tags[1].types).to eq(['Boolean'])
|
177
|
-
end
|
178
|
-
end
|
179
|
-
|
180
|
-
describe 'parsing a function with a missing @return tag' do
|
181
|
-
let(:source) { <<-SOURCE
|
182
|
-
# A simple foo function.
|
183
|
-
# @param param1 First param.
|
184
|
-
# @param param2 Second param.
|
185
|
-
# @param param3 Third param.
|
186
|
-
function foo(Integer $param1, $param2, String $param3 = hi) {
|
187
|
-
notice 'hello world'
|
188
|
-
}
|
189
|
-
SOURCE
|
190
|
-
}
|
191
|
-
|
192
|
-
it 'should output a warning' do
|
193
|
-
expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):5\./).to_stdout_from_any_process
|
194
|
-
end
|
195
|
-
end
|
196
|
-
|
197
|
-
describe 'parsing a function with a missing @return tag and return type specified in the function definition', if: TEST_FUNCTION_RETURN_TYPE do
|
198
|
-
let(:source) { <<-SOURCE
|
199
|
-
# A simple foo function.
|
200
|
-
function foo() >> String {
|
201
|
-
notice 'hello world'
|
202
|
-
}
|
203
|
-
SOURCE
|
204
|
-
}
|
205
|
-
|
206
|
-
it 'should register a function object with the correct return type' do
|
207
|
-
expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
|
208
|
-
expect(subject.size).to eq(1)
|
209
|
-
object = subject.first
|
210
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
211
|
-
tags = object.docstring.tags(:return)
|
212
|
-
expect(tags.size).to eq(1)
|
213
|
-
expect(tags[0].tag_name).to eq('return')
|
214
|
-
expect(tags[0].text).to eq('')
|
215
|
-
expect(tags[0].types).to eq(['String'])
|
216
|
-
end
|
217
|
-
end
|
218
|
-
|
219
|
-
describe 'parsing a function with a non-conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
|
220
|
-
let(:source) { <<-SOURCE
|
221
|
-
# A simple foo function
|
222
|
-
# @return [String] Hi there
|
223
|
-
function foo() >> String {
|
224
|
-
notice 'hi there'
|
225
|
-
}
|
226
|
-
SOURCE
|
227
|
-
}
|
228
|
-
|
229
|
-
it 'should not output a warning if return types match' do
|
230
|
-
expect{ subject }.not_to output(/Documented return type does not match return type in function definition/).to_stdout_from_any_process
|
231
|
-
end
|
232
|
-
end
|
233
|
-
|
234
|
-
describe 'parsing a function with a conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
|
235
|
-
let(:source) { <<-SOURCE
|
236
|
-
# A simple foo function.
|
237
|
-
# @return [Integer] this is a lie.
|
238
|
-
function foo() >> Struct[{'a' => Integer[1, 10]}] {
|
239
|
-
notice 'hello world'
|
240
|
-
}
|
241
|
-
SOURCE
|
242
|
-
}
|
243
|
-
|
244
|
-
it 'should prefer the return type from the function definition' do
|
245
|
-
expect{ subject }.to output(/\[warn\]: Documented return type does not match return type in function definition near \(stdin\):3\./).to_stdout_from_any_process
|
246
|
-
expect(subject.size).to eq(1)
|
247
|
-
object = subject.first
|
248
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
249
|
-
tags = object.docstring.tags(:return)
|
250
|
-
expect(tags.size).to eq(1)
|
251
|
-
expect(tags[0].tag_name).to eq('return')
|
252
|
-
expect(tags[0].text).to eq('this is a lie.')
|
253
|
-
expect(tags[0].types).to eq(["Struct[{'a' => Integer[1, 10]}]"])
|
254
|
-
end
|
255
|
-
end
|
256
|
-
|
257
|
-
describe 'parsing a function without a return tag or return type in the function definition' do
|
258
|
-
let(:source) { <<-SOURCE
|
259
|
-
# A simple foo function.
|
260
|
-
function foo() {
|
261
|
-
notice 'hello world'
|
262
|
-
}
|
263
|
-
SOURCE
|
264
|
-
}
|
265
|
-
|
266
|
-
it 'should add a return tag with a default type value of Any' do
|
267
|
-
expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
|
268
|
-
expect(subject.size).to eq(1)
|
269
|
-
object = subject.first
|
270
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
271
|
-
tags = object.docstring.tags(:return)
|
272
|
-
expect(tags.size).to eq(1)
|
273
|
-
expect(tags[0].tag_name).to eq('return')
|
274
|
-
expect(tags[0].text).to eq('')
|
275
|
-
expect(tags[0].types).to eq(['Any'])
|
276
|
-
end
|
277
|
-
end
|
278
|
-
|
279
|
-
describe 'parsing a function with a summary' do
|
280
|
-
context 'when the summary has fewer than 140 characters' do
|
281
|
-
let(:source) { <<-SOURCE
|
282
|
-
# A simple foo function.
|
283
|
-
# @summary A short summary.
|
284
|
-
# @return [String] foo
|
285
|
-
function foo() {
|
286
|
-
notice 'hello world'
|
287
|
-
}
|
288
|
-
SOURCE
|
289
|
-
}
|
290
|
-
|
291
|
-
it 'should parse the summary' do
|
292
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
293
|
-
expect(subject.size).to eq(1)
|
294
|
-
summary = subject.first.tags(:summary)
|
295
|
-
expect(summary.first.text).to eq('A short summary.')
|
296
|
-
end
|
297
|
-
end
|
298
|
-
|
299
|
-
context 'when the summary has more than 140 characters' do
|
300
|
-
let(:source) { <<-SOURCE
|
301
|
-
# A simple foo function.
|
302
|
-
# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
|
303
|
-
function foo() {
|
304
|
-
notice 'hello world'
|
305
|
-
}
|
306
|
-
|
307
|
-
SOURCE
|
308
|
-
}
|
309
|
-
|
310
|
-
it 'should log a warning' do
|
311
|
-
expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
|
312
|
-
end
|
313
|
-
end
|
314
|
-
end
|
315
|
-
end
|