puppet-lint-param-docs 1.6.0 → 1.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b7f8ef3f161f032261f4785f2ef368e89ad583295f8d1af9e25fc2daad26e15
-  data.tar.gz: ff99f8a6a3c9ceb061c6b8397e928ab5871fc2da91fffb0c296efe0f340a2575
+  metadata.gz: 4eb142c68d835142b195284909d9537589ed309072ddaa0a5ba1613422f3588e
+  data.tar.gz: 7eb0c3cde4c9772b8d54078de3a7598294545e4de5d4b61509a634d3a4984fae
 SHA512:
-  metadata.gz: dad82fe8054ea2433eb4bfa7d2c4a39401de66308e4c2f5027e9da3c39fbc93284e2c501b48a175469bbc3f61d1c950ee5beb5153f871084a5d3361c4d0175c9
-  data.tar.gz: e321066d4a8fc4661a923f0d1ab1e06e986a021462b7411c2b66eb5ab06d2087cdea4cb4ce39c16f480cf2ea8195c0bdbdc19e07272727eb0ba30130b726b4d7
+  metadata.gz: 0fc8365176cd4916883c7e0734a71dab1f38d0a507241df4b2479772127d6293c52c4d236ff21e74fba51e0b2994dcee22f2cad34d617ee1a7df088a34076246
+  data.tar.gz: 925331d48264d7787f8874c96db4cdcfb5b2b4f616f7addfacfcdd3a2ee7b8daf05b1886e57adbd17768d6200250a0d136968808c0cde2f24b20294910788ca4

data/README.md

@@ -1,5 +1,13 @@
 # puppet-lint parameter documentation check
 
