Adds a new puppet-lint check to verify all class and defined type parameters have been documented.
Particularly useful with kafo, as its default behaviour is to throw an error when a parameter is undocumented.
To use this plugin, add the following line to the Gemfile in your Puppet code
base and run bundle install
.
gem 'puppet-lint-param-docs'
This plugin provides a new check to puppet-lint
.
--fix support: No
This check will raise a warning for any class or defined type parameters that don't have a description.
WARNING: missing documentation for class parameter foo::bar
WARNING: missing documentation for defined type parameter foo::baz
It will also raise warnings for parameters documented more than once.
WARNING Duplicate class parameter documentation for foo::bar on line 5
WARNING Duplicate class parameter documentation for foo::bar on line 6
A warning will also be raised if you document a parameter that doesn't exist in the class or defined type.
WARNING No matching class parameter for documentation of foo::bar
The check will accept any of the following styles:
Used by Puppet Strings.
# @summary Example class
#
# @param foo example
define example($foo) { }
Used by the puppet-doc command, deprecated in favour of Puppet Strings.
# Example class
#
# === Parameters:
#
# [*foo*] example
#
class example($foo) { }
Used in kafo following an rdoc style.
# Example class
#
# === Parameters:
#
# $foo:: example
#
class example($foo) { }
The usual puppet-lint rake task checks all manifests, which isn't always desirable with this particular check. If your module contains many classes, some of which you don't wish to document, then you can exclude them using control comments 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
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 @api private
directive can also be used
to disable checks on that file.