puppet-lint-param-docs 1.3.1 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8b74b2eba1bf2552829262b8cbbb7ec77de00457
-  data.tar.gz: 072f70beee8e599b8b50e8a26aa9f848eb1faa9a
+SHA256:
+  metadata.gz: 14633dfc2336826ed35662bf1840e6ef992f0032146f2a932a988a42521b2006
+  data.tar.gz: 9f7a4139402ebe4d390f07b38ed5013e4f10b42bf3e793d8b6a4e05c170d25c6
 SHA512:
-  metadata.gz: 368cea9c49874b060719f7663aba531515435777be4185112cc22dd0c767d9ca234f2533c0ac40d486f69947fecdcb9d01cc05a73ddb737a1c1eac96cb0bd84f
-  data.tar.gz: d97334cb071b50f732b785b6b068e02fb486248149209d1e5fdcd82ddc14a7d2e47b4aae0c70f13fc7460868bef2c6bc1ba49e0d83967b945b548661e5a36d28
+  metadata.gz: 9c685fe25b7b03c9af645f2ff82ea4c86e3c820ce3343c16b4a8926be097a0e3fa4723910a7f5c71e555978101dc61a0739f6496abcae8eea2ca4296a8a3ec14
+  data.tar.gz: d696ad85c260c8956787f27a3af8b37a8b26526b57d789f005881ae89de538241fbaa7daca6ad03abd6e0576db71a306c1227f8b3cecb226dc4cd44d18a7927e

data/README.md

