(maint) Update documentation and format/style for puppet-lint

Rakefile

@@ -7,6 +7,10 @@ require 'puppet-syntax/tasks/puppet-syntax'
 require 'github_changelog_generator/task' if Bundler.rubygems.find_name('github_changelog_generator').any?
 require 'puppet-strings/tasks' if Bundler.rubygems.find_name('puppet-strings').any?
 
+# puppet-lint-top_scope_facts assumes all top scope variables are facts.
+# This configures the check to ignore all top scope variables listed in []
+PuppetLint.configuration.top_scope_variables = ['platform_tag']
+
 def changelog_user
   return unless Rake.application.top_level_tasks.include? "changelog"
   returnVal = nil || JSON.load(File.read('metadata.json'))['author']

docker/upgrade.pp

@@ -1,5 +1,5 @@
 node default {
-  class { '::puppet_agent':
+  class { 'puppet_agent':
     package_version => $facts['to_version'],
     # Upgrades in Docker cannot start the puppet service due to systemd
     # incompatibilities. Essentially, Docker expects an init system for

examples/init.pp

@@ -9,4 +9,4 @@
 # Learn more about module testing here:
 # http://docs.puppetlabs.com/guides/tests_smoke.html
 #
-include ::puppet_agent
+include puppet_agent

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,130 +4,138 @@
 #
 # === 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 version_file_path
+#    The default install path for the VERSION file
+# @param skip_if_unavailable
+# @param disable_proxy
 class puppet_agent (
-  $arch                    = $facts['os']['architecture'],
-  $collection              = $::puppet_agent::params::collection,
-  $is_pe                   = $::puppet_agent::params::_is_pe,
-  $manage_pki_dir          = true,
-  $manage_repo             = true,
-  $package_name            = 'puppet-agent',
-  $package_version         = undef,
-  $service_names           = $::puppet_agent::params::service_names,
-  $source                  = undef,
-  $absolute_source         = undef,
-  $yum_source              = 'http://yum.puppet.com',
-  $apt_source              = 'https://apt.puppet.com',
-  $mac_source              = 'https://downloads.puppet.com',
-  $windows_source          = 'https://downloads.puppet.com',
-  $solaris_source          = 'puppet:///pe_packages',
-  $aix_source              = 'puppet:///pe_packages',
-  $use_alternate_sources   = false,
-  $alternate_pe_source     = undef,
-  Optional[Stdlib::Absolutepath] $install_dir = undef,
-  $disable_proxy           = false,
-  $proxy                   = undef,
-  $install_options         = [],
-  $skip_if_unavailable     = 'absent',
-  $msi_move_locked_files   = false,
-  $wait_for_pxp_agent_exit = undef,
-  $wait_for_puppet_run     = undef,
-  Array[Puppet_agent::Config] $config = [],
-  $version_file_path       = $facts['os']['family'] ? { 'windows' => "${facts['env_windows_installdir']}\\VERSION", default => '/opt/puppetlabs/puppet/VERSION' }
-) inherits ::puppet_agent::params {
+  String                         $arch                    = $facts['os']['architecture'],
+  String                         $collection              = $puppet_agent::params::collection,
+  Boolean                        $is_pe                   = $puppet_agent::params::_is_pe,
+  Boolean                        $manage_pki_dir          = true,
+  Boolean                        $manage_repo             = true,
+  String                         $package_name            = 'puppet-agent',
+  Optional                       $package_version         = undef,
+  Array                          $service_names           = $puppet_agent::params::service_names,
+  Optional                       $source                  = undef,
+  Optional                       $absolute_source         = undef,
+  String                         $yum_source              = 'http://yum.puppet.com',
+  String                         $apt_source              = 'https://apt.puppet.com',
+  String                         $mac_source              = 'https://downloads.puppet.com',
+  String                         $windows_source          = 'https://downloads.puppet.com',
+  String                         $solaris_source          = 'puppet:///modules/pe_packages',
+  String                         $aix_source              = 'puppet:///modules/pe_packages',
+  Boolean                        $use_alternate_sources   = false,
+  Optional                       $alternate_pe_source     = undef,
+  Optional[Stdlib::Absolutepath] $install_dir             = undef,
+  Boolean                        $disable_proxy           = false,
+  Optional                       $proxy                   = undef,
+  Array                          $install_options         = [],
+  String                         $skip_if_unavailable     = 'absent',
+  Boolean                        $msi_move_locked_files   = false,
+  Optional                       $wait_for_pxp_agent_exit = undef,
+  Optional                       $wait_for_puppet_run     = undef,
+  Array[Puppet_agent::Config]    $config                  = [],
+  String                         $version_file_path       = $facts['os']['family'] ? { 'windows' => "${facts['env_windows_installdir']}\\VERSION", default => '/opt/puppetlabs/puppet/VERSION' }
+) inherits puppet_agent::params {
   # The configure 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. Dependencies for configure will be declared later if the
@@ -193,14 +201,14 @@
       $aio_upgrade_required = false
       $aio_downgrade_required = false
     } else {
-      $aio_upgrade_required = versioncmp($::aio_agent_version, $_expected_package_version) < 0
-      $aio_downgrade_required = versioncmp($::aio_agent_version, $_expected_package_version) > 0
+      $aio_upgrade_required = versioncmp($facts['aio_agent_version'], $_expected_package_version) < 0
+      $aio_downgrade_required = versioncmp($facts['aio_agent_version'], $_expected_package_version) > 0
     }
 
     if $aio_upgrade_required {
       if any_resources_of_type('filebucket', { path => false }) {
-        if $settings::digest_algorithm != $::puppet_digest_algorithm {
-          fail("Remote filebuckets are enabled, but there was a agent/server digest algorithm mismatch. Server: ${settings::digest_algorithm}, agent: ${::puppet_digest_algorithm}. Either ensure the algorithms are matching, or disable remote filebuckets during the upgrade.")
+        if $settings::digest_algorithm != $facts['puppet_digest_algorithm'] {
+          fail("Remote filebuckets are enabled, but there was a agent/server digest algorithm mismatch. Server: ${settings::digest_algorithm}, agent: ${facts['puppet_digest_algorithm']}. Either ensure the algorithms are matching, or disable remote filebuckets during the upgrade.")
         }
       }
     }
@@ -214,10 +222,10 @@
       $_package_version = $master_or_package_version
     }
 
-    class { '::puppet_agent::prepare':
+    class { 'puppet_agent::prepare':
       package_version => $_package_version,
     }
-    class { '::puppet_agent::install':
+    class { 'puppet_agent::install':
       package_version => $_package_version,
       install_dir     => $install_dir,
       install_options => $install_options,
@@ -232,7 +240,7 @@
     # - On Windows, services are handled by the puppet-agent MSI packages themselves.
     # ...but outside of PE, on other platforms, we must make sure the services are restarted. We do that with the
     # ::puppet_agent::service class. Make sure it's applied after the install process finishes if needed:
-    if $facts['os']['family'] != 'windows' and (!$is_pe or versioncmp($::clientversion, '4.0.0') < 0) {
+    if $facts['os']['family'] != 'windows' and (!$is_pe or versioncmp($facts['clientversion'], '4.0.0') < 0) {
       Class['puppet_agent::configure']
       ~> contain('puppet_agent::service')
     }