puppet-lint-param-docs 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8b74b2eba1bf2552829262b8cbbb7ec77de00457
-  data.tar.gz: 072f70beee8e599b8b50e8a26aa9f848eb1faa9a
+  metadata.gz: 1cd697d0feb34c823acfdb9c02da8dc0c51e79e3
+  data.tar.gz: 208239c0f29443cd62bb57e6a1dd39e08baec929
 SHA512:
-  metadata.gz: 368cea9c49874b060719f7663aba531515435777be4185112cc22dd0c767d9ca234f2533c0ac40d486f69947fecdcb9d01cc05a73ddb737a1c1eac96cb0bd84f
-  data.tar.gz: d97334cb071b50f732b785b6b068e02fb486248149209d1e5fdcd82ddc14a7d2e47b4aae0c70f13fc7460868bef2c6bc1ba49e0d83967b945b548661e5a36d28
+  metadata.gz: a6009a3d8e57ecfa4979efc2e403a0c0392a9023f201e0bd1efe1cda86de02c9a6edd6c3bfec28dd010fe4e3e10ff94166d40cabd8b37f796ba23ece61b25f77
+  data.tar.gz: 7ded50a856ce0bd2c0e07e8c2b85172204bdb275592c8d5d06ff29280e24e9e56ea80a9cacf9bf0082fa906c51946eff2cad13e8f05314aef295f420d3fce7b5

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,10 +78,10 @@ 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

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

@@ -8,7 +8,8 @@ PuppetLint.new_check(:parameter_documentation) do
         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
         else

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

@@ -130,6 +130,44 @@ 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 '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+/, '')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-lint-param-docs
 version: !ruby/object:Gem::Version
-  version: 1.3.1
+  version: 1.4.0
 platform: ruby
 authors:
 - Dominic Cleal
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-02 00:00:00.000000000 Z
+date: 2016-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puppet-lint