+[![License](https://img.shields.io/github/license/voxpupuli/puppet-lint-trailing_comma-check.svg)](https://github.com/voxpupuli/puppet-lint-trailing_comma-check/blob/master/LICENSE)
+[![Test](https://github.com/voxpupuli/puppet-lint-param-docs/actions/workflows/test.yml/badge.svg)](https://github.com/voxpupuli/puppet-lint-param-docs/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/voxpupuli/puppet-lint-param-docs/branch/master/graph/badge.svg?token=Mypkl78hvK)](https://codecov.io/gh/voxpupuli/puppet-lint-param-docs)
+[![Release](https://github.com/voxpupuli/puppet-lint-param-docs/actions/workflows/release.yml/badge.svg)](https://github.com/voxpupuli/puppet-lint-param-docs/actions/workflows/release.yml)
+[![RubyGem Version](https://img.shields.io/gem/v/puppet-lint-param-docs.svg)](https://rubygems.org/gems/puppet-lint-param-docs)
+[![RubyGem Downloads](https://img.shields.io/gem/dt/puppet-lint-param-docs.svg)](https://rubygems.org/gems/puppet-lint-param-docs)
+[![Donated by Dominic Cleal](https://img.shields.io/badge/donated%20by-Dominic%20Cleal-fb7047.svg)](#transfer-notice)
+
 Adds a new puppet-lint check to verify all class and defined type parameters
 have been documented.
 
@@ -15,6 +23,21 @@ base and run `bundle install`.
 gem 'puppet-lint-param-docs'
 ```
 
+This gem is not only available on rubygems, but also as [GitHub Package](https://github.com/voxpupuli/puppet-lint-param-docs/packages/)
+You can install it from GitHub like this:
+
+```
+$ gem install puppet-lint-param-docs --source "https://rubygems.pkg.github.com/voxpupuli"
+```
+
+Or in a Gemfile:
+
+```
+source "https://rubygems.pkg.github.com/voxpupuli" do
+  gem "puppet-lint-param-docs", "1.7.4"
+end
+```
+
 ## Usage
 
 This plugin provides a new check to `puppet-lint`.
@@ -46,9 +69,25 @@ WARNING No matching class parameter for documentation of foo::bar
 
 ### Documentation styles
 
+By default, the check will allow all known documentation styles.
+You can, however, specify a list of accepted formats:
+
+```ruby
+# Limit to a single style
+PuppetLint.configuration.docs_allowed_styles = 'strings'
+# Limit to multiple styles
+PuppetLint.configuration.docs_allowed_styles = ['strings', 'doc']
+```
+
+It will raise a warning if the documentation style does not match.
+
+```
+WARNING: invalid documentation style for class parameter foo::bar (doc) on line 4
+```
+
 The check will accept any of the following styles:
 
-#### Puppet Strings
+#### Puppet Strings: `strings`
 
 Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
 
@@ -59,7 +98,7 @@ Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
 define example($foo) { }
 ```
 
-#### Puppet Doc style
+#### Puppet Doc style: `doc`
 
 Used by the [puppet-doc](https://puppet.com/docs/puppet/6.18/man/doc.html)
 command, deprecated in favour of Puppet Strings.
@@ -74,7 +113,7 @@ command, deprecated in favour of Puppet Strings.
 class example($foo) { }
 ```
 
-#### Kafo rdoc style
+#### Kafo rdoc style: `kafo`
 
 Used in [kafo](https://github.com/theforeman/kafo#documentation) following an
 rdoc style.
@@ -108,3 +147,25 @@ given in `config.pattern`.
 
 The [Puppet Strings](#puppet_strings) `@api private` directive can also be used
 to disable checks on that file.
+
+## Transfer Notice
+
+This plugin was originally authored by [Dominic Cleal](https://github.com/domcleal).
+The maintainer preferred that Puppet Community take ownership of the module for future improvement and maintenance.
+Existing pull requests and issues were transferred over, please fork and continue to contribute here.
+
+Previously: https://github.com/domcleal/puppet-lint-absolute_classname-check
+
+## License
+
+This gem is licensed under the MIT license.
+
+## Release information
+
+To make a new release, please do:
+* update the version in the gemspec file
+* Install gems with `bundle install --with release --path .vendor`
+* generate the changelog with `bundle exec rake changelog`
+* Check if the new version matches the closed issues/PRs in the changelog
+* Create a PR with it
+* After it got merged, push a tag. GitHub actions will do the actual release to rubygems and GitHub Packages

data/lib/puppet-lint/plugins/check_parameter_documentation.rb

@@ -1,27 +1,33 @@
 PuppetLint.new_check(:parameter_documentation) do
   def check
+    allowed_styles = PuppetLint.configuration.docs_allowed_styles || ['doc', 'kafo', 'strings']
+    allowed_styles = [ allowed_styles ].flatten
+
     class_indexes.concat(defined_type_indexes).each do |idx|
       doc_params = {}
+      doc_params_styles = {}
       doc_params_duplicates = Hash.new { |hash, key| hash[key] = [doc_params[key]] }
       is_private = false
       tokens[0..idx[:start]].reverse_each do |dtok|
         next if [:CLASS, :DEFINE, :NEWLINE, :WHITESPACE, :INDENT].include?(dtok.type)
         if dtok.type == :COMMENT
-          if dtok.value =~ /\A\s*\[\*([a-zA-Z0-9_]+)\*\]/ or
-             dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+):: +/ or
-             dtok.value =~ /\A\s*@param (?:\[.+\] )?([a-zA-Z0-9_]+)(?: +|$)/
-            parameter = $1
-            parameter = 'name/title' if idx[:type] == :DEFINE && ['name','title'].include?(parameter)
-            if doc_params.include? parameter
-              doc_params_duplicates[parameter] << dtok
-            else
-              doc_params[parameter] = dtok
-            end
+          if dtok.value =~ /\A\s*@api +private\s*$/
+            is_private = true
+            next
           end
 
-          is_private = true if dtok.value =~ /\A\s*@api +private\s*$/
-        else
-          break
+          style = detect_style(dtok)
+          # not a doc parameter if style has not been detected
+          next if style[0].nil?
+
+          parameter = style[2]
+          parameter = 'name/title' if idx[:type] == :DEFINE && ['name','title'].include?(parameter)
+          if doc_params.include? parameter
+            doc_params_duplicates[parameter] << dtok
+          else
+            doc_params[parameter] = dtok
+            doc_params_styles[parameter] = style[0]
+          end
         end
       end
 
@@ -52,12 +58,22 @@ PuppetLint.new_check(:parameter_documentation) do
 
       unless is_private
         params.each do |p|
-          next if doc_params.has_key? p.value
-          notify :warning, {
-            :message => "missing documentation for #{type_str(idx)} parameter #{idx[:name_token].value}::#{p.value}",
-            :line    => p.line,
-            :column  => p.column,
-          }
+          if doc_params.has_key? p.value
+            style = doc_params_styles[p.value] || 'unknown'
+            unless allowed_styles.include?(style)
+              notify :warning, {
+                :message => "invalid documentation style for #{type_str(idx)} parameter #{idx[:name_token].value}::#{p.value} (#{doc_params_styles[p.value]})",
+                :line    => p.line,
+                :column  => p.column,
+              }
+            end
+          else
+            notify :warning, {
+              :message => "missing documentation for #{type_str(idx)} parameter #{idx[:name_token].value}::#{p.value}",
+              :line    => p.line,
+              :column  => p.column,
+            }
+          end
         end
       end
     end
@@ -83,9 +99,9 @@ PuppetLint.new_check(:parameter_documentation) do
           while true
             ptok = e.next
             case ptok.type
-            when :LPAREN
+            when :LPAREN, :LBRACK
               nesting += 1
-            when :RPAREN
+            when :RPAREN, :RBRACK
               nesting -= 1
             when :COMMA
               break unless nesting > 0
@@ -97,4 +113,19 @@ PuppetLint.new_check(:parameter_documentation) do
 
     params
   end
+
+  # returns an array [<detected_style>, <complete match>, <param name>, <same-line-docs>]
+  # [nil, nil] if this is not a parameter.
+  def detect_style(dtok)
+    style = nil
+    case dtok.value
+    when %r{\A\s*\[\*([a-zA-Z0-9_]+)\*\]\s*(.*)\z}
+      style = 'doc'
+    when %r{\A\s*\$([a-zA-Z0-9_]+):: +(.*)\z}
+      style = 'kafo'
+    when %r{\A\s*@param (?:\[.+\] )?([a-zA-Z0-9_]+)(?: +|$)(.*)\z}
+      style = 'strings'
+    end
+    [ style, * $~ ]
+  end
 end

data/spec/puppet-lint/plugins/check_parameter_documentation_spec.rb

@@ -3,6 +3,8 @@ require 'spec_helper'
 describe 'parameter_documentation' do
   let(:class_msg) { 'missing documentation for class parameter example::%s' }
   let(:define_msg) { 'missing documentation for defined type parameter example::%s' }
+  let(:class_style_msg) { 'invalid documentation style for class parameter example::%s (%s)' }
+  let(:define_style_msg) { 'invalid documentation style for defined type parameter example::%s (%s)' }
 
   context 'class missing any documentation' do
     let(:code) { 'class example($foo) { }' }
@@ -355,6 +357,62 @@ define foreman (
     end
   end
 
+  context 'check style' do
+    let(:code) do
+      <<-EOS
+      # Example mixed style class
+      #
+      # Parameters:
+      #
+      # $foo:: example
+      #
+      # [*bar*] example
+      #
+      # @param foobar example
+      #
+      class example($foo, $bar, $foobar) { }
+      EOS
+    end
+
+    context 'detect all styles' do
+      before do
+        PuppetLint.configuration.docs_allowed_styles = ['noexist']
+      end
+      after do
+        PuppetLint.configuration.docs_allowed_styles = false
+      end
+
+      it 'should detect three problems' do
+        expect(problems).to have(3).problems
+      end
+
+      it 'should create three problems' do
+        expect(problems).to contain_warning(class_style_msg % [:foo, 'kafo']).on_line(11).in_column(21)
+        expect(problems).to contain_warning(class_style_msg % [:bar, 'doc']).on_line(11).in_column(27)
+        expect(problems).to contain_warning(class_style_msg % [:foobar, 'strings']).on_line(11).in_column(33)
+      end
+    end
+
+    context 'use configured style' do
+      before do
+        PuppetLint.configuration.docs_allowed_styles = 'strings'
+      end
+      after do
+        PuppetLint.configuration.docs_allowed_styles = nil
+      end
+
+      it 'should detect two problems' do
+        expect(problems).to have(2).problems
+      end
+
+      it 'should create three problems' do
+        expect(problems).to contain_warning(class_style_msg % [:foo, 'kafo']).on_line(11).in_column(21)
+        expect(problems).to contain_warning(class_style_msg % [:bar, 'doc']).on_line(11).in_column(27)
+      end
+    end
+  end
+
+
   context 'define with all parameters documented ($foo::)' do
     let(:code) do
       <<-EOS
@@ -855,4 +913,46 @@ define foreman (
       expect(problems).to contain_warning('Duplicate defined type parameter documentation for example::name/title').on_line(5).in_column(10)
     end
   end
+
+  context 'class with array defaults containing variables' do
+    # Example taken from https://github.com/voxpupuli/puppet-lint-param-docs/issues/30
+    let(:code) do
+      <<-EOS.gsub(/^\s+/, '')
+      # @summary example class
+      #
+      # @param parameter_1
+      # @param parameter_2
+      # @param parameter_3
+      # @param parameter_4
+      # @param parameter_5
+      # @param parameter_6
+      # @param parameter_7
+      # @param parameter_8
+      #
+      class example (
+        Array $parameter_1 = $variable1,
+        Array $parameter_2 = [ $variable2, ],
+        Array $parameter_3 = [ $variable3, 'string1', ],
+        Array $parameter_4 = [
+          $variable4,
+          'string1',
+        ],
+        Array $parameter_5 = [ $variable5, $variable6, 'string1', ],
+        Array $parameter_6 = [ $variable7, 'string1', $variable8, ],
+        Array $parameter_7 = [ 'string1', $variable9, ],
+        Array $parameter_8 = [
+          'string1',
+          $variable10,
+          'string2',
+        ],
+      ) {
+        # foo
+      }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,3 +1,26 @@
+if ENV['COVERAGE'] == 'yes'
+  require 'simplecov'
+  require 'simplecov-console'
+  require 'codecov'
+
+  SimpleCov.start do
+    track_files 'lib/**/*.rb'
+
+    add_filter '/spec'
+
+    enable_coverage :branch
+
+    # do not track vendored files
+    add_filter '/vendor'
+    add_filter '/.vendor'
+  end
+
+  SimpleCov.formatters = [
+    SimpleCov::Formatter::Console,
+    SimpleCov::Formatter::Codecov,
+  ]
+end
+
 require 'puppet-lint'
 
 PuppetLint::Plugins.load_spec_helper

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param-docs
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.5
 platform: ruby
 authors:
 - Vox Pupuli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-05 00:00:00.000000000 Z
+date: 2021-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puppet-lint
@@ -87,7 +87,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: simplecov
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: codecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -132,10 +146,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.2.22
 signing_key: 
 specification_version: 4
 summary: puppet-lint check to validate all parameters are documented
 test_files:
-- spec/spec_helper.rb
 - spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
+- spec/spec_helper.rb