puppet-lint-param-docs 1.3.1 → 1.5.1
Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
|
-
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 14633dfc2336826ed35662bf1840e6ef992f0032146f2a932a988a42521b2006
|
4
|
+
data.tar.gz: 9f7a4139402ebe4d390f07b38ed5013e4f10b42bf3e793d8b6a4e05c170d25c6
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 9c685fe25b7b03c9af645f2ff82ea4c86e3c820ce3343c16b4a8926be097a0e3fa4723910a7f5c71e555978101dc61a0739f6496abcae8eea2ca4296a8a3ec14
|
7
|
+
data.tar.gz: d696ad85c260c8956787f27a3af8b37a8b26526b57d789f005881ae89de538241fbaa7daca6ad03abd6e0576db71a306c1227f8b3cecb226dc4cd44d18a7927e
|
data/README.md
CHANGED
@@ -31,6 +31,45 @@ WARNING: missing documentation for class parameter foo::bar
|
|
31
31
|
WARNING: missing documentation for defined type parameter foo::baz
|
32
32
|
```
|
33
33
|
|
34
|
+
### Documentation styles
|
35
|
+
|
36
|
+
The check will accept any of the following styles:
|
37
|
+
|
38
|
+
#### Puppet Strings
|
39
|
+
|
40
|
+
Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
|
41
|
+
|
42
|
+
# Example class
|
43
|
+
#
|
44
|
+
# @param foo example
|
45
|
+
define example($foo) { }
|
46
|
+
|
47
|
+
#### Puppet Doc style
|
48
|
+
|
49
|
+
Used by the [puppet-doc](https://docs.puppetlabs.com/puppet/latest/reference/man/doc.html)
|
50
|
+
command, generally deprecated in favour of Puppet Strings.
|
51
|
+
|
52
|
+
# Example class
|
53
|
+
#
|
54
|
+
# === Parameters:
|
55
|
+
#
|
56
|
+
# [*foo*] example
|
57
|
+
#
|
58
|
+
class example($foo) { }
|
59
|
+
|
60
|
+
#### Kafo rdoc style
|
61
|
+
|
62
|
+
Used in [kafo](https://github.com/theforeman/kafo#documentation) following an
|
63
|
+
rdoc style.
|
64
|
+
|
65
|
+
# Example class
|
66
|
+
#
|
67
|
+
# === Parameters:
|
68
|
+
#
|
69
|
+
# $foo:: example
|
70
|
+
#
|
71
|
+
class example($foo) { }
|
72
|
+
|
34
73
|
### Selective rake task
|
35
74
|
|
36
75
|
The usual puppet-lint rake task checks all manifests, which isn't always
|
@@ -39,11 +78,14 @@ some of which you don't wish to document, then you can exclude them using
|
|
39
78
|
[control comments](http://puppet-lint.com/controlcomments/) or by using this
|
40
79
|
helper to customise the lint rake task:
|
41
80
|
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
81
|
+
require 'puppet-lint-param-docs/tasks'
|
82
|
+
PuppetLintParamDocs.define_selective do |config|
|
83
|
+
config.pattern = ['manifests/init.pp', 'manifests/other/**/*.pp']
|
84
|
+
end
|
46
85
|
|
47
86
|
This would disable the parameter_documentation check by default, but then
|
48
87
|
defines a new rake task (which runs after `lint`) specifically for the files
|
49
88
|
given in `config.pattern`.
|
89
|
+
|
90
|
+
The [Puppet Strings](#puppet_strings) `@api private` directive can also be used
|
91
|
+
to disable checks on that file.
|
@@ -4,28 +4,42 @@ PuppetLint.new_check(:parameter_documentation) do
|
|
4
4
|
next if idx[:param_tokens].nil?
|
5
5
|
|
6
6
|
doc_params = []
|
7
|
+
is_private = false
|
7
8
|
tokens[0..idx[:start]].reverse_each do |dtok|
|
8
9
|
next if [:CLASS, :DEFINE, :NEWLINE, :WHITESPACE, :INDENT].include?(dtok.type)
|
9
10
|
if [:COMMENT, :MLCOMMENT, :SLASH_COMMENT].include?(dtok.type)
|
10
11
|
if dtok.value =~ /\A\s*\[\*([a-zA-Z0-9_]+)\*\]/ or
|
11
|
-
dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+):: +/
|
12
|
+
dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+):: +/ or
|
13
|
+
dtok.value =~ /\A\s*@param (?:\[.+\] )?([a-zA-Z0-9_]+)(?: +|$)/
|
12
14
|
doc_params << $1
|
13
15
|
end
|
16
|
+
|
17
|
+
is_private = true if dtok.value =~ /\A\s*@api +private\s*$/
|
14
18
|
else
|
15
19
|
break
|
16
20
|
end
|
17
21
|
end
|
18
22
|
|
23
|
+
next if is_private
|
24
|
+
|
19
25
|
params = []
|
20
26
|
e = idx[:param_tokens].each
|
21
27
|
begin
|
22
28
|
while (ptok = e.next)
|
23
29
|
if ptok.type == :VARIABLE
|
24
30
|
params << ptok
|
31
|
+
nesting = 0
|
25
32
|
# skip to the next parameter to avoid finding default values of variables
|
26
33
|
while true
|
27
34
|
ptok = e.next
|
28
|
-
|
35
|
+
case ptok.type
|
36
|
+
when :LPAREN
|
37
|
+
nesting += 1
|
38
|
+
when :RPAREN
|
39
|
+
nesting -= 1
|
40
|
+
when :COMMA
|
41
|
+
break unless nesting > 0
|
42
|
+
end
|
29
43
|
end
|
30
44
|
end
|
31
45
|
end
|
@@ -52,6 +52,18 @@ describe 'parameter_documentation' do
|
|
52
52
|
end
|
53
53
|
end
|
54
54
|
|
55
|
+
context 'define with param defaults using a function' do
|
56
|
+
let(:code) { 'define example($foo = min(8, $facts["processors"]["count"])) { }' }
|
57
|
+
|
58
|
+
it 'should detect a single problem' do
|
59
|
+
expect(problems).to have(1).problem
|
60
|
+
end
|
61
|
+
|
62
|
+
it 'should create a warning' do
|
63
|
+
expect(problems).to contain_warning(define_msg % :foo).on_line(1).in_column(16)
|
64
|
+
end
|
65
|
+
end
|
66
|
+
|
55
67
|
context 'class with many param defaults' do
|
56
68
|
let(:code) do
|
57
69
|
<<-EOS
|
@@ -130,6 +142,65 @@ define foreman (
|
|
130
142
|
end
|
131
143
|
end
|
132
144
|
|
145
|
+
context 'class missing documentation (@param bar) for a parameter' do
|
146
|
+
let(:code) do
|
147
|
+
<<-EOS.gsub(/^\s+/, '')
|
148
|
+
# Example class
|
149
|
+
#
|
150
|
+
# @param bar example
|
151
|
+
class example($foo, $bar) { }
|
152
|
+
EOS
|
153
|
+
end
|
154
|
+
|
155
|
+
it 'should detect a single problem' do
|
156
|
+
expect(problems).to have(1).problem
|
157
|
+
end
|
158
|
+
|
159
|
+
it 'should create a warning' do
|
160
|
+
expect(problems).to contain_warning(class_msg % :foo).on_line(4).in_column(15)
|
161
|
+
end
|
162
|
+
end
|
163
|
+
|
164
|
+
context 'private class missing documentation (@param bar) for a parameter' do
|
165
|
+
let(:code) do
|
166
|
+
<<-EOS.gsub(/^\s+/, '')
|
167
|
+
# Example class
|
168
|
+
#
|
169
|
+
# @api private
|
170
|
+
#
|
171
|
+
# @param bar example
|
172
|
+
class example($foo, $bar) { }
|
173
|
+
EOS
|
174
|
+
end
|
175
|
+
|
176
|
+
it 'should detect no single problems' do
|
177
|
+
expect(problems).to have(0).problems
|
178
|
+
end
|
179
|
+
|
180
|
+
it 'should not create a warning' do
|
181
|
+
expect(problems).not_to contain_info(class_msg % :foo)
|
182
|
+
end
|
183
|
+
end
|
184
|
+
|
185
|
+
context 'define missing documentation (@param bar) for a parameter' do
|
186
|
+
let(:code) do
|
187
|
+
<<-EOS.gsub(/^\s+/, '')
|
188
|
+
# Example class
|
189
|
+
#
|
190
|
+
# @param bar example
|
191
|
+
define example($foo, $bar) { }
|
192
|
+
EOS
|
193
|
+
end
|
194
|
+
|
195
|
+
it 'should detect a single problem' do
|
196
|
+
expect(problems).to have(1).problem
|
197
|
+
end
|
198
|
+
|
199
|
+
it 'should create a warning' do
|
200
|
+
expect(problems).to contain_warning(define_msg % :foo).on_line(4).in_column(16)
|
201
|
+
end
|
202
|
+
end
|
203
|
+
|
133
204
|
context 'class missing documentation ([*bar*]) for a parameter' do
|
134
205
|
let(:code) do
|
135
206
|
<<-EOS.gsub(/^\s+/, '')
|
@@ -338,6 +409,88 @@ define foreman (
|
|
338
409
|
end
|
339
410
|
end
|
340
411
|
|
412
|
+
context 'class with all parameters documented (@param)' do
|
413
|
+
let(:code) do
|
414
|
+
<<-EOS
|
415
|
+
# Example class
|
416
|
+
#
|
417
|
+
# === Parameters:
|
418
|
+
#
|
419
|
+
# @param foo example
|
420
|
+
# @param [Integer] bar example
|
421
|
+
# @param baz
|
422
|
+
# example
|
423
|
+
# @param [Integer] qux
|
424
|
+
# example
|
425
|
+
#
|
426
|
+
class example($foo, $bar, $baz, $qux) { }
|
427
|
+
EOS
|
428
|
+
end
|
429
|
+
|
430
|
+
it 'should not detect any problems' do
|
431
|
+
expect(problems).to have(0).problems
|
432
|
+
end
|
433
|
+
end
|
434
|
+
|
435
|
+
context 'define with all parameters documented (@param)' do
|
436
|
+
let(:code) do
|
437
|
+
<<-EOS
|
438
|
+
# Example define
|
439
|
+
#
|
440
|
+
# === Parameters:
|
441
|
+
#
|
442
|
+
# @param foo example
|
443
|
+
# @param [Integer] bar example
|
444
|
+
# @param baz
|
445
|
+
# example
|
446
|
+
# @param [Integer] qux
|
447
|
+
# example
|
448
|
+
#
|
449
|
+
define example($foo, $bar, $baz, $qux) { }
|
450
|
+
EOS
|
451
|
+
end
|
452
|
+
|
453
|
+
it 'should not detect any problems' do
|
454
|
+
expect(problems).to have(0).problems
|
455
|
+
end
|
456
|
+
end
|
457
|
+
|
458
|
+
context 'define with all parameters documented with defaults (@param)' do
|
459
|
+
let(:code) do
|
460
|
+
<<-EOS
|
461
|
+
# Example define
|
462
|
+
#
|
463
|
+
# @param foo example
|
464
|
+
#
|
465
|
+
define example($foo = $facts['networking']['fqdn']) { }
|
466
|
+
EOS
|
467
|
+
end
|
468
|
+
|
469
|
+
it 'should not detect any problems' do
|
470
|
+
expect(problems).to have(0).problems
|
471
|
+
end
|
472
|
+
end
|
473
|
+
|
474
|
+
context 'define with all parameters documented with defaults using functions (@param)' do
|
475
|
+
let(:code) do
|
476
|
+
<<-EOS
|
477
|
+
# Example define
|
478
|
+
#
|
479
|
+
# @param foo example
|
480
|
+
# @param multiple test nested function calls
|
481
|
+
#
|
482
|
+
define example(
|
483
|
+
$foo = min(8, $facts['processors']['count']),
|
484
|
+
$multiple = min(8, max(2, $facts['processors']['count'])),
|
485
|
+
) { }
|
486
|
+
EOS
|
487
|
+
end
|
488
|
+
|
489
|
+
it 'should not detect any problems' do
|
490
|
+
expect(problems).to have(0).problems
|
491
|
+
end
|
492
|
+
end
|
493
|
+
|
341
494
|
context 'class without parameters' do
|
342
495
|
let(:code) { 'class example { }' }
|
343
496
|
|
metadata
CHANGED
@@ -1,88 +1,107 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: puppet-lint-param-docs
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 1.
|
4
|
+
version: 1.5.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
|
-
-
|
7
|
+
- Vox Pupuli
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date:
|
11
|
+
date: 2020-06-23 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: puppet-lint
|
15
15
|
requirement: !ruby/object:Gem::Requirement
|
16
16
|
requirements:
|
17
|
-
- -
|
17
|
+
- - ">="
|
18
18
|
- !ruby/object:Gem::Version
|
19
19
|
version: '1.1'
|
20
|
+
- - "<"
|
21
|
+
- !ruby/object:Gem::Version
|
22
|
+
version: '3.0'
|
20
23
|
type: :runtime
|
21
24
|
prerelease: false
|
22
25
|
version_requirements: !ruby/object:Gem::Requirement
|
23
26
|
requirements:
|
24
|
-
- -
|
27
|
+
- - ">="
|
25
28
|
- !ruby/object:Gem::Version
|
26
29
|
version: '1.1'
|
30
|
+
- - "<"
|
31
|
+
- !ruby/object:Gem::Version
|
32
|
+
version: '3.0'
|
27
33
|
- !ruby/object:Gem::Dependency
|
28
34
|
name: rspec
|
29
35
|
requirement: !ruby/object:Gem::Requirement
|
30
36
|
requirements:
|
31
|
-
- - ~>
|
37
|
+
- - "~>"
|
32
38
|
- !ruby/object:Gem::Version
|
33
39
|
version: '3.0'
|
34
40
|
type: :development
|
35
41
|
prerelease: false
|
36
42
|
version_requirements: !ruby/object:Gem::Requirement
|
37
43
|
requirements:
|
38
|
-
- - ~>
|
44
|
+
- - "~>"
|
39
45
|
- !ruby/object:Gem::Version
|
40
46
|
version: '3.0'
|
41
47
|
- !ruby/object:Gem::Dependency
|
42
48
|
name: rspec-its
|
43
49
|
requirement: !ruby/object:Gem::Requirement
|
44
50
|
requirements:
|
45
|
-
- - ~>
|
51
|
+
- - "~>"
|
46
52
|
- !ruby/object:Gem::Version
|
47
53
|
version: '1.0'
|
48
54
|
type: :development
|
49
55
|
prerelease: false
|
50
56
|
version_requirements: !ruby/object:Gem::Requirement
|
51
57
|
requirements:
|
52
|
-
- - ~>
|
58
|
+
- - "~>"
|
53
59
|
- !ruby/object:Gem::Version
|
54
60
|
version: '1.0'
|
55
61
|
- !ruby/object:Gem::Dependency
|
56
62
|
name: rspec-collection_matchers
|
57
63
|
requirement: !ruby/object:Gem::Requirement
|
58
64
|
requirements:
|
59
|
-
- - ~>
|
65
|
+
- - "~>"
|
60
66
|
- !ruby/object:Gem::Version
|
61
67
|
version: '1.0'
|
62
68
|
type: :development
|
63
69
|
prerelease: false
|
64
70
|
version_requirements: !ruby/object:Gem::Requirement
|
65
71
|
requirements:
|
66
|
-
- - ~>
|
72
|
+
- - "~>"
|
67
73
|
- !ruby/object:Gem::Version
|
68
74
|
version: '1.0'
|
69
75
|
- !ruby/object:Gem::Dependency
|
70
76
|
name: rake
|
71
77
|
requirement: !ruby/object:Gem::Requirement
|
72
78
|
requirements:
|
73
|
-
- -
|
79
|
+
- - ">="
|
74
80
|
- !ruby/object:Gem::Version
|
75
81
|
version: '0'
|
76
82
|
type: :development
|
77
83
|
prerelease: false
|
78
84
|
version_requirements: !ruby/object:Gem::Requirement
|
79
85
|
requirements:
|
80
|
-
- -
|
86
|
+
- - ">="
|
87
|
+
- !ruby/object:Gem::Version
|
88
|
+
version: '0'
|
89
|
+
- !ruby/object:Gem::Dependency
|
90
|
+
name: simplecov
|
91
|
+
requirement: !ruby/object:Gem::Requirement
|
92
|
+
requirements:
|
93
|
+
- - ">="
|
81
94
|
- !ruby/object:Gem::Version
|
82
95
|
version: '0'
|
83
|
-
|
84
|
-
|
85
|
-
|
96
|
+
type: :development
|
97
|
+
prerelease: false
|
98
|
+
version_requirements: !ruby/object:Gem::Requirement
|
99
|
+
requirements:
|
100
|
+
- - ">="
|
101
|
+
- !ruby/object:Gem::Version
|
102
|
+
version: '0'
|
103
|
+
description: " A new check for puppet-lint that validates all parameters are documented.\n"
|
104
|
+
email: voxpupuli@groups.io
|
86
105
|
executables: []
|
87
106
|
extensions: []
|
88
107
|
extra_rdoc_files: []
|
@@ -94,7 +113,7 @@ files:
|
|
94
113
|
- lib/puppet-lint/plugins/check_parameter_documentation.rb
|
95
114
|
- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
|
96
115
|
- spec/spec_helper.rb
|
97
|
-
homepage: https://github.com/
|
116
|
+
homepage: https://github.com/voxpupuli/puppet-lint-param-docs
|
98
117
|
licenses:
|
99
118
|
- MIT
|
100
119
|
metadata: {}
|
@@ -104,20 +123,20 @@ require_paths:
|
|
104
123
|
- lib
|
105
124
|
required_ruby_version: !ruby/object:Gem::Requirement
|
106
125
|
requirements:
|
107
|
-
- -
|
126
|
+
- - ">="
|
108
127
|
- !ruby/object:Gem::Version
|
109
128
|
version: '0'
|
110
129
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
111
130
|
requirements:
|
112
|
-
- -
|
131
|
+
- - ">="
|
113
132
|
- !ruby/object:Gem::Version
|
114
133
|
version: '0'
|
115
134
|
requirements: []
|
116
135
|
rubyforge_project:
|
117
|
-
rubygems_version: 2.
|
136
|
+
rubygems_version: 2.7.7
|
118
137
|
signing_key:
|
119
138
|
specification_version: 4
|
120
139
|
summary: puppet-lint check to validate all parameters are documented
|
121
140
|
test_files:
|
122
|
-
- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
|
123
141
|
- spec/spec_helper.rb
|
142
|
+
- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
|