(maint) Update documentation for voxpupuli-puppet-lint-plugins

lib/puppet/functions/any_resources_of_type.rb

@@ -1,4 +1,9 @@
+# @summary A function used to determine if there are any
+# Puppet::Parser::Resource instances of the passed in resource type
 Puppet::Functions.create_function(:any_resources_of_type, Puppet::Functions::InternalFunction) do
+  # @return [Boolean] Whether there are any instances of resource_type
+  # @param resource_type Resource type that is being looked for
+  # @param parameters Optional parameters
   dispatch :any_resources_of_type do
     scope_param
 

lib/puppet/parser/functions/uri_host_from_string.rb

@@ -2,7 +2,7 @@
 
 module Puppet::Parser::Functions
   newfunction(:uri_host_from_string, arity: 1, type: :rvalue, doc: <<-EOS
-  Return a uri host from a string
+  @return Return a uri host from a string
   EOS
   ) do |args|
     uri = URI(args[0])

lib/puppet/parser/functions/windows_msi_installargs.rb

@@ -1,6 +1,6 @@
 module Puppet::Parser::Functions
   newfunction(:windows_msi_installargs, arity: 1, type: :rvalue, doc: <<-EOS
-  Return the $install_options parameter as a string usable in an msiexec command
+  @return [String] Return the $install_options parameter as a string usable in an msiexec command
   EOS
   ) do |args|
     install_args = args[0]

lib/puppet/parser/functions/windows_native_path.rb

@@ -1,6 +1,7 @@
 module Puppet::Parser::Functions
+  # @return Windows native path
   newfunction(:windows_native_path, arity: 1, type: :rvalue, doc: <<-EOS
-  Return a windows native path
+  @return Return a windows native path
   EOS
   ) do |args|
     path = args[0]

lib/puppet/provider/puppet_agent_end_run/puppet_agent_end_run.rb

@@ -1,4 +1,6 @@
+
 Puppet::Type.type(:puppet_agent_end_run).provide :puppet_agent_end_run do
+  desc '@summary This provider will stop the puppet agent run after a Puppet upgrade is performed'
   def end_run
     false
   end

lib/puppet/provider/puppet_agent_upgrade_error/puppet_agent_upgrade_error.rb

@@ -1,4 +1,10 @@
 Puppet::Type.type(:puppet_agent_upgrade_error).provide :puppet_agent_upgrade_error do
+  desc <<-DESC
+  @summary This provider checks an error log from a previous puppet agent
+  installation and will fail if the error log exists. The provider will delete
+  the existing error log before failing so that after the failed puppet run the
+  user can attempt the upgrade again.
+  DESC
   def ensure_notexist
     logfile = File.join(Puppet['statedir'].to_s, @resource[:name])
     Puppet.debug "Checking for Error logfile #{logfile}"

manifests/configure.pp

