puppet-lint-param-docs 1.6.0 → 1.7.0
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
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: ca78318c1175f2885dcffee1d275f71edc78bb91a0624dc32e84fd949c03a841
|
4
|
+
data.tar.gz: d38343fa7170f7cdc1ae94c10aa3e809be6e61a30ce5f25d1c147e191782744f
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 6c960b3b0f25548ff75c5597ac10ed27164a1230db2ab223272ad43dae88c223ca1653ef2c8e9c0ae416c98a8f4a8ba139c1501d920e3d6cbd521b6a49f8c058
|
7
|
+
data.tar.gz: 7433e3dee1f9055b53332dd4b3d080e154d2be067f70fb9db1a98317f2bb3a217f4548ead7db47dba081cd7b11b1e2a9038c0163d27d2a00775d1d69c54c89c1
|
data/README.md
CHANGED
@@ -46,9 +46,25 @@ WARNING No matching class parameter for documentation of foo::bar
|
|
46
46
|
|
47
47
|
### Documentation styles
|
48
48
|
|
49
|
+
By default, the check will allow all known documentation styles.
|
50
|
+
You can, however, specify a list of accepted formats:
|
51
|
+
|
52
|
+
```ruby
|
53
|
+
# Limit to a single style
|
54
|
+
PuppetLint.configuration.docs_allowed_styles = 'strings'
|
55
|
+
# Limit to multiple styles
|
56
|
+
PuppetLint.configuration.docs_allowed_styles = ['strings', 'doc']
|
57
|
+
```
|
58
|
+
|
59
|
+
It will raise a warning if the documentation style does not match.
|
60
|
+
|
61
|
+
```
|
62
|
+
WARNING: invalid documentation style for class parameter foo::bar (doc) on line 4
|
63
|
+
```
|
64
|
+
|
49
65
|
The check will accept any of the following styles:
|
50
66
|
|
51
|
-
#### Puppet Strings
|
67
|
+
#### Puppet Strings: `strings`
|
52
68
|
|
53
69
|
Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
|
54
70
|
|
@@ -59,7 +75,7 @@ Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
|
|
59
75
|
define example($foo) { }
|
60
76
|
```
|
61
77
|
|
62
|
-
#### Puppet Doc style
|
78
|
+
#### Puppet Doc style: `doc`
|
63
79
|
|
64
80
|
Used by the [puppet-doc](https://puppet.com/docs/puppet/6.18/man/doc.html)
|
65
81
|
command, deprecated in favour of Puppet Strings.
|
@@ -74,7 +90,7 @@ command, deprecated in favour of Puppet Strings.
|
|
74
90
|
class example($foo) { }
|
75
91
|
```
|
76
92
|
|
77
|
-
#### Kafo rdoc style
|
93
|
+
#### Kafo rdoc style: `kafo`
|
78
94
|
|
79
95
|
Used in [kafo](https://github.com/theforeman/kafo#documentation) following an
|
80
96
|
rdoc style.
|
@@ -1,27 +1,33 @@
|
|
1
1
|
PuppetLint.new_check(:parameter_documentation) do
|
2
2
|
def check
|
3
|
+
allowed_styles = PuppetLint.configuration.docs_allowed_styles || ['doc', 'kafo', 'strings']
|
4
|
+
allowed_styles = [ allowed_styles ].flatten
|
5
|
+
|
3
6
|
class_indexes.concat(defined_type_indexes).each do |idx|
|
4
7
|
doc_params = {}
|
8
|
+
doc_params_styles = {}
|
5
9
|
doc_params_duplicates = Hash.new { |hash, key| hash[key] = [doc_params[key]] }
|
6
10
|
is_private = false
|
7
11
|
tokens[0..idx[:start]].reverse_each do |dtok|
|
8
12
|
next if [:CLASS, :DEFINE, :NEWLINE, :WHITESPACE, :INDENT].include?(dtok.type)
|
9
13
|
if dtok.type == :COMMENT
|
10
|
-
if dtok.value =~ /\A\s
|
11
|
-
|
12
|
-
|
13
|
-
parameter = $1
|
14
|
-
parameter = 'name/title' if idx[:type] == :DEFINE && ['name','title'].include?(parameter)
|
15
|
-
if doc_params.include? parameter
|
16
|
-
doc_params_duplicates[parameter] << dtok
|
17
|
-
else
|
18
|
-
doc_params[parameter] = dtok
|
19
|
-
end
|
14
|
+
if dtok.value =~ /\A\s*@api +private\s*$/
|
15
|
+
is_private = true
|
16
|
+
next
|
20
17
|
end
|
21
18
|
|
22
|
-
|
23
|
-
|
24
|
-
|
19
|
+
style = detect_style(dtok)
|
20
|
+
# not a doc parameter if style has not been detected
|
21
|
+
next if style[0].nil?
|
22
|
+
|
23
|
+
parameter = style[2]
|
24
|
+
parameter = 'name/title' if idx[:type] == :DEFINE && ['name','title'].include?(parameter)
|
25
|
+
if doc_params.include? parameter
|
26
|
+
doc_params_duplicates[parameter] << dtok
|
27
|
+
else
|
28
|
+
doc_params[parameter] = dtok
|
29
|
+
doc_params_styles[parameter] = style[0]
|
30
|
+
end
|
25
31
|
end
|
26
32
|
end
|
27
33
|
|
@@ -52,12 +58,22 @@ PuppetLint.new_check(:parameter_documentation) do
|
|
52
58
|
|
53
59
|
unless is_private
|
54
60
|
params.each do |p|
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
+
if doc_params.has_key? p.value
|
62
|
+
style = doc_params_styles[p.value] || 'unknown'
|
63
|
+
unless allowed_styles.include?(style)
|
64
|
+
notify :warning, {
|
65
|
+
:message => "invalid documentation style for #{type_str(idx)} parameter #{idx[:name_token].value}::#{p.value} (#{doc_params_styles[p.value]})",
|
66
|
+
:line => p.line,
|
67
|
+
:column => p.column,
|
68
|
+
}
|
69
|
+
end
|
70
|
+
else
|
71
|
+
notify :warning, {
|
72
|
+
:message => "missing documentation for #{type_str(idx)} parameter #{idx[:name_token].value}::#{p.value}",
|
73
|
+
:line => p.line,
|
74
|
+
:column => p.column,
|
75
|
+
}
|
76
|
+
end
|
61
77
|
end
|
62
78
|
end
|
63
79
|
end
|
@@ -97,4 +113,19 @@ PuppetLint.new_check(:parameter_documentation) do
|
|
97
113
|
|
98
114
|
params
|
99
115
|
end
|
116
|
+
|
117
|
+
# returns an array [<detected_style>, <complete match>, <param name>, <same-line-docs>]
|
118
|
+
# [nil, nil] if this is not a parameter.
|
119
|
+
def detect_style(dtok)
|
120
|
+
style = nil
|
121
|
+
case dtok.value
|
122
|
+
when %r{\A\s*\[\*([a-zA-Z0-9_]+)\*\]\s*(.*)\z}
|
123
|
+
style = 'doc'
|
124
|
+
when %r{\A\s*\$([a-zA-Z0-9_]+):: +(.*)\z}
|
125
|
+
style = 'kafo'
|
126
|
+
when %r{\A\s*@param (?:\[.+\] )?([a-zA-Z0-9_]+)(?: +|$)(.*)\z}
|
127
|
+
style = 'strings'
|
128
|
+
end
|
129
|
+
[ style, * $~ ]
|
130
|
+
end
|
100
131
|
end
|
@@ -3,6 +3,8 @@ require 'spec_helper'
|
|
3
3
|
describe 'parameter_documentation' do
|
4
4
|
let(:class_msg) { 'missing documentation for class parameter example::%s' }
|
5
5
|
let(:define_msg) { 'missing documentation for defined type parameter example::%s' }
|
6
|
+
let(:class_style_msg) { 'invalid documentation style for class parameter example::%s (%s)' }
|
7
|
+
let(:define_style_msg) { 'invalid documentation style for defined type parameter example::%s (%s)' }
|
6
8
|
|
7
9
|
context 'class missing any documentation' do
|
8
10
|
let(:code) { 'class example($foo) { }' }
|
@@ -355,6 +357,62 @@ define foreman (
|
|
355
357
|
end
|
356
358
|
end
|
357
359
|
|
360
|
+
context 'check style' do
|
361
|
+
let(:code) do
|
362
|
+
<<-EOS
|
363
|
+
# Example mixed style class
|
364
|
+
#
|
365
|
+
# Parameters:
|
366
|
+
#
|
367
|
+
# $foo:: example
|
368
|
+
#
|
369
|
+
# [*bar*] example
|
370
|
+
#
|
371
|
+
# @param foobar example
|
372
|
+
#
|
373
|
+
class example($foo, $bar, $foobar) { }
|
374
|
+
EOS
|
375
|
+
end
|
376
|
+
|
377
|
+
context 'detect all styles' do
|
378
|
+
before do
|
379
|
+
PuppetLint.configuration.docs_allowed_styles = ['noexist']
|
380
|
+
end
|
381
|
+
after do
|
382
|
+
PuppetLint.configuration.docs_allowed_styles = false
|
383
|
+
end
|
384
|
+
|
385
|
+
it 'should detect three problems' do
|
386
|
+
expect(problems).to have(3).problems
|
387
|
+
end
|
388
|
+
|
389
|
+
it 'should create three problems' do
|
390
|
+
expect(problems).to contain_warning(class_style_msg % [:foo, 'kafo']).on_line(11).in_column(21)
|
391
|
+
expect(problems).to contain_warning(class_style_msg % [:bar, 'doc']).on_line(11).in_column(27)
|
392
|
+
expect(problems).to contain_warning(class_style_msg % [:foobar, 'strings']).on_line(11).in_column(33)
|
393
|
+
end
|
394
|
+
end
|
395
|
+
|
396
|
+
context 'use configured style' do
|
397
|
+
before do
|
398
|
+
PuppetLint.configuration.docs_allowed_styles = 'strings'
|
399
|
+
end
|
400
|
+
after do
|
401
|
+
PuppetLint.configuration.docs_allowed_styles = nil
|
402
|
+
end
|
403
|
+
|
404
|
+
it 'should detect two problems' do
|
405
|
+
expect(problems).to have(2).problems
|
406
|
+
end
|
407
|
+
|
408
|
+
it 'should create three problems' do
|
409
|
+
expect(problems).to contain_warning(class_style_msg % [:foo, 'kafo']).on_line(11).in_column(21)
|
410
|
+
expect(problems).to contain_warning(class_style_msg % [:bar, 'doc']).on_line(11).in_column(27)
|
411
|
+
end
|
412
|
+
end
|
413
|
+
end
|
414
|
+
|
415
|
+
|
358
416
|
context 'define with all parameters documented ($foo::)' do
|
359
417
|
let(:code) do
|
360
418
|
<<-EOS
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
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.7.0
|
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: 2021-06-05 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: puppet-lint
|
@@ -132,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
|
|
132
132
|
- !ruby/object:Gem::Version
|
133
133
|
version: '0'
|
134
134
|
requirements: []
|
135
|
-
rubygems_version: 3.
|
135
|
+
rubygems_version: 3.1.6
|
136
136
|
signing_key:
|
137
137
|
specification_version: 4
|
138
138
|
summary: puppet-lint check to validate all parameters are documented
|