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,309 +0,0 @@
|
|
1
|
-
require 'spec_helper'
|
2
|
-
require 'puppet-strings/yard'
|
3
|
-
|
4
|
-
describe PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler, if: TEST_PUPPET_DATATYPES do
|
5
|
-
subject {
|
6
|
-
YARD::Parser::SourceParser.parse_string(source, :ruby)
|
7
|
-
YARD::Registry.all(:puppet_data_type)
|
8
|
-
}
|
9
|
-
|
10
|
-
before(:each) do
|
11
|
-
# Tests may suppress logging to make it easier to read results,
|
12
|
-
# so remember the logging object prior to running the test
|
13
|
-
@original_yard_logging_object = YARD::Logger.instance.io
|
14
|
-
end
|
15
|
-
|
16
|
-
after(:each) do
|
17
|
-
# Restore the original logging IO object
|
18
|
-
YARD::Logger.instance.io = @original_yard_logging_object
|
19
|
-
end
|
20
|
-
|
21
|
-
def suppress_yard_logging
|
22
|
-
YARD::Logger.instance.io = nil
|
23
|
-
end
|
24
|
-
|
25
|
-
describe 'parsing source without a data type definition' do
|
26
|
-
let(:source) { 'puts "hi"' }
|
27
|
-
|
28
|
-
it 'no data types should be in the registry' do
|
29
|
-
expect(subject.empty?).to eq(true)
|
30
|
-
end
|
31
|
-
end
|
32
|
-
|
33
|
-
describe 'parsing an empty data type definition' do
|
34
|
-
let(:source) { <<-SOURCE
|
35
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
36
|
-
end
|
37
|
-
SOURCE
|
38
|
-
}
|
39
|
-
|
40
|
-
it 'should register a data type object with no param tags' do
|
41
|
-
expect(subject.size).to eq(1)
|
42
|
-
object = subject.first
|
43
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
44
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
|
45
|
-
expect(object.name).to eq(:RubyDataType)
|
46
|
-
expect(object.docstring).to eq('')
|
47
|
-
expect(object.docstring.tags.size).to eq(1)
|
48
|
-
tags = object.docstring.tags(:api)
|
49
|
-
expect(tags.size).to eq(1)
|
50
|
-
expect(tags[0].text).to eq('public')
|
51
|
-
|
52
|
-
expect(object.parameters.size).to eq(0)
|
53
|
-
end
|
54
|
-
end
|
55
|
-
|
56
|
-
describe 'parsing a data type definition with missing param tags' do
|
57
|
-
let(:source) { <<-SOURCE
|
58
|
-
# An example Puppet Data Type in Ruby.
|
59
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
60
|
-
interface <<-PUPPET
|
61
|
-
attributes => {
|
62
|
-
msg => String[1],
|
63
|
-
}
|
64
|
-
PUPPET
|
65
|
-
end
|
66
|
-
SOURCE
|
67
|
-
}
|
68
|
-
|
69
|
-
it 'should output a warning' do
|
70
|
-
expect{ subject }.to output(/\[warn\]: Missing @param tag for attribute 'msg' near \(stdin\):2/).to_stdout_from_any_process
|
71
|
-
end
|
72
|
-
|
73
|
-
it 'should register a data type object with all param tags' do
|
74
|
-
suppress_yard_logging
|
75
|
-
|
76
|
-
expect(subject.size).to eq(1)
|
77
|
-
object = subject.first
|
78
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
79
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
|
80
|
-
expect(object.name).to eq(:RubyDataType)
|
81
|
-
expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
|
82
|
-
expect(object.docstring.tags.size).to eq(2)
|
83
|
-
tags = object.docstring.tags(:api)
|
84
|
-
expect(tags.size).to eq(1)
|
85
|
-
expect(tags[0].text).to eq('public')
|
86
|
-
|
87
|
-
# Check that the param tags are created
|
88
|
-
tags = object.docstring.tags(:param)
|
89
|
-
expect(tags.size).to eq(1)
|
90
|
-
expect(tags[0].name).to eq('msg')
|
91
|
-
expect(tags[0].text).to eq('')
|
92
|
-
expect(tags[0].types).to eq(['String[1]'])
|
93
|
-
|
94
|
-
# Check for default values for parameters
|
95
|
-
expect(object.parameters.size).to eq(1)
|
96
|
-
expect(object.parameters[0]).to eq(['msg', nil])
|
97
|
-
end
|
98
|
-
end
|
99
|
-
|
100
|
-
describe 'parsing a data type definition with extra param tags' do
|
101
|
-
let(:source) { <<-SOURCE
|
102
|
-
# An example Puppet Data Type in Ruby.
|
103
|
-
# @param msg A message parameter.
|
104
|
-
# @param arg1 Optional String parameter. Defaults to 'param'.
|
105
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
106
|
-
interface <<-PUPPET
|
107
|
-
attributes => {
|
108
|
-
msg => Numeric,
|
109
|
-
}
|
110
|
-
PUPPET
|
111
|
-
end
|
112
|
-
SOURCE
|
113
|
-
}
|
114
|
-
|
115
|
-
it 'should output a warning' do
|
116
|
-
expect{ subject }.to output(/\[warn\]: The @param tag for 'arg1' has no matching attribute near \(stdin\):4/).to_stdout_from_any_process
|
117
|
-
end
|
118
|
-
|
119
|
-
it 'should register a data type object with extra param tags removed' do
|
120
|
-
suppress_yard_logging
|
121
|
-
|
122
|
-
expect(subject.size).to eq(1)
|
123
|
-
object = subject.first
|
124
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
125
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
|
126
|
-
expect(object.name).to eq(:RubyDataType)
|
127
|
-
expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
|
128
|
-
expect(object.docstring.tags.size).to eq(2)
|
129
|
-
tags = object.docstring.tags(:api)
|
130
|
-
expect(tags.size).to eq(1)
|
131
|
-
expect(tags[0].text).to eq('public')
|
132
|
-
|
133
|
-
# Check that the param tags are removed
|
134
|
-
tags = object.docstring.tags(:param)
|
135
|
-
expect(tags.size).to eq(1)
|
136
|
-
expect(tags[0].name).to eq('msg')
|
137
|
-
expect(tags[0].text).to eq('A message parameter.')
|
138
|
-
expect(tags[0].types).to eq(['Numeric'])
|
139
|
-
|
140
|
-
# Check that only the actual attributes appear
|
141
|
-
expect(object.parameters.size).to eq(1)
|
142
|
-
expect(object.parameters[0]).to eq(['msg', nil])
|
143
|
-
end
|
144
|
-
end
|
145
|
-
|
146
|
-
describe 'parsing a valid data type definition' do
|
147
|
-
let(:source) { <<-SOURCE
|
148
|
-
# An example Puppet Data Type in Ruby.
|
149
|
-
#
|
150
|
-
# @param msg A message parameter5.
|
151
|
-
# @param arg1 Optional String parameter5. Defaults to 'param'.
|
152
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
153
|
-
interface <<-PUPPET
|
154
|
-
attributes => {
|
155
|
-
msg => Variant[Numeric, String[1,2]],
|
156
|
-
arg1 => { type => Optional[String[1]], value => "param" }
|
157
|
-
}
|
158
|
-
PUPPET
|
159
|
-
end
|
160
|
-
SOURCE
|
161
|
-
}
|
162
|
-
|
163
|
-
it 'should register a data type object' do
|
164
|
-
expect(subject.size).to eq(1)
|
165
|
-
object = subject.first
|
166
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
167
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
|
168
|
-
expect(object.name).to eq(:RubyDataType)
|
169
|
-
expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
|
170
|
-
expect(object.docstring.tags.size).to eq(3)
|
171
|
-
tags = object.docstring.tags(:api)
|
172
|
-
expect(tags.size).to eq(1)
|
173
|
-
expect(tags[0].text).to eq('public')
|
174
|
-
|
175
|
-
# Check that the param tags are removed
|
176
|
-
tags = object.docstring.tags(:param)
|
177
|
-
expect(tags.size).to eq(2)
|
178
|
-
expect(tags[0].name).to eq('msg')
|
179
|
-
expect(tags[0].text).to eq('A message parameter5.')
|
180
|
-
expect(tags[0].types).to eq(['Variant[Numeric, String[1,2]]'])
|
181
|
-
expect(tags[1].name).to eq('arg1')
|
182
|
-
expect(tags[1].text).to eq('Optional String parameter5. Defaults to \'param\'.')
|
183
|
-
expect(tags[1].types).to eq(['Optional[String[1]]'])
|
184
|
-
|
185
|
-
# Check for default values
|
186
|
-
expect(object.parameters.size).to eq(2)
|
187
|
-
expect(object.parameters[0]).to eq(['msg', nil])
|
188
|
-
expect(object.parameters[1]).to eq(['arg1', 'param'])
|
189
|
-
end
|
190
|
-
end
|
191
|
-
|
192
|
-
testcases = [
|
193
|
-
{ :value => '-1', :expected => -1 },
|
194
|
-
{ :value => '0', :expected => 0 },
|
195
|
-
{ :value => '10', :expected => 10 },
|
196
|
-
{ :value => '0777', :expected => 511 },
|
197
|
-
{ :value => '0xFF', :expected => 255 },
|
198
|
-
{ :value => '0.1', :expected => 0.1 },
|
199
|
-
{ :value => '31.415e-1', :expected => 3.1415 },
|
200
|
-
{ :value => '0.31415e1', :expected => 3.1415 }
|
201
|
-
].each do |testcase|
|
202
|
-
describe "parsing a valid data type definition with numeric default #{testcase[:value]}" do
|
203
|
-
let(:source) { <<-SOURCE
|
204
|
-
# An example Puppet Data Type in Ruby.
|
205
|
-
# @param num1 A numeric parameter
|
206
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
207
|
-
interface <<-PUPPET
|
208
|
-
attributes => {
|
209
|
-
num1 => { type => Numeric, value => #{testcase[:value]} },
|
210
|
-
}
|
211
|
-
PUPPET
|
212
|
-
end
|
213
|
-
SOURCE
|
214
|
-
}
|
215
|
-
|
216
|
-
it 'should register a data type object' do
|
217
|
-
expect(subject.size).to eq(1)
|
218
|
-
object = subject.first
|
219
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
220
|
-
expect(object.parameters.size).to eq(1)
|
221
|
-
expect(object.parameters[0]).to eq(['num1', testcase[:expected]])
|
222
|
-
end
|
223
|
-
end
|
224
|
-
end
|
225
|
-
|
226
|
-
describe 'parsing a invalid data type definition' do
|
227
|
-
let(:source) { <<-SOURCE
|
228
|
-
# The msg attribute is missing a comma.
|
229
|
-
#
|
230
|
-
# @param msg A message parameter5.
|
231
|
-
# @param arg1 Optional String parameter5. Defaults to 'param'.
|
232
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
233
|
-
interface <<-PUPPET
|
234
|
-
attributes => {
|
235
|
-
msg => Variant[Numeric, String[1,2]]
|
236
|
-
arg1 => { type => Optional[String[1]], value => "param" }
|
237
|
-
}
|
238
|
-
PUPPET
|
239
|
-
end
|
240
|
-
SOURCE
|
241
|
-
}
|
242
|
-
|
243
|
-
it 'should register a partial data type object' do
|
244
|
-
expect(subject.size).to eq(1)
|
245
|
-
object = subject.first
|
246
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
|
247
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
|
248
|
-
expect(object.name).to eq(:RubyDataType)
|
249
|
-
expect(object.docstring).to eq('The msg attribute is missing a comma.')
|
250
|
-
# The attributes will be missing therefore only one tag
|
251
|
-
expect(object.docstring.tags.size).to eq(1)
|
252
|
-
tags = object.docstring.tags(:api)
|
253
|
-
expect(tags.size).to eq(1)
|
254
|
-
expect(tags[0].text).to eq('public')
|
255
|
-
|
256
|
-
# Check that the param tags are removed
|
257
|
-
tags = object.docstring.tags(:param)
|
258
|
-
expect(tags.size).to eq(0)
|
259
|
-
|
260
|
-
# Check for default values
|
261
|
-
expect(object.parameters.size).to eq(0)
|
262
|
-
end
|
263
|
-
|
264
|
-
it 'should log a warning' do
|
265
|
-
expect{ subject }.to output(/\[warn\]: Invalid datatype definition at (.+):[0-9]+: Syntax error at 'arg1'/).to_stdout_from_any_process
|
266
|
-
end
|
267
|
-
end
|
268
|
-
|
269
|
-
describe 'parsing a data type with a summary' do
|
270
|
-
context 'when the summary has fewer than 140 characters' do
|
271
|
-
let(:source) { <<-SOURCE
|
272
|
-
# An example Puppet Data Type in Ruby.
|
273
|
-
#
|
274
|
-
# @summary A short summary.
|
275
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
276
|
-
interface <<-PUPPET
|
277
|
-
attributes => { }
|
278
|
-
PUPPET
|
279
|
-
end
|
280
|
-
SOURCE
|
281
|
-
}
|
282
|
-
|
283
|
-
it 'should parse the summary' do
|
284
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
285
|
-
expect(subject.size).to eq(1)
|
286
|
-
summary = subject.first.tags(:summary)
|
287
|
-
expect(summary.first.text).to eq('A short summary.')
|
288
|
-
end
|
289
|
-
end
|
290
|
-
|
291
|
-
context 'when the summary has more than 140 characters' do
|
292
|
-
let(:source) { <<-SOURCE
|
293
|
-
# An example Puppet Data Type in Ruby.
|
294
|
-
#
|
295
|
-
# @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!!
|
296
|
-
Puppet::DataTypes.create_type('RubyDataType') do
|
297
|
-
interface <<-PUPPET
|
298
|
-
attributes => { }
|
299
|
-
PUPPET
|
300
|
-
end
|
301
|
-
SOURCE
|
302
|
-
}
|
303
|
-
|
304
|
-
it 'should log a warning' do
|
305
|
-
expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_data_type 'RubyDataType' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
|
306
|
-
end
|
307
|
-
end
|
308
|
-
end
|
309
|
-
end
|
@@ -1,746 +0,0 @@
|
|
1
|
-
require 'spec_helper'
|
2
|
-
require 'puppet-strings/yard'
|
3
|
-
|
4
|
-
describe PuppetStrings::Yard::Handlers::Ruby::FunctionHandler do
|
5
|
-
subject {
|
6
|
-
YARD::Parser::SourceParser.parse_string(source, :ruby)
|
7
|
-
YARD::Registry.all(:puppet_function)
|
8
|
-
}
|
9
|
-
|
10
|
-
describe 'parsing source without a function definition' do
|
11
|
-
let(:source) { 'puts "hi"' }
|
12
|
-
|
13
|
-
it 'no functions should be in the registry' do
|
14
|
-
expect(subject.empty?).to eq(true)
|
15
|
-
end
|
16
|
-
end
|
17
|
-
|
18
|
-
describe 'parsing 3.x API functions' do
|
19
|
-
describe 'parsing a function with a missing docstring' do
|
20
|
-
let(:source) { <<-SOURCE
|
21
|
-
Puppet::Parser::Functions.newfunction(:foo) do |*args|
|
22
|
-
end
|
23
|
-
SOURCE
|
24
|
-
}
|
25
|
-
|
26
|
-
it 'should log a warning' do
|
27
|
-
expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process
|
28
|
-
end
|
29
|
-
end
|
30
|
-
|
31
|
-
describe 'parsing a function with a doc parameter' do
|
32
|
-
let(:source) { <<-SOURCE
|
33
|
-
Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC
|
34
|
-
An example 3.x function.
|
35
|
-
@param [String] first The first parameter.
|
36
|
-
@param second The second parameter.
|
37
|
-
@return [Undef] Returns nothing.
|
38
|
-
DOC
|
39
|
-
) do |*args|
|
40
|
-
end
|
41
|
-
SOURCE
|
42
|
-
}
|
43
|
-
|
44
|
-
it 'should register a function object' do
|
45
|
-
expect(subject.size).to eq(1)
|
46
|
-
object = subject.first
|
47
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
48
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X))
|
49
|
-
expect(object.name).to eq(:foo)
|
50
|
-
expect(object.signature).to eq('foo(String $first, Any $second)')
|
51
|
-
expect(object.parameters).to eq([['first', nil], ['second', nil]])
|
52
|
-
expect(object.docstring).to eq('An example 3.x function.')
|
53
|
-
expect(object.docstring.tags.size).to eq(4)
|
54
|
-
tags = object.docstring.tags(:param)
|
55
|
-
expect(tags.size).to eq(2)
|
56
|
-
expect(tags[0].name).to eq('first')
|
57
|
-
expect(tags[0].text).to eq('The first parameter.')
|
58
|
-
expect(tags[0].types).to eq(['String'])
|
59
|
-
expect(tags[1].name).to eq('second')
|
60
|
-
expect(tags[1].text).to eq('The second parameter.')
|
61
|
-
expect(tags[1].types).to eq(['Any'])
|
62
|
-
tags = object.docstring.tags(:return)
|
63
|
-
expect(tags.size).to eq(1)
|
64
|
-
expect(tags[0].name).to be_nil
|
65
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
66
|
-
expect(tags[0].types).to eq(['Undef'])
|
67
|
-
tags = object.docstring.tags(:api)
|
68
|
-
expect(tags.size).to eq(1)
|
69
|
-
expect(tags[0].text).to eq('public')
|
70
|
-
end
|
71
|
-
end
|
72
|
-
|
73
|
-
describe 'parsing a function with a doc parameter which has a newline between the namespace and the newfunction call' do
|
74
|
-
let(:source) { <<-SOURCE
|
75
|
-
module Puppet::Parser::Functions
|
76
|
-
newfunction(:foo, doc: <<-DOC
|
77
|
-
An example 3.x function.
|
78
|
-
@param [String] first The first parameter.
|
79
|
-
@param second The second parameter.
|
80
|
-
@return [Undef] Returns nothing.
|
81
|
-
DOC
|
82
|
-
) do |*args|
|
83
|
-
end
|
84
|
-
end
|
85
|
-
SOURCE
|
86
|
-
}
|
87
|
-
|
88
|
-
it 'should register a function object' do
|
89
|
-
expect(subject.size).to eq(1)
|
90
|
-
object = subject.first
|
91
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
92
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X))
|
93
|
-
expect(object.name).to eq(:foo)
|
94
|
-
expect(object.signature).to eq('foo(String $first, Any $second)')
|
95
|
-
expect(object.parameters).to eq([['first', nil], ['second', nil]])
|
96
|
-
expect(object.docstring).to eq('An example 3.x function.')
|
97
|
-
expect(object.docstring.tags.size).to eq(4)
|
98
|
-
tags = object.docstring.tags(:param)
|
99
|
-
expect(tags.size).to eq(2)
|
100
|
-
expect(tags[0].name).to eq('first')
|
101
|
-
expect(tags[0].text).to eq('The first parameter.')
|
102
|
-
expect(tags[0].types).to eq(['String'])
|
103
|
-
expect(tags[1].name).to eq('second')
|
104
|
-
expect(tags[1].text).to eq('The second parameter.')
|
105
|
-
expect(tags[1].types).to eq(['Any'])
|
106
|
-
tags = object.docstring.tags(:return)
|
107
|
-
expect(tags.size).to eq(1)
|
108
|
-
expect(tags[0].name).to be_nil
|
109
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
110
|
-
expect(tags[0].types).to eq(['Undef'])
|
111
|
-
tags = object.docstring.tags(:api)
|
112
|
-
expect(tags.size).to eq(1)
|
113
|
-
expect(tags[0].text).to eq('public')
|
114
|
-
end
|
115
|
-
end
|
116
|
-
|
117
|
-
describe 'parsing a function with a missing @return tag' do
|
118
|
-
let(:source) { <<-SOURCE
|
119
|
-
Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC) do |*args|
|
120
|
-
An example 3.x function.
|
121
|
-
@param [String] first The first parameter.
|
122
|
-
@param second The second parameter.
|
123
|
-
DOC
|
124
|
-
end
|
125
|
-
SOURCE
|
126
|
-
}
|
127
|
-
|
128
|
-
it 'should log a warning' do
|
129
|
-
expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):1/).to_stdout_from_any_process
|
130
|
-
end
|
131
|
-
end
|
132
|
-
end
|
133
|
-
|
134
|
-
describe 'parsing 4.x API functions' do
|
135
|
-
describe 'parsing a function with a missing docstring' do
|
136
|
-
let(:source) { <<-SOURCE
|
137
|
-
Puppet::Functions.create_function(:foo) do
|
138
|
-
end
|
139
|
-
SOURCE
|
140
|
-
}
|
141
|
-
|
142
|
-
it 'should log a warning' do
|
143
|
-
expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process
|
144
|
-
end
|
145
|
-
end
|
146
|
-
|
147
|
-
describe 'parsing a function with a simple docstring' do
|
148
|
-
let(:source) { <<-SOURCE
|
149
|
-
# An example 4.x function.
|
150
|
-
Puppet::Functions.create_function(:foo) do
|
151
|
-
end
|
152
|
-
SOURCE
|
153
|
-
}
|
154
|
-
|
155
|
-
it 'should register a function object' do
|
156
|
-
expect(subject.size).to eq(1)
|
157
|
-
object = subject.first
|
158
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
159
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
160
|
-
expect(object.name).to eq(:foo)
|
161
|
-
expect(object.signature).to eq('foo()')
|
162
|
-
expect(object.parameters).to eq([])
|
163
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
164
|
-
expect(object.docstring.tags.size).to eq(1)
|
165
|
-
tags = object.docstring.tags(:api)
|
166
|
-
expect(tags.size).to eq(1)
|
167
|
-
expect(tags[0].text).to eq('public')
|
168
|
-
end
|
169
|
-
end
|
170
|
-
|
171
|
-
describe 'parsing a function without any dispatches' do
|
172
|
-
let(:source) { <<-SOURCE
|
173
|
-
# An example 4.x function.
|
174
|
-
Puppet::Functions.create_function(:foo) do
|
175
|
-
# @param [Integer] param1 The first parameter.
|
176
|
-
# @param param2 The second parameter.
|
177
|
-
# @param [String] param3 The third parameter.
|
178
|
-
# @return [Undef] Returns nothing.
|
179
|
-
def foo(param1, param2, param3 = nil)
|
180
|
-
end
|
181
|
-
end
|
182
|
-
SOURCE
|
183
|
-
}
|
184
|
-
|
185
|
-
it 'should register a function object' do
|
186
|
-
expect(subject.size).to eq(1)
|
187
|
-
object = subject.first
|
188
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
189
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
190
|
-
expect(object.name).to eq(:foo)
|
191
|
-
expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[String] $param3 = undef)')
|
192
|
-
expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'undef']])
|
193
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
194
|
-
expect(object.docstring.tags.size).to eq(5)
|
195
|
-
tags = object.docstring.tags(:param)
|
196
|
-
expect(tags.size).to eq(3)
|
197
|
-
expect(tags[0].name).to eq('param1')
|
198
|
-
expect(tags[0].text).to eq('The first parameter.')
|
199
|
-
expect(tags[0].types).to eq(['Integer'])
|
200
|
-
expect(tags[1].name).to eq('param2')
|
201
|
-
expect(tags[1].text).to eq('The second parameter.')
|
202
|
-
expect(tags[1].types).to eq(['Any'])
|
203
|
-
expect(tags[2].name).to eq('param3')
|
204
|
-
expect(tags[2].text).to eq('The third parameter.')
|
205
|
-
expect(tags[2].types).to eq(['Optional[String]'])
|
206
|
-
tags = object.docstring.tags(:return)
|
207
|
-
expect(tags.size).to eq(1)
|
208
|
-
expect(tags[0].name).to be_nil
|
209
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
210
|
-
expect(tags[0].types).to eq(['Undef'])
|
211
|
-
tags = object.docstring.tags(:api)
|
212
|
-
expect(tags.size).to eq(1)
|
213
|
-
expect(tags[0].text).to eq('public')
|
214
|
-
end
|
215
|
-
end
|
216
|
-
|
217
|
-
describe 'parsing a function with a single dispatch' do
|
218
|
-
let(:source) { <<-SOURCE
|
219
|
-
# An example 4.x function.
|
220
|
-
Puppet::Functions.create_function(:foo) do
|
221
|
-
# @param param1 The first parameter.
|
222
|
-
# @param param2 The second parameter.
|
223
|
-
# @param param3 The third parameter.
|
224
|
-
# @return [Undef] Returns nothing.
|
225
|
-
dispatch :foo do
|
226
|
-
param 'Integer', :param1
|
227
|
-
param 'Any', :param2
|
228
|
-
optional_param 'Array[String]', :param3
|
229
|
-
end
|
230
|
-
|
231
|
-
def foo(param1, param2, param3 = nil)
|
232
|
-
end
|
233
|
-
end
|
234
|
-
SOURCE
|
235
|
-
}
|
236
|
-
|
237
|
-
it 'should register a function object without any overload tags' do
|
238
|
-
expect(subject.size).to eq(1)
|
239
|
-
object = subject.first
|
240
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
241
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
242
|
-
expect(object.name).to eq(:foo)
|
243
|
-
expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)')
|
244
|
-
expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil]])
|
245
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
246
|
-
expect(object.docstring.tags(:overload).empty?).to be_truthy
|
247
|
-
expect(object.docstring.tags.size).to eq(5)
|
248
|
-
tags = object.docstring.tags(:param)
|
249
|
-
expect(tags.size).to eq(3)
|
250
|
-
expect(tags[0].name).to eq('param1')
|
251
|
-
expect(tags[0].text).to eq('The first parameter.')
|
252
|
-
expect(tags[0].types).to eq(['Integer'])
|
253
|
-
expect(tags[1].name).to eq('param2')
|
254
|
-
expect(tags[1].text).to eq('The second parameter.')
|
255
|
-
expect(tags[1].types).to eq(['Any'])
|
256
|
-
expect(tags[2].name).to eq('param3')
|
257
|
-
expect(tags[2].text).to eq('The third parameter.')
|
258
|
-
expect(tags[2].types).to eq(['Optional[Array[String]]'])
|
259
|
-
tags = object.docstring.tags(:return)
|
260
|
-
expect(tags.size).to eq(1)
|
261
|
-
expect(tags[0].name).to be_nil
|
262
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
263
|
-
expect(tags[0].types).to eq(['Undef'])
|
264
|
-
tags = object.docstring.tags(:api)
|
265
|
-
expect(tags.size).to eq(1)
|
266
|
-
expect(tags[0].text).to eq('public')
|
267
|
-
end
|
268
|
-
end
|
269
|
-
|
270
|
-
describe 'parsing a function using only return_type' do
|
271
|
-
let(:source) { <<-SOURCE
|
272
|
-
# An example 4.x function.
|
273
|
-
Puppet::Functions.create_function(:foo) do
|
274
|
-
# @param param1 The first parameter.
|
275
|
-
# @param param2 The second parameter.
|
276
|
-
# @param param3 The third parameter.
|
277
|
-
dispatch :foo do
|
278
|
-
param 'Integer', :param1
|
279
|
-
param 'Any', :param2
|
280
|
-
optional_param 'Array[String]', :param3
|
281
|
-
return_type 'String'
|
282
|
-
end
|
283
|
-
|
284
|
-
def foo(param1, param2, param3 = nil)
|
285
|
-
"Bar"
|
286
|
-
end
|
287
|
-
end
|
288
|
-
SOURCE
|
289
|
-
}
|
290
|
-
|
291
|
-
it 'does not throw an error with no @return' do
|
292
|
-
expect { subject }.not_to raise_error
|
293
|
-
end
|
294
|
-
|
295
|
-
it 'contains a return data type' do
|
296
|
-
tags = subject.first.docstring.tags(:return)
|
297
|
-
expect(tags.size).to eq(1)
|
298
|
-
expect(tags[0].name).to be_nil
|
299
|
-
expect(tags[0].types).to eq(['String'])
|
300
|
-
end
|
301
|
-
end
|
302
|
-
|
303
|
-
describe 'parsing a function with various dispatch parameters.' do
|
304
|
-
let(:source) { <<-SOURCE
|
305
|
-
# An example 4.x function.
|
306
|
-
Puppet::Functions.create_function(:foo) do
|
307
|
-
# @param param1 The first parameter.
|
308
|
-
# @param param2 The second parameter.
|
309
|
-
# @param param3 The third parameter.
|
310
|
-
# @param param4 The fourth parameter.
|
311
|
-
# @return [Undef] Returns nothing.
|
312
|
-
dispatch :foo do
|
313
|
-
param 'String', :param1
|
314
|
-
required_param 'Integer', :param2
|
315
|
-
optional_param 'Array', :param3
|
316
|
-
repeated_param 'String', :param4
|
317
|
-
end
|
318
|
-
end
|
319
|
-
SOURCE
|
320
|
-
}
|
321
|
-
|
322
|
-
it 'should register a function object with the expected parameters' do
|
323
|
-
expect(subject.size).to eq(1)
|
324
|
-
object = subject.first
|
325
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
326
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
327
|
-
expect(object.name).to eq(:foo)
|
328
|
-
expect(object.signature).to eq('foo(String $param1, Integer $param2, Optional[Array] $param3, String *$param4)')
|
329
|
-
expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil], ['*param4', nil]])
|
330
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
331
|
-
expect(object.docstring.tags(:overload).empty?).to be_truthy
|
332
|
-
expect(object.docstring.tags.size).to eq(6)
|
333
|
-
tags = object.docstring.tags(:param)
|
334
|
-
expect(tags.size).to eq(4)
|
335
|
-
expect(tags[0].name).to eq('param1')
|
336
|
-
expect(tags[0].text).to eq('The first parameter.')
|
337
|
-
expect(tags[0].types).to eq(['String'])
|
338
|
-
expect(tags[1].name).to eq('param2')
|
339
|
-
expect(tags[1].text).to eq('The second parameter.')
|
340
|
-
expect(tags[1].types).to eq(['Integer'])
|
341
|
-
expect(tags[2].name).to eq('param3')
|
342
|
-
expect(tags[2].text).to eq('The third parameter.')
|
343
|
-
expect(tags[2].types).to eq(['Optional[Array]'])
|
344
|
-
expect(tags[3].name).to eq('*param4')
|
345
|
-
expect(tags[3].text).to eq('The fourth parameter.')
|
346
|
-
expect(tags[3].types).to eq(['String'])
|
347
|
-
tags = object.docstring.tags(:return)
|
348
|
-
expect(tags.size).to eq(1)
|
349
|
-
expect(tags[0].name).to be_nil
|
350
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
351
|
-
expect(tags[0].types).to eq(['Undef'])
|
352
|
-
tags = object.docstring.tags(:api)
|
353
|
-
expect(tags.size).to eq(1)
|
354
|
-
expect(tags[0].text).to eq('public')
|
355
|
-
end
|
356
|
-
end
|
357
|
-
|
358
|
-
describe 'parsing a function with an optional repeated param.' do
|
359
|
-
let(:source) { <<-SOURCE
|
360
|
-
# An example 4.x function.
|
361
|
-
Puppet::Functions.create_function(:foo) do
|
362
|
-
# @param param The first parameter.
|
363
|
-
# @return [Undef] Returns nothing.
|
364
|
-
dispatch :foo do
|
365
|
-
optional_repeated_param 'String', :param
|
366
|
-
end
|
367
|
-
end
|
368
|
-
SOURCE
|
369
|
-
}
|
370
|
-
|
371
|
-
it 'should register a function object with the expected parameters' do
|
372
|
-
expect(subject.size).to eq(1)
|
373
|
-
object = subject.first
|
374
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
375
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
376
|
-
expect(object.name).to eq(:foo)
|
377
|
-
expect(object.signature).to eq('foo(Optional[String] *$param)')
|
378
|
-
expect(object.parameters).to eq([['*param', nil]])
|
379
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
380
|
-
expect(object.docstring.tags(:overload).empty?).to be_truthy
|
381
|
-
expect(object.docstring.tags.size).to eq(3)
|
382
|
-
tags = object.docstring.tags(:param)
|
383
|
-
expect(tags.size).to eq(1)
|
384
|
-
expect(tags[0].name).to eq('*param')
|
385
|
-
expect(tags[0].text).to eq('The first parameter.')
|
386
|
-
expect(tags[0].types).to eq(['Optional[String]'])
|
387
|
-
tags = object.docstring.tags(:return)
|
388
|
-
expect(tags.size).to eq(1)
|
389
|
-
expect(tags[0].name).to be_nil
|
390
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
391
|
-
expect(tags[0].types).to eq(['Undef'])
|
392
|
-
tags = object.docstring.tags(:api)
|
393
|
-
expect(tags.size).to eq(1)
|
394
|
-
expect(tags[0].text).to eq('public')
|
395
|
-
end
|
396
|
-
end
|
397
|
-
|
398
|
-
describe 'parsing a function with a block param with one parameter' do
|
399
|
-
let(:source) { <<-SOURCE
|
400
|
-
# An example 4.x function.
|
401
|
-
Puppet::Functions.create_function(:foo) do
|
402
|
-
# @param a_block The block parameter.
|
403
|
-
# @return [Undef] Returns nothing.
|
404
|
-
dispatch :foo do
|
405
|
-
block_param :a_block
|
406
|
-
end
|
407
|
-
end
|
408
|
-
SOURCE
|
409
|
-
}
|
410
|
-
|
411
|
-
it 'should register a function object with the expected parameters' do
|
412
|
-
expect(subject.size).to eq(1)
|
413
|
-
object = subject.first
|
414
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
415
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
416
|
-
expect(object.name).to eq(:foo)
|
417
|
-
expect(object.signature).to eq('foo(Callable &$a_block)')
|
418
|
-
expect(object.parameters).to eq([['&a_block', nil]])
|
419
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
420
|
-
expect(object.docstring.tags(:overload).empty?).to be_truthy
|
421
|
-
expect(object.docstring.tags.size).to eq(3)
|
422
|
-
tags = object.docstring.tags(:param)
|
423
|
-
expect(tags.size).to eq(1)
|
424
|
-
expect(tags[0].name).to eq('&a_block')
|
425
|
-
expect(tags[0].text).to eq('The block parameter.')
|
426
|
-
expect(tags[0].types).to eq(['Callable'])
|
427
|
-
tags = object.docstring.tags(:return)
|
428
|
-
expect(tags.size).to eq(1)
|
429
|
-
expect(tags[0].name).to be_nil
|
430
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
431
|
-
expect(tags[0].types).to eq(['Undef'])
|
432
|
-
tags = object.docstring.tags(:api)
|
433
|
-
expect(tags.size).to eq(1)
|
434
|
-
expect(tags[0].text).to eq('public')
|
435
|
-
end
|
436
|
-
end
|
437
|
-
|
438
|
-
describe 'parsing a function with a block param with two parameter' do
|
439
|
-
let(:source) { <<-SOURCE
|
440
|
-
# An example 4.x function.
|
441
|
-
Puppet::Functions.create_function(:foo) do
|
442
|
-
# @param a_block The block parameter.
|
443
|
-
# @return [Undef] Returns nothing.
|
444
|
-
dispatch :foo do
|
445
|
-
optional_block_param 'Callable[String]', :a_block
|
446
|
-
end
|
447
|
-
end
|
448
|
-
SOURCE
|
449
|
-
}
|
450
|
-
|
451
|
-
it 'should register a function object with the expected parameters' do
|
452
|
-
expect(subject.size).to eq(1)
|
453
|
-
object = subject.first
|
454
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
455
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
456
|
-
expect(object.name).to eq(:foo)
|
457
|
-
expect(object.signature).to eq('foo(Optional[Callable[String]] &$a_block)')
|
458
|
-
expect(object.parameters).to eq([['&a_block', nil]])
|
459
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
460
|
-
expect(object.docstring.tags(:overload).empty?).to be_truthy
|
461
|
-
expect(object.docstring.tags.size).to eq(3)
|
462
|
-
tags = object.docstring.tags(:param)
|
463
|
-
expect(tags.size).to eq(1)
|
464
|
-
expect(tags[0].name).to eq('&a_block')
|
465
|
-
expect(tags[0].text).to eq('The block parameter.')
|
466
|
-
expect(tags[0].types).to eq(['Optional[Callable[String]]'])
|
467
|
-
tags = object.docstring.tags(:return)
|
468
|
-
expect(tags.size).to eq(1)
|
469
|
-
expect(tags[0].name).to be_nil
|
470
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
471
|
-
expect(tags[0].types).to eq(['Undef'])
|
472
|
-
tags = object.docstring.tags(:api)
|
473
|
-
expect(tags.size).to eq(1)
|
474
|
-
expect(tags[0].text).to eq('public')
|
475
|
-
end
|
476
|
-
end
|
477
|
-
end
|
478
|
-
|
479
|
-
describe 'parsing a function with a multiple dispatches' do
|
480
|
-
let(:source) { <<-SOURCE
|
481
|
-
# An example 4.x function.
|
482
|
-
Puppet::Functions.create_function(:foo) do
|
483
|
-
# The first overload.
|
484
|
-
# @param param1 The first parameter.
|
485
|
-
# @param param2 The second parameter.
|
486
|
-
# @param param3 The third parameter.
|
487
|
-
# @return [Undef] Returns nothing.
|
488
|
-
dispatch :foo do
|
489
|
-
param 'Integer', :param1
|
490
|
-
param 'Any', :param2
|
491
|
-
optional_param 'Array[String]', :param3
|
492
|
-
end
|
493
|
-
|
494
|
-
# The second overload.
|
495
|
-
# @param param The first parameter.
|
496
|
-
# @param block The block parameter.
|
497
|
-
# @return [String] Returns a string.
|
498
|
-
dispatch :other do
|
499
|
-
param 'Boolean', :param
|
500
|
-
block_param
|
501
|
-
end
|
502
|
-
|
503
|
-
def foo(param1, param2, param3 = nil)
|
504
|
-
end
|
505
|
-
|
506
|
-
def other(b)
|
507
|
-
'lol'
|
508
|
-
end
|
509
|
-
end
|
510
|
-
SOURCE
|
511
|
-
}
|
512
|
-
|
513
|
-
it 'should register a function object with overload tags' do
|
514
|
-
expect(subject.size).to eq(1)
|
515
|
-
object = subject.first
|
516
|
-
expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
|
517
|
-
expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
|
518
|
-
expect(object.name).to eq(:foo)
|
519
|
-
expect(object.signature).to eq('')
|
520
|
-
expect(object.parameters).to eq([])
|
521
|
-
expect(object.docstring).to eq('An example 4.x function.')
|
522
|
-
expect(object.docstring.tags(:param).empty?).to be_truthy
|
523
|
-
expect(object.docstring.tags(:return).empty?).to be_truthy
|
524
|
-
expect(object.docstring.tags.size).to eq(3)
|
525
|
-
overloads = object.docstring.tags(:overload)
|
526
|
-
expect(overloads.size).to eq(2)
|
527
|
-
expect(overloads[0]).to be_a(PuppetStrings::Yard::Tags::OverloadTag)
|
528
|
-
expect(overloads[0].docstring).to eq('The first overload.')
|
529
|
-
expect(overloads[0].signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)')
|
530
|
-
expect(overloads[0].tags.size).to eq(4)
|
531
|
-
tags = overloads[0].tags(:param)
|
532
|
-
expect(tags.size).to eq(3)
|
533
|
-
expect(tags[0].name).to eq('param1')
|
534
|
-
expect(tags[0].text).to eq('The first parameter.')
|
535
|
-
expect(tags[0].types).to eq(['Integer'])
|
536
|
-
expect(tags[1].name).to eq('param2')
|
537
|
-
expect(tags[1].text).to eq('The second parameter.')
|
538
|
-
expect(tags[1].types).to eq(['Any'])
|
539
|
-
expect(tags[2].name).to eq('param3')
|
540
|
-
expect(tags[2].text).to eq('The third parameter.')
|
541
|
-
expect(tags[2].types).to eq(['Optional[Array[String]]'])
|
542
|
-
tags = overloads[0].tags(:return)
|
543
|
-
expect(tags.size).to eq(1)
|
544
|
-
expect(tags[0].name).to be_nil
|
545
|
-
expect(tags[0].text).to eq('Returns nothing.')
|
546
|
-
expect(tags[0].types).to eq(['Undef'])
|
547
|
-
expect(overloads[1]).to be_a(PuppetStrings::Yard::Tags::OverloadTag)
|
548
|
-
expect(overloads[1].docstring).to eq('The second overload.')
|
549
|
-
expect(overloads[1].signature).to eq('foo(Boolean $param, Callable &$block)')
|
550
|
-
expect(overloads[1].tags.size).to eq(3)
|
551
|
-
tags = overloads[1].tags(:param)
|
552
|
-
expect(tags.size).to eq(2)
|
553
|
-
expect(tags[0].name).to eq('param')
|
554
|
-
expect(tags[0].text).to eq('The first parameter.')
|
555
|
-
expect(tags[0].types).to eq(['Boolean'])
|
556
|
-
expect(tags[1].name).to eq('&block')
|
557
|
-
expect(tags[1].text).to eq('The block parameter.')
|
558
|
-
expect(tags[1].types).to eq(['Callable'])
|
559
|
-
tags = overloads[1].tags(:return)
|
560
|
-
expect(tags.size).to eq(1)
|
561
|
-
expect(tags[0].name).to be_nil
|
562
|
-
expect(tags[0].text).to eq('Returns a string.')
|
563
|
-
expect(tags[0].types).to eq(['String'])
|
564
|
-
tags = object.docstring.tags(:api)
|
565
|
-
expect(tags.size).to eq(1)
|
566
|
-
expect(tags[0].text).to eq('public')
|
567
|
-
end
|
568
|
-
end
|
569
|
-
|
570
|
-
describe 'parsing a function with a namespaced name' do
|
571
|
-
let(:source) { <<-SOURCE
|
572
|
-
# An example 4.x function.
|
573
|
-
Puppet::Functions.create_function(:'foo::bar::baz') do
|
574
|
-
# @return [Undef]
|
575
|
-
dispatch :foo do
|
576
|
-
end
|
577
|
-
end
|
578
|
-
SOURCE
|
579
|
-
}
|
580
|
-
|
581
|
-
it 'should output the name correctly as a symbol' do
|
582
|
-
expect(subject.size).to eq(1)
|
583
|
-
expect(subject.first.name).to eq(:'foo::bar::baz')
|
584
|
-
end
|
585
|
-
end
|
586
|
-
|
587
|
-
describe 'parsing a function with a missing parameter' do
|
588
|
-
let(:source) { <<-SOURCE
|
589
|
-
# An example 4.x function.
|
590
|
-
Puppet::Functions.create_function(:foo) do
|
591
|
-
# @param missing A missing parameter.
|
592
|
-
# @return [Undef] Returns nothing.
|
593
|
-
dispatch :foo do
|
594
|
-
end
|
595
|
-
end
|
596
|
-
SOURCE
|
597
|
-
}
|
598
|
-
|
599
|
-
it 'should output a warning' do
|
600
|
-
expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'missing' has no matching parameter at \(stdin\):5/).to_stdout_from_any_process
|
601
|
-
end
|
602
|
-
end
|
603
|
-
|
604
|
-
describe 'parsing a function with a missing @param tag' do
|
605
|
-
let(:source) { <<-SOURCE
|
606
|
-
# An example 4.x function.
|
607
|
-
Puppet::Functions.create_function(:foo) do
|
608
|
-
# @return [Undef] Returns nothing.
|
609
|
-
dispatch :foo do
|
610
|
-
param 'String', :param1
|
611
|
-
end
|
612
|
-
end
|
613
|
-
SOURCE
|
614
|
-
}
|
615
|
-
|
616
|
-
it 'should output a warning' do
|
617
|
-
expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param1' near \(stdin\):5/).to_stdout_from_any_process
|
618
|
-
end
|
619
|
-
end
|
620
|
-
|
621
|
-
describe 'parsing a function with a typed @param tag' do
|
622
|
-
let(:source) { <<-SOURCE
|
623
|
-
# An example 4.x function.
|
624
|
-
Puppet::Functions.create_function(:foo) do
|
625
|
-
# @param [Integer] param1 The first parameter.
|
626
|
-
# @return [Undef] Returns nothing.
|
627
|
-
dispatch :foo do
|
628
|
-
param 'String', :param1
|
629
|
-
end
|
630
|
-
end
|
631
|
-
SOURCE
|
632
|
-
}
|
633
|
-
|
634
|
-
it 'should output a warning' do
|
635
|
-
expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):6: ignoring in favor of dispatch type information\./).to_stdout_from_any_process
|
636
|
-
end
|
637
|
-
end
|
638
|
-
|
639
|
-
describe 'parsing a function with a typed @param tag' do
|
640
|
-
let(:source) { <<-SOURCE
|
641
|
-
# An example 4.x function.
|
642
|
-
Puppet::Functions.create_function(:foo) do
|
643
|
-
# @param param1 The first parameter.
|
644
|
-
dispatch :foo do
|
645
|
-
param 'String', :param1
|
646
|
-
end
|
647
|
-
end
|
648
|
-
SOURCE
|
649
|
-
}
|
650
|
-
|
651
|
-
it 'should output a warning' do
|
652
|
-
expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):4/).to_stdout_from_any_process
|
653
|
-
end
|
654
|
-
end
|
655
|
-
|
656
|
-
describe 'parsing a function with a root @param tag' do
|
657
|
-
let(:source) { <<-SOURCE
|
658
|
-
# An example 4.x function.
|
659
|
-
# @param param Nope.
|
660
|
-
Puppet::Functions.create_function(:foo) do
|
661
|
-
# @return [Undef]
|
662
|
-
dispatch :foo do
|
663
|
-
end
|
664
|
-
end
|
665
|
-
SOURCE
|
666
|
-
}
|
667
|
-
|
668
|
-
it 'should output a warning' do
|
669
|
-
expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @param tags near \(stdin\):3: parameter documentation should be made on the dispatch call\./).to_stdout_from_any_process
|
670
|
-
end
|
671
|
-
end
|
672
|
-
|
673
|
-
|
674
|
-
describe 'parsing a function with a root @overload tag' do
|
675
|
-
let(:source) { <<-SOURCE
|
676
|
-
# An example 4.x function.
|
677
|
-
# @overload foo
|
678
|
-
Puppet::Functions.create_function(:foo) do
|
679
|
-
# @return [Undef]
|
680
|
-
dispatch :foo do
|
681
|
-
end
|
682
|
-
end
|
683
|
-
SOURCE
|
684
|
-
}
|
685
|
-
|
686
|
-
it 'should output a warning' do
|
687
|
-
expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @overload tags near \(stdin\):3: overload tags are automatically generated from the dispatch calls\./).to_stdout_from_any_process
|
688
|
-
end
|
689
|
-
end
|
690
|
-
|
691
|
-
describe 'parsing a function with a root @return tag' do
|
692
|
-
let(:source) { <<-SOURCE
|
693
|
-
# An example 4.x function.
|
694
|
-
# @return [Undef] foo
|
695
|
-
Puppet::Functions.create_function(:foo) do
|
696
|
-
# @return [Undef]
|
697
|
-
dispatch :foo do
|
698
|
-
end
|
699
|
-
end
|
700
|
-
SOURCE
|
701
|
-
}
|
702
|
-
|
703
|
-
it 'should output a warning' do
|
704
|
-
expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @return tags near \(stdin\):3: return value documentation should be made on the dispatch call\./).to_stdout_from_any_process
|
705
|
-
end
|
706
|
-
end
|
707
|
-
|
708
|
-
describe 'parsing a function with a summary' do
|
709
|
-
context 'when the summary has fewer than 140 characters' do
|
710
|
-
let(:source) { <<-SOURCE
|
711
|
-
# An example 4.x function.
|
712
|
-
# @summary A short summary.
|
713
|
-
Puppet::Functions.create_function(:foo) do
|
714
|
-
# @return [Undef]
|
715
|
-
dispatch :foo do
|
716
|
-
end
|
717
|
-
end
|
718
|
-
SOURCE
|
719
|
-
}
|
720
|
-
|
721
|
-
it 'should parse the summary' do
|
722
|
-
expect{ subject }.to output('').to_stdout_from_any_process
|
723
|
-
expect(subject.size).to eq(1)
|
724
|
-
summary = subject.first.tags(:summary)
|
725
|
-
expect(summary.first.text).to eq('A short summary.')
|
726
|
-
end
|
727
|
-
end
|
728
|
-
|
729
|
-
context 'when the summary has more than 140 characters' do
|
730
|
-
let(:source) { <<-SOURCE
|
731
|
-
# An example 4.x function.
|
732
|
-
# @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!!
|
733
|
-
Puppet::Functions.create_function(:foo) do
|
734
|
-
# @return [Undef]
|
735
|
-
dispatch :foo do
|
736
|
-
end
|
737
|
-
end
|
738
|
-
SOURCE
|
739
|
-
}
|
740
|
-
|
741
|
-
it 'should log a warning' do
|
742
|
-
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
|
743
|
-
end
|
744
|
-
end
|
745
|
-
end
|
746
|
-
end
|