@@ -1,3 +1,6 @@
+# @summary This class uses $puppet_agent::config to manage settings in
+# puppet.conf, and will always be present. It does not require management of
+# the agent package.
 class puppet_agent::configure {
   assert_private()
 

manifests/init.pp

@@ -4,100 +4,106 @@
 #
 # === Parameters
 #
-# [arch]
+# @param arch
 #   The package architecture. Defaults to the architecture fact.
-# [collection]
+# @param collection
 #   The Puppet Collection to track. Defaults to 'PC1'.
-# [is_pe]
+# @param is_pe
 #   Install from Puppet Enterprise repos. Enabled if communicating with a PE master.
-# [manage_pki_dir]
+# @param manage_pki_dir
 #   Whether or not to manage the /etc/pki directory.  Defaults to true.
 #   Managing the /etc/pki directory inside the puppet_agent module can be problematic for
 #   organizations that manage gpg keys and settings in other modules.
-# [manage_repo]
+# @param manage_repo
 #   Boolean to determine whether to configure repositories
 #   This is intended to provide the ability to disable configuring a local repo
 #   in support of systems that manage external repositories (i.e. spacewalk/satellite)
 #   to enable users to add the proper packages to their internal repos
 #   and to utilize default package providers for the install
-# [package_name]
+# @param package_name
 #   The package to upgrade to, i.e. `puppet-agent`.
-# [package_version]
+# @param package_version
 #   The package version to upgrade to. Explicitly specify the version to upgrade to,
 #   or set to 'auto' to specify the version of the compiling master.
-# [service_names]
+# @param service_names
 #   An array of services to start, normally `puppet`.
 #   None will be started if the array is empty.
-# [source]
+# @param source
 #   **INCLUDED FOR COMPATIBILITY WITH MODULE VERSIONS 1.0/2.0. PREFER USE OF "absolute_source",
 #   "apt_source", "deb_source" etc. OVER USE OF "source".**
 #
 #   The location to find packages. Replaces base URL for unix/MacOS agents, used as fully
 #   qualified path in windows
-# [absolute_source]
+# @param absolute_source
 #   The exact location of the package to install. The entire path to the package must be
 #   provided with this parameter.
-# [yum_source]
+# @param yum_source
 #   Base URL of the location of mirrors of yum.puppet.com downloads sites. Directories under
 #   the URL "yum_source" should match the structure of the yum.puppet.com
-# [apt_source]
+# @param apt_source
 #   Base URL of the location of mirrors of apt.puppet.com downloads sites. Directories under
 #   the URL "apt_source" should match the structure of the apt.puppet.com
-# [mac_source]
+# @param mac_source
 #   Base URL of the location of mirrors of downloads.puppet.com downloads site that serves
 #   MacOS packages. Directories under the URL "mac_source" should match the structure of the
 #   downloads.puppet.com site
-# [windows_source]
+# @param windows_source
 #   Base URL of the location of mirrors of downloads.puppet.com downloads site that serves
 #   Windows packages. Directories under the URL "windows_source" should match the structure of
 #   the downloads.puppet.com site
-# [solaris_source]
+# @param solaris_source
 #   Base URL of the location of a mirror for Solaris packages. Currently, solaris packages can
 #   only be made available by using puppetlabs-pe_repo. This means the mirror must be of a
 #   PE master package serve.
-# [aix_source]
+# @param aix_source
 #   Base URL of the location of a mirror for AIX packages. Currently, AIX packages can
 #   only be made available by using puppetlabs-pe_repo. This means the mirror must be of a
 #   PE master package serve.
-# [use_alternate_sources]
+# @param use_alternate_sources
 #   **ONLY APPLICABLE WHEN WORKING WITH PE INSTALLTIONS**
 #   When set to true will force downloads to come from the values of $apt_source, $deb_source
 #   $mac_source etc. rather than from the default PE master package serve. Note that this will
 #   also force downloads to ignore alternate_pe_source
-# [alternate_pe_source]
+# @param alternate_pe_source
 #   Base URL of the location where packages are located in the same structure that's served
 #   by a PE master (the directory structure in PE for serving packages is created by the
 #   puppetlabs-pe_repo module). The general structure served by PE is:
 #   /packages/${pe_server_version}/${platform_tag}/${package_name}
-# [install_dir]
+# @param install_dir
 #   The directory the puppet agent should be installed to. This is only applicable for
 #   windows operating systems. This only applies when upgrading the agent to a new
 #   version; it will not cause re-installation of the same version to a new location.
-# [install_options]
+# @param install_options
 #   An array of additional options to pass when installing puppet-agent. Each option in
 #   the array can either be a string or a hash. Each option will automatically be quoted
 #   when passed to the install command. With Windows packages, note that file paths in an
 #   install option must use backslashes. (Since install options are passed directly to
 #   the installation command, forward slashes won't be automatically converted like they
 #   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
 #   be escaped and backslashes in single-quoted strings _can_ be escaped.
-# [msi_move_locked_files]
+# @param msi_move_locked_files
 #   This is only applicable for Windows operating systems. There may be instances where
 #   file locks cause unncessary service restarts.  By setting to true, the module
 #   will move files prior to installation that are known to cause file locks.
-# [wait_for_pxp_agent_exit]
+# @param wait_for_pxp_agent_exit
 #   This parameter is only applicable for Windows operating systems and pertains to the 
 #   /files/install_agent.ps1 script. This parameterizes the module to define the wait time
 #   for the PXP agent to end successfully. The default value is set 2 minutes.
-# [wait_for_puppet_run]
+# @param wait_for_puppet_run
 #   This parameter is only applicable for Windows operating systems and pertains to the
 #   /files/install_agent.ps1 script. This parameterizes the module to define the wait time
 #   for the current puppet agent run to end successfully. The default value is set 2 minutes.
-# [config]
+# @param config
 #   An array of configuration data to enforce. Each configuration data item must be a
 #   Puppet_agent::Config hash, which has keys for puppet.conf section, setting, and value.
 #   This parameter is constrained to managing only a predetermined set of configuration
 #   settings, e.g. runinterval.
+# @param proxy
+#    This is to be able to configure yum-repo with proxy, needed for
+#   example for clients in dmz:s that need to use proxy to reach the repo
+#   provided by puppetserver.
+# @param skip_if_unavailable
+# @param disable_proxy
 class puppet_agent (
   $arch                    = $facts['os']['architecture'],
   $collection              = $::puppet_agent::params::collection,

manifests/install.pp

@@ -4,9 +4,19 @@
 #
 # === Parameters
 #
-# [version]
+# @param package_version
 #   The puppet-agent version to install.
-#
+# @param install_dir
+#   The directory the puppet agent should be installed to. This is only applicable for
+#   windows operating systems.
+# @param install_options
+#   An array of additional options to pass when installing puppet-agent. Each option in
+#   the array can either be a string or a hash. Each option will automatically be quoted
+#   when passed to the install command. With Windows packages, note that file paths in an
+#   install option must use backslashes. (Since install options are passed directly to
+#   the installation command, forward slashes won't be automatically converted like they
+#   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
+#   be escaped and backslashes in single-quoted strings _can_ be escaped.
 class puppet_agent::install (
   $package_version   = 'present',
   $install_dir       = undef,

manifests/install/darwin.pp

@@ -4,6 +4,18 @@
 #
 # Manage the install process for Darwin OSes specifically
 #
+# === Parameters
+#
+# @param package_version
+#   The puppet-agent version to install.
+# @param install_options
+#   An array of additional options to pass when installing puppet-agent. Each option in
+#   the array can either be a string or a hash. Each option will automatically be quoted
+#   when passed to the install command. With Windows packages, note that file paths in an
+#   install option must use backslashes. (Since install options are passed directly to
+#   the installation command, forward slashes won't be automatically converted like they
+#   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
+#   be escaped and backslashes in single-quoted strings _can_ be escaped.
 class puppet_agent::install::darwin (
   $package_version,
   $install_options = [],

manifests/install/solaris.pp

@@ -4,6 +4,18 @@
 #
 # Manage the install process for solaris specifically
 #
+# === Parameters
+#
+# @param package_version
+#   The puppet-agent version to install.
+# @param install_options
+#   An array of additional options to pass when installing puppet-agent. Each option in
+#   the array can either be a string or a hash. Each option will automatically be quoted
+#   when passed to the install command. With Windows packages, note that file paths in an
+#   install option must use backslashes. (Since install options are passed directly to
+#   the installation command, forward slashes won't be automatically converted like they
+#   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
+#   be escaped and backslashes in single-quoted strings _can_ be escaped.
 class puppet_agent::install::solaris (
   $package_version,
   $install_options = [],

manifests/install/suse.pp

@@ -4,6 +4,18 @@
 #
 # Manage the install process for SUSE OSes specifically
 #
+# === Parameters
+#
+# @param package_version
+#   The puppet-agent version to install.
+# @param install_options
+#   An array of additional options to pass when installing puppet-agent. Each option in
+#   the array can either be a string or a hash. Each option will automatically be quoted
+#   when passed to the install command. With Windows packages, note that file paths in an
+#   install option must use backslashes. (Since install options are passed directly to
+#   the installation command, forward slashes won't be automatically converted like they
+#   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
+#   be escaped and backslashes in single-quoted strings _can_ be escaped.
 class puppet_agent::install::suse (
   $package_version,
   $install_options = [],

manifests/install/windows.pp

@@ -4,6 +4,19 @@
 #
 # Manage the install process for windows specifically
 #
+# === Parameters
+#
+# @param install_options
+#   An array of additional options to pass when installing puppet-agent. Each option in
+#   the array can either be a string or a hash. Each option will automatically be quoted
+#   when passed to the install command. With Windows packages, note that file paths in an
+#   install option must use backslashes. (Since install options are passed directly to
+#   the installation command, forward slashes won't be automatically converted like they
+#   are in `file` resources.) Note also that backslashes in double-quoted strings _must_
+#   be escaped and backslashes in single-quoted strings _can_ be escaped.
+# @param install_dir
+#   The directory the puppet agent should be installed to. This is only applicable for
+#   windows operating systems.
 class puppet_agent::install::windows (
   $install_dir           = undef,
   $install_options       = [],

manifests/osfamily/aix.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for AIX OSes
 class puppet_agent::osfamily::aix {
   assert_private()
 

manifests/osfamily/darwin.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for Darwin OSes
 class puppet_agent::osfamily::darwin {
   assert_private()
 

manifests/osfamily/debian.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for Debain OSes
 class puppet_agent::osfamily::debian {
   assert_private()
 

manifests/osfamily/redhat.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for RedHat OSes
 class puppet_agent::osfamily::redhat {
   assert_private()
 

manifests/osfamily/solaris.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for Solaris OSes
 class puppet_agent::osfamily::solaris {
   assert_private()
 

manifests/osfamily/suse.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for SUSE OSes
 class puppet_agent::osfamily::suse {
   assert_private()
 

manifests/osfamily/windows.pp

@@ -1,3 +1,5 @@
+# @summary This private class is used to determine the puppet-agent package
+# location for Windows OSes
 class puppet_agent::osfamily::windows {
   assert_private()
 

manifests/prepare.pp

@@ -4,9 +4,8 @@
 #
 # === Parameters
 #
-# [version]
+# @param package_version
 #   The puppet-agent version to install.
-#
 class puppet_agent::prepare (
   $package_version = undef
 ) {

manifests/prepare/package.pp

@@ -4,9 +4,9 @@
 # package is downloaded locally for installation.  This is used on platforms
 # without package managers capable of working with a remote https repository.
 #
-# [package_file_name]
-#   The puppet-agent package file to retrieve from the master.
+# === Parameters
 #
+# @param source
 class puppet_agent::prepare::package (
   $source,
 ) {

manifests/prepare/puppet_config.pp

@@ -2,6 +2,10 @@
 #
 # Private class called from puppet_agent::prepare class
 #
+# === Parameters
+#
+# @param package_version
+#   The puppet-agent version to install.
 class puppet_agent::prepare::puppet_config (
   $package_version,
 ) {

types/arch.pp

@@ -1 +1,2 @@
+# @summary This type stores all possible architecture patterns
 type Puppet_agent::Arch = Pattern[/^x86$/,/^x64$/,/^i386$/,/^i86pc$/,/^amd64$/,/^x86_64$/,/^power$/,/^sun4[uv]$/, /^ppc64le$/, /^aarch64$/, /PowerPC_POWER/]

types/config.pp

@@ -1,3 +1,4 @@
+# @summary This Puppet type alias 
 type Puppet_agent::Config = Variant[Struct[{ section          => Enum[main, server, agent, user, master],
                                             setting          => Puppet_agent::Config_setting,
                                             value            => String,