(maint) Update documentation and style for puppet-lint & Rubocop

Additionally, this commit adds the Vox Beaker gem back. It was
removed when updating PDK.

.sync.yml

@@ -43,6 +43,7 @@ Gemfile:
         version: '~> 1.30' # otherwise async 2.0.0(needs ruby >=3.1.0) is wrongly selected by bundler on jenkins while running with ruby 2.7.1
     ":system_tests":
       - gem: voxpupuli-acceptance
+        version: '~> 1.0'
 appveyor.yml:
   delete: true
 .travis.yml:

Gemfile

@@ -53,7 +53,7 @@ end
 group :system_tests do
   gem "serverspec", '~> 2.41',    require: false
   gem "puppet_litmus", '~> 1.0', require: false, platforms: [:ruby, :x64_mingw]
-  gem "voxpupuli-acceptance",     require: false
+  gem "voxpupuli-acceptance", '~> 1.0'
 end
 
 puppet_version = ENV['PUPPET_GEM_VERSION']

Rakefile

@@ -6,6 +6,7 @@ require 'puppetlabs_spec_helper/rake_tasks'
 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?
+require 'voxpupuli/acceptance/rake'
 
 def changelog_user
   return unless Rake.application.top_level_tasks.include? "changelog"

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

files/rb_task_helper.rb

@@ -1,61 +1,59 @@
 # frozen_string_literal: true
 
 # Puppet Agent task helper
-module PuppetAgent
-  module RbTaskHelper
-    private
-
-    def error_result(error_type, error_message)
-      {
-        '_error' => {
-          'msg' => error_message,
-          'kind' => error_type,
-          'details' => {},
-        },
-      }
-    end
-
-    def puppet_bin_present?
-      File.exist?(puppet_bin)
-    end
-
-    # Returns the path to the Puppet agent executable
-    def puppet_bin
-      @puppet_bin ||= if Puppet.features.microsoft_windows?
-                        puppet_bin_windows
-                      else
-                        '/opt/puppetlabs/bin/puppet'
-                      end
-    end
-
-    # Returns the path to the Puppet agent executable on Windows
-    def puppet_bin_windows
-      require 'win32/registry'
-
-      install_dir = begin
-                      Win32::Registry::HKEY_LOCAL_MACHINE.open('SOFTWARE\Puppet Labs\Puppet') do |reg|
-                        # Rescue missing key
-                        dir = begin
-                                reg['RememberedInstallDir64']
-                              rescue StandardError
-                                ''
-                              end
-                        # Both keys may exist, make sure the dir exists
-                        break dir if File.exist?(dir)
-
-                        # Rescue missing key
-                        begin
-                          reg['RememberedInstallDir']
-                        rescue StandardError
-                          ''
-                        end
+module PuppetAgent::RbTaskHelper
+  private
+
+  def error_result(error_type, error_message)
+    {
+      '_error' => {
+        'msg' => error_message,
+        'kind' => error_type,
+        'details' => {},
+      },
+    }
+  end
+
+  def puppet_bin_present?
+    File.exist?(puppet_bin)
+  end
+
+  # Returns the path to the Puppet agent executable
+  def puppet_bin
+    @puppet_bin ||= if Puppet.features.microsoft_windows?
+                      puppet_bin_windows
+                    else
+                      '/opt/puppetlabs/bin/puppet'
+                    end
+  end
+
+  # Returns the path to the Puppet agent executable on Windows
+  def puppet_bin_windows
+    require 'win32/registry'
+
+    install_dir = begin
+                    Win32::Registry::HKEY_LOCAL_MACHINE.open('SOFTWARE\Puppet Labs\Puppet') do |reg|
+                      # Rescue missing key
+                      dir = begin
+                              reg['RememberedInstallDir64']
+                            rescue StandardError
+                              ''
+                            end
+                      # Both keys may exist, make sure the dir exists
+                      break dir if File.exist?(dir)
+
+                      # Rescue missing key
+                      begin
+                        reg['RememberedInstallDir']
+                      rescue StandardError
+                        ''
                       end
-                    rescue Win32::Registry::Error
-                      # Rescue missing registry path
-                      ''
                     end
+                  rescue Win32::Registry::Error
+                    # Rescue missing registry path
+                    ''
+                  end
 
-      File.join(install_dir, 'bin', 'puppet.bat')
-    end
+    File.join(install_dir, 'bin', 'puppet.bat')
   end
 end

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,5 @@
+# @summary Uses $puppet_agent::config to manage settings in puppet.conf.
+# It does not require management of the agent package.
 class puppet_agent::configure {
   assert_private()