use more specific data types

Also includes some corrections to documentation.

Author: kenyon

REFERENCE.md

@@ -12,12 +12,12 @@
 #   - Ubuntu: 'http://archive.ubuntu.com/ubuntu'
 #
 # @param release
-#   Specifies a distribution of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file.
+#   Specifies a distribution of the Apt repository containing the backports to manage. Used in populating the `sources.list` configuration file.
 #   Default: on Debian and Ubuntu, `${fact('os.distro.codename')}-backports`. We recommend keeping this default, except on other operating
 #   systems.
 #
 # @param repos
-#   Specifies a component of the Apt repository containing the backports to manage. Used in populating the `source.list` configuration file.
+#   Specifies a component of the Apt repository containing the backports to manage. Used in populating the `sources.list` configuration file.
 #   Default value for Debian and Ubuntu varies:
 #
 #   - Debian: 'main contrib non-free'
@@ -41,13 +41,13 @@
 #   Specifies whether to include 'deb' or 'src', or both.
 #
 class apt::backports (
-  Optional[String] $location                    = undef,
-  Optional[String] $release                     = undef,
-  Optional[String] $repos                       = undef,
-  Optional[Variant[String, Hash]] $key          = undef,
-  Stdlib::AbsolutePath $keyring                 = "/usr/share/keyrings/${facts['os']['name'].downcase}-archive-keyring.gpg",
-  Variant[Integer, String, Hash] $pin           = 200,
-  Variant[Hash] $include                        = {},
+  Optional[Stdlib::HTTPUrl] $location = undef,
+  Optional[String[1]] $release = undef,
+  Optional[String[1]] $repos = undef,
+  Optional[Variant[String[1], Hash]] $key = undef,
+  Stdlib::AbsolutePath $keyring = "/usr/share/keyrings/${facts['os']['name'].downcase}-archive-keyring.gpg",
+  Variant[Integer, String[1], Hash] $pin = 200,
+  Hash $include = {},
 ) {
   include apt
 

manifests/backports.pp

@@ -4,20 +4,20 @@
 #   Required unless `ensure` is set to 'absent'. Directly supplies content for the configuration file.
 #
 # @param ensure
-#    Specifies whether the configuration file should exist. Valid options: 'present' and 'absent'. 
+#    Specifies whether the configuration file should exist.
 #
 # @param priority
-#   Determines the order in which Apt processes the configuration file. Files with lower priority numbers are loaded first. 
+#   Determines the order in which Apt processes the configuration file. Files with lower priority numbers are loaded first.
 #   Valid options: a string containing an integer or an integer.
 #
 # @param notify_update
 #   Specifies whether to trigger an `apt-get update` run.
 #
 define apt::conf (
-  Optional[String] $content          = undef,
-  Enum['present', 'absent'] $ensure  = present,
-  Variant[String, Integer] $priority = 50,
-  Optional[Boolean] $notify_update   = undef,
+  Optional[String[1]] $content = undef,
+  Enum['present', 'absent'] $ensure = present,
+  Variant[String[1], Integer[0]] $priority = 50,
+  Optional[Boolean] $notify_update = undef,
 ) {
   unless $ensure == 'absent' {
     unless $content {

manifests/conf.pp

@@ -174,11 +174,11 @@
     'deb' => true,
     'src' => false,
   },
-  String $provider = '/usr/bin/apt-get',
-  String $keyserver = 'keyserver.ubuntu.com',
-  Optional[String] $key_options = undef,
-  Optional[Array[String]] $ppa_options = undef,
-  Optional[String] $ppa_package = undef,
+  Stdlib::Absolutepath $provider = '/usr/bin/apt-get',
+  Stdlib::Host $keyserver = 'keyserver.ubuntu.com',
+  Optional[String[1]] $key_options = undef,
+  Optional[Array[String[1]]] $ppa_options = undef,
+  Optional[String[1]] $ppa_package = undef,
   Optional[Hash] $backports = undef,
   Hash $confs = {},
   Hash $update = {},
@@ -192,14 +192,14 @@
   Hash $settings = {},
   Boolean $manage_auth_conf = true,
   Array[Apt::Auth_conf_entry] $auth_conf_entries = [],
-  String $auth_conf_owner = '_apt',
-  String $root = '/etc/apt',
-  String $sources_list = "${root}/sources.list",
-  String $sources_list_d = "${root}/sources.list.d",
-  String $conf_d = "${root}/apt.conf.d",
-  String $preferences = "${root}/preferences",
-  String $preferences_d = "${root}/preferences.d",
-  String $apt_conf_d = "${root}/apt.conf.d",
+  String[1] $auth_conf_owner = '_apt',
+  Stdlib::Absolutepath $root = '/etc/apt',
+  Stdlib::Absolutepath $sources_list = "${root}/sources.list",
+  Stdlib::Absolutepath $sources_list_d = "${root}/sources.list.d",
+  Stdlib::Absolutepath $conf_d = "${root}/apt.conf.d",
+  Stdlib::Absolutepath $preferences = "${root}/preferences",
+  Stdlib::Absolutepath $preferences_d = "${root}/preferences.d",
+  Stdlib::Absolutepath $apt_conf_d = "${root}/apt.conf.d",
   Hash $config_files = {
     'conf'   => {
       'path' => $conf_d,

manifests/init.pp

@@ -1,6 +1,6 @@
-# @summary Manages the GPG keys that Apt uses to authenticate packages. 
+# @summary Manages the GPG keys that Apt uses to authenticate packages.
 #
-# @note 
+# @note
 #   The apt::key defined type makes use of the apt_key type, but includes extra functionality to help prevent duplicate keys.
 #
 # @example Declare Apt key for apt.puppetlabs.com source
@@ -11,38 +11,39 @@
 #   }
 #
 # @param id
-#   Specifies a GPG key to authenticate Apt package signatures. Valid options: a string containing a key ID (8 or 16 hexadecimal 
+#   Specifies a GPG key to authenticate Apt package signatures. Valid options: a string containing a key ID (8 or 16 hexadecimal
 #   characters, optionally prefixed with "0x") or a full key fingerprint (40 hexadecimal characters).
 #
 # @param ensure
-#   Specifies whether the key should exist. Valid options: 'present', 'absent' or 'refreshed'. Using 'refreshed' will make keys auto
-#   update when they have expired (assuming a new key exists on the key server).
+#   Specifies whether the key should exist. Using `refreshed` will make keys
+#   auto update when they have expired (assuming a new key exists on the key
+#   server).
 #
 # @param content
 #   Supplies the entire GPG key. Useful in case the key can't be fetched from a remote location and using a file resource is inconvenient.
 #
 # @param source
-#   Specifies the location of an existing GPG key file to copy. Valid options: a string containing a URL (ftp://, http://, or https://) or 
+#   Specifies the location of an existing GPG key file to copy. Valid options: a string containing a URL (ftp://, http://, or https://) or
 #   an absolute path.
 #
 # @param server
 #   Specifies a keyserver to provide the GPG key. Valid options: a string containing a domain name or a full URL (http://, https://,
 #   hkp:// or hkps://). The hkps:// protocol is currently only supported on Ubuntu 18.04.
 #
 # @param weak_ssl
-#    Specifies whether strict SSL verification on a https URL should be disabled. Valid options: true or false.
+#    Specifies whether strict SSL verification on a https URL should be disabled.
 #
 # @param options
 #   Passes additional options to `apt-key adv --keyserver-options`.
 #
 define apt::key (
   Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/, /\A(0x)?[0-9a-fA-F]{16}\Z/, /\A(0x)?[0-9a-fA-F]{40}\Z/] $id                        = $title,
   Enum['present', 'absent', 'refreshed'] $ensure                                                                        = present,
-  Optional[String] $content                                                                                             = undef,
+  Optional[String[1]] $content                                                                                          = undef,
   Optional[Pattern[/\Ahttps?:\/\//, /\Aftp:\/\//, /\A\/\w+/]] $source                                                   = undef,
   Pattern[/\A((hkp|hkps|http|https):\/\/)?([a-z\d])([a-z\d-]{0,61}\.)+[a-z\d]+(:\d{2,5})?(\/[a-zA-Z\d\-_.]+)*\/?$/] $server = $apt::keyserver,
   Boolean $weak_ssl                                                                                                     = false,
-  Optional[String] $options                                                                                             = $apt::key_options,
+  Optional[String[1]] $options                                                                                          = $apt::key_options,
 ) {
   case $ensure {
     /^(refreshed|present)$/: {

manifests/key.pp

@@ -1,8 +1,7 @@
 # @summary Manages apt-mark settings
 #
 # @param setting
-#   auto, manual, hold, unhold
-#   specifies the behavior of apt in case of no more dependencies installed
+#   Specifies the behavior of apt in case of no more dependencies installed
 #   https://manpages.debian.org/stable/apt/apt-mark.8.en.html
 #
 define apt::mark (

manifests/mark.pp

@@ -1,9 +1,9 @@
 # @summary Manages Apt pins. Does not trigger an apt-get update run.
 #
-# @see http://linux.die.net/man/5/apt_preferences for context on these parameters
+# @see https://manpages.debian.org/stable/apt/apt_preferences.5.en.html for context on these parameters
 #
 # @param ensure
-#   Specifies whether the pin should exist. Valid options: 'file', 'present', and 'absent'.
+#   Specifies whether the pin should exist.
 #
 # @param explanation
 #   Supplies a comment to explain the pin. Default: "${caller_module_name}: ${name}".
@@ -15,8 +15,8 @@
 #   Specifies which package(s) to pin.
 #
 # @param priority
-#   Sets the priority of the package. If multiple versions of a given package are available, `apt-get` installs the one with the highest 
-#   priority number (subject to dependency constraints). Valid options: an integer.
+#   Sets the priority of the package. If multiple versions of a given package are available, `apt-get` installs the one with the highest
+#   priority number (subject to dependency constraints).
 #
 # @param release
 #   Tells APT to prefer packages that support the specified release. Typical values include 'stable', 'testing', and 'unstable'.
@@ -34,28 +34,28 @@
 #   Names the label of the packages in the directory tree of the Release file.
 #
 # @param origin
-#   The package origin
+#   The package origin (the hostname part of the package's sources.list entry)
 #
 # @param version
 #   The version of the package
 #
 # @param codename
-#   The codename of the package
+#   The codename of the release
 #
 define apt::pin (
   Enum['file', 'present', 'absent'] $ensure = present,
-  Optional[String] $explanation             = undef,
-  Variant[Integer] $order                   = 50,
-  Variant[String, Array] $packages          = '*',
-  Variant[Numeric, String] $priority        = 0,
-  Optional[String] $release                 = undef, # a=
-  Optional[String] $origin                  = undef,
-  Optional[String] $version                 = undef,
-  Optional[String] $codename                = undef, # n=
-  Optional[String] $release_version         = undef, # v=
-  Optional[String] $component               = undef, # c=
-  Optional[String] $originator              = undef, # o=
-  Optional[String] $label                   = undef,  # l=
+  Optional[String[1]] $explanation = undef,
+  Variant[Integer[0]] $order = 50,
+  Variant[String[1], Array[String[1]]] $packages = '*',
+  Variant[Integer, String[1]] $priority = 0,
+  Optional[String[1]] $release = undef, # a=
+  Optional[String[1]] $origin = undef,
+  Optional[String[1]] $version = undef,
+  Optional[String[1]] $codename = undef, # n=
+  Optional[String[1]] $release_version = undef, # v=
+  Optional[String[1]] $component = undef, # c=
+  Optional[String[1]] $originator = undef, # o=
+  Optional[String[1]] $label = undef, # l=
 ) {
   if $explanation {
     $_explanation = $explanation

manifests/pin.pp

@@ -1,13 +1,13 @@
 # @summary Manages PPA repositories using `add-apt-repository`. Not supported on Debian.
 #
-# @example Example declaration of an Apt PPA
-#   apt::ppa{ 'ppa:openstack-ppa/bleeding-edge': }
+# @example Declaration of an Apt PPA
+#   apt::ppa { 'ppa:openstack-ppa/bleeding-edge': }
 #
 # @param ensure
-#   Specifies whether the PPA should exist. Valid options: 'present' and 'absent'.
+#   Specifies whether the PPA should exist.
 #
 # @param options
-#   Supplies options to be passed to the `add-apt-repository` command. Default: '-y'.
+#   Supplies options to be passed to the `add-apt-repository` command.
 #
 # @param release
 #   Specifies the operating system of your node. Valid options: a string containing a valid LSB distribution codename.
@@ -18,17 +18,17 @@
 #   Optional if `puppet facts show os.name` returns your correct distribution name.
 #
 # @param package_name
-#   Names the package that provides the `apt-add-repository` command. Default: 'software-properties-common'.
+#   Names the package that provides the `apt-add-repository` command.
 #
 # @param package_manage
 #   Specifies whether Puppet should manage the package that provides `apt-add-repository`.
 #
 define apt::ppa (
-  String $ensure                        = 'present',
-  Optional[Array[String]] $options      = $apt::ppa_options,
-  Optional[String] $release             = fact('os.distro.codename'),
-  Optional[String] $dist                = $facts['os']['name'],
-  Optional[String] $package_name        = $apt::ppa_package,
+  Enum['present', 'absent'] $ensure     = 'present',
+  Optional[Array[String[1]]] $options   = $apt::ppa_options,
+  Optional[String[1]] $release          = fact('os.distro.codename'),
+  Optional[String[1]] $dist             = $facts['os']['name'],
+  Optional[String[1]] $package_name     = $apt::ppa_package,
   Boolean $package_manage               = false,
 ) {
   unless $release {

manifests/ppa.pp

@@ -1,30 +1,30 @@
 # @summary Manages Apt configuration files.
 #
-# @see https://docs.puppetlabs.com/references/latest/type.html#file-attributes for more information on source and content parameters
+# @see https://www.puppet.com/docs/puppet/latest/types/file.html#file-attributes for more information on source and content parameters
 #
 # @param priority
 #   Determines the order in which Apt processes the configuration file. Files with higher priority numbers are loaded first.
 #
 # @param ensure
-#   Specifies whether the file should exist. Valid options: 'present', 'absent', and 'file'.
+#   Specifies whether the file should exist.
 #
 # @param source
-#   Required, unless `content` is set. Specifies a source file to supply the content of the configuration file. Cannot be used in combination 
+#   Required, unless `content` is set. Specifies a source file to supply the content of the configuration file. Cannot be used in combination
 #   with `content`. Valid options: see link above for Puppet's native file type source attribute.
 #
 # @param content
-#   Required, unless `source` is set. Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid 
+#   Required, unless `source` is set. Directly supplies content for the configuration file. Cannot be used in combination with `source`. Valid
 #   options: see link above for Puppet's native file type content attribute.
 #
 # @param notify_update
 #   Specifies whether to trigger an `apt-get update` run.
 #
 define apt::setting (
-  Variant[String, Integer, Array] $priority           = 50,
-  Enum['file', 'present', 'absent'] $ensure           = file,
-  Optional[String] $source                            = undef,
-  Optional[String] $content                           = undef,
-  Boolean $notify_update                              = true,
+  Variant[String[1], Integer[0]] $priority = 50,
+  Enum['file', 'present', 'absent'] $ensure = file,
+  Optional[String[1]] $source = undef,
+  Optional[String[1]] $content = undef,
+  Boolean $notify_update = true,
 ) {
   if $content and $source {
     fail('apt::setting cannot have both content and source')

manifests/setting.pp

@@ -22,7 +22,7 @@
 #   }
 #
 # @param location
-#   Required, unless ensure is set to 'absent'. Specifies an Apt repository. Valid options: a string containing a repository URL.
+#   Required, unless ensure is set to 'absent'. Specifies an Apt repository.
 #
 # @param comment
 #   Supplies a comment for adding to the Apt source file.
@@ -59,7 +59,7 @@
 #   See https://wiki.debian.org/DebianRepository/UseThirdParty for details.
 #
 # @param pin
-#   Creates a declaration of the apt::pin defined type. Valid options: a number or string to be passed to the `id` parameter of the
+#   Creates a declaration of the apt::pin defined type. Valid options: a number or string to be passed to the `priority` parameter of the
 #   `apt::pin` defined type, or a hash of `parameter => value` pairs to be passed to `apt::pin`'s corresponding parameters.
 #
 # @param architecture
@@ -80,20 +80,20 @@
 #   Specifies whether to check if the package release date is valid.
 #
 define apt::source (
-  Optional[String] $location                    = undef,
-  String $comment                               = $name,
-  String $ensure                                = present,
-  Optional[String] $release                     = undef,
-  String $repos                                 = 'main',
-  Variant[Hash] $include                        = {},
-  Optional[Variant[String, Hash]] $key          = undef,
-  Optional[Stdlib::AbsolutePath] $keyring       = undef,
-  Optional[Variant[Hash, Numeric, String]] $pin = undef,
-  Optional[String] $architecture                = undef,
-  Boolean $allow_unsigned                       = false,
-  Boolean $allow_insecure                       = false,
-  Boolean $notify_update                        = true,
-  Boolean $check_valid_until                    = true,
+  Optional[String[1]] $location = undef,
+  String[1] $comment = $name,
+  Enum['present', 'absent'] $ensure = present,
+  Optional[String[0]] $release = undef,
+  String[1] $repos = 'main',
+  Hash $include = {},
+  Optional[Variant[String[1], Hash]] $key = undef,
+  Optional[Stdlib::AbsolutePath] $keyring = undef,
+  Optional[Variant[Hash, Integer, String[1]]] $pin = undef,
+  Optional[String[1]] $architecture = undef,
+  Boolean $allow_unsigned = false,
+  Boolean $allow_insecure = false,
+  Boolean $notify_update = true,
+  Boolean $check_valid_until = true,
 ) {
   include apt