@@ -31,6 +31,45 @@ WARNING: missing documentation for class parameter foo::bar
 WARNING: missing documentation for defined type parameter foo::baz
 ```
 
+### Documentation styles
+
+The check will accept any of the following styles:
+
+#### Puppet Strings
+
+Used by [Puppet Strings](https://github.com/puppetlabs/puppetlabs-strings).
+
+    # Example class
+    #
+    # @param foo example
+    define example($foo) { }
+
+#### Puppet Doc style
+
+Used by the [puppet-doc](https://docs.puppetlabs.com/puppet/latest/reference/man/doc.html)
+command, generally deprecated in favour of Puppet Strings.
+
+    # Example class
+    #
+    # === Parameters:
+    #
+    # [*foo*] example
+    #
+    class example($foo) { }
+
+#### Kafo rdoc style
+
+Used in [kafo](https://github.com/theforeman/kafo#documentation) following an
+rdoc style.
+
+    # Example class
+    #
+    # === Parameters:
+    #
+    # $foo:: example
+    #
+    class example($foo) { }
+
 ### Selective rake task
 
 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
 [control comments](http://puppet-lint.com/controlcomments/) or by using this
 helper to customise the lint rake task:
 
-  require 'puppet-lint-param-docs/tasks'
-  PuppetLintParamDocs.define_selective do |config|
-    config.pattern = ['manifests/init.pp', 'manifests/other/**/*.pp']
-  end
+    require 'puppet-lint-param-docs/tasks'
+    PuppetLintParamDocs.define_selective do |config|
+      config.pattern = ['manifests/init.pp', 'manifests/other/**/*.pp']
+    end
 
 This would disable the parameter_documentation check by default, but then
 defines a new rake task (which runs after `lint`) specifically for the files
 given in `config.pattern`.
+
+The [Puppet Strings](#puppet_strings) `@api private` directive can also be used
+to disable checks on that file.

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

@@ -4,28 +4,42 @@ PuppetLint.new_check(:parameter_documentation) do
       next if idx[:param_tokens].nil?
 
       doc_params = []
+      is_private = false
       tokens[0..idx[:start]].reverse_each do |dtok|
         next if [:CLASS, :DEFINE, :NEWLINE, :WHITESPACE, :INDENT].include?(dtok.type)
         if [:COMMENT, :MLCOMMENT, :SLASH_COMMENT].include?(dtok.type)
           if dtok.value =~ /\A\s*\[\*([a-zA-Z0-9_]+)\*\]/ or
-             dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+):: +/
+             dtok.value =~ /\A\s*\$([a-zA-Z0-9_]+):: +/ or
+             dtok.value =~ /\A\s*@param (?:\[.+\] )?([a-zA-Z0-9_]+)(?: +|$)/
             doc_params << $1
           end
+
+          is_private = true if dtok.value =~ /\A\s*@api +private\s*$/
         else
           break
         end
       end
 
+      next if is_private
+
       params = []
       e = idx[:param_tokens].each
       begin
         while (ptok = e.next)
           if ptok.type == :VARIABLE
             params << ptok
+            nesting = 0
             # skip to the next parameter to avoid finding default values of variables
             while true
               ptok = e.next
-              break if ptok.type == :COMMA
+              case ptok.type
+              when :LPAREN
+                nesting += 1
+              when :RPAREN
+                nesting -= 1
+              when :COMMA
+                break unless nesting > 0
+              end
             end
           end
         end

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

@@ -52,6 +52,18 @@ describe 'parameter_documentation' do
     end
   end
 
+  context 'define with param defaults using a function' do
+    let(:code) { 'define example($foo = min(8, $facts["processors"]["count"])) { }' }
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      expect(problems).to contain_warning(define_msg % :foo).on_line(1).in_column(16)
+    end
+  end
+
   context 'class with many param defaults' do
     let(:code) do
       <<-EOS
@@ -130,6 +142,65 @@ define foreman (
     end
   end
 
+  context 'class missing documentation (@param bar) for a parameter' do
+    let(:code) do
+      <<-EOS.gsub(/^\s+/, '')
+      # Example class
+      #
+      # @param bar example
+      class example($foo, $bar) { }
+      EOS
+    end
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      expect(problems).to contain_warning(class_msg % :foo).on_line(4).in_column(15)
+    end
+  end
+
+  context 'private class missing documentation (@param bar) for a parameter' do
+    let(:code) do
+      <<-EOS.gsub(/^\s+/, '')
+      # Example class
+      #
+      # @api private
+      #
+      # @param bar example
+      class example($foo, $bar) { }
+      EOS
+    end
+
+    it 'should detect no single problems' do
+      expect(problems).to have(0).problems
+    end
+
+    it 'should not create a warning' do
+      expect(problems).not_to contain_info(class_msg % :foo)
+    end
+  end
+
+  context 'define missing documentation (@param bar) for a parameter' do
+    let(:code) do
+      <<-EOS.gsub(/^\s+/, '')
+      # Example class
+      #
+      # @param bar example
+      define example($foo, $bar) { }
+      EOS
+    end
+
+    it 'should detect a single problem' do
+      expect(problems).to have(1).problem
+    end
+
+    it 'should create a warning' do
+      expect(problems).to contain_warning(define_msg % :foo).on_line(4).in_column(16)
+    end
+  end
+
   context 'class missing documentation ([*bar*]) for a parameter' do
     let(:code) do
       <<-EOS.gsub(/^\s+/, '')
@@ -338,6 +409,88 @@ define foreman (
     end
   end
 
+  context 'class with all parameters documented (@param)' do
+    let(:code) do
+      <<-EOS
+      # Example class
+      #
+      # === Parameters:
+      #
+      # @param foo example
+      # @param [Integer] bar example
+      # @param baz
+      #   example
+      # @param [Integer] qux
+      #   example
+      #
+      class example($foo, $bar, $baz, $qux) { }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'define with all parameters documented (@param)' do
+    let(:code) do
+      <<-EOS
+      # Example define
+      #
+      # === Parameters:
+      #
+      # @param foo example
+      # @param [Integer] bar example
+      # @param baz
+      #   example
+      # @param [Integer] qux
+      #   example
+      #
+      define example($foo, $bar, $baz, $qux) { }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'define with all parameters documented with defaults (@param)' do
+    let(:code) do
+      <<-EOS
+      # Example define
+      #
+      # @param foo example
+      #
+      define example($foo = $facts['networking']['fqdn']) { }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
+  context 'define with all parameters documented with defaults using functions (@param)' do
+    let(:code) do
+      <<-EOS
+      # Example define
+      #
+      # @param foo example
+      # @param multiple test nested function calls
+      #
+      define example(
+        $foo = min(8, $facts['processors']['count']),
+        $multiple = min(8, max(2, $facts['processors']['count'])),
+      ) { }
+      EOS
+    end
+
+    it 'should not detect any problems' do
+      expect(problems).to have(0).problems
+    end
+  end
+
   context 'class without parameters' do
     let(:code) { 'class example { }' }
 

metadata

@@ -1,88 +1,107 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param-docs
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.5.1
 platform: ruby
 authors:
-- Dominic Cleal
+- Vox Pupuli
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-02 00:00:00.000000000 Z
+date: 2020-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puppet-lint
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rspec-its
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rspec-collection_matchers
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rake
   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: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: |2
-      A new check for puppet-lint that validates all parameters are documented.
-email: dcleal@redhat.com
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "    A new check for puppet-lint that validates all parameters are documented.\n"
+email: voxpupuli@groups.io
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -94,7 +113,7 @@ files:
 - lib/puppet-lint/plugins/check_parameter_documentation.rb
 - spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
 - spec/spec_helper.rb
-homepage: https://github.com/domcleal/puppet-lint-param-docs
+homepage: https://github.com/voxpupuli/puppet-lint-param-docs
 licenses:
 - MIT
 metadata: {}
@@ -104,20 +123,20 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.4
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: puppet-lint check to validate all parameters are documented
 test_files:
-- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb
 - spec/spec_helper.rb
+- spec/puppet-lint/plugins/check_parameter_documentation_spec.rb