Merge pull request #7887 from chef/docs_improvements_14

Backport: Resource property description updates

31 files changed, 81 insertions, 71 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 79e995bb5d..a1e563386b 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -656,7 +656,7 @@ Use the swap_file resource to create or delete swap files on Linux systems, and
 
 ### sysctl
 
-Use the sysctl resource to set kernel parameters using the sysctl command line tool and configuration files in the system's `sysctl.d` directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If an existing value was already set for the value it will be backed up to the node and restored if the :remove action is used later. This resource was ported from the `sysctl` community cookbook.
+Use the sysctl resource to set or remove kernel parameters using the sysctl command line tool and configuration files in the system's `sysctl.d` directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If an existing value was already set for the value it will be backed up to the node and restored if the :remove action is used later. This resource was ported from the `sysctl` community cookbook.
 
 `Note`: This resource no longer backs up existing key values to the node when changing values as we have done in the sysctl cookbook previously. The resource has also been renamed from `sysctl_param` to `sysctl` with backwards compatibility for the previous name.
 
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index ee0284ec37..382573791e 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -58,7 +58,7 @@ class Chef
 
       property :raid_device, String,
                identity: true, name_property: true,
-               description: "The name of the RAID device. We'll use the resource's name if this isn't specified."
+               description: "An optional property to specify the name of the RAID device if it differs from the resource block's name."
 
       property :layout, String,
                description: "The RAID5 parity algorithm. Possible values: left-asymmetric (or la), left-symmetric (or ls), right-asymmetric (or ra), or right-symmetric (or rs)."
diff --git a/lib/chef/resource/openssl_dhparam.rb b/lib/chef/resource/openssl_dhparam.rb
index 3b0d264f8b..f2f3b679e4 100644
--- a/lib/chef/resource/openssl_dhparam.rb
+++ b/lib/chef/resource/openssl_dhparam.rb
@@ -30,7 +30,7 @@ class Chef
       introduced "14.0"
 
       property :path, String,
-               description: "The path to write the file to if it's different than the resource name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :key_length, Integer,
diff --git a/lib/chef/resource/openssl_ec_private_key.rb b/lib/chef/resource/openssl_ec_private_key.rb
index 77e98f9c2d..366f2c44f3 100644
--- a/lib/chef/resource/openssl_ec_private_key.rb
+++ b/lib/chef/resource/openssl_ec_private_key.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.4"
 
       property :path, String,
-               description: "The path to write the file to it's different than the resource name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :key_curve, String,
diff --git a/lib/chef/resource/openssl_ec_public_key.rb b/lib/chef/resource/openssl_ec_public_key.rb
index d6900c1ad4..ced23a539a 100644
--- a/lib/chef/resource/openssl_ec_public_key.rb
+++ b/lib/chef/resource/openssl_ec_public_key.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.4"
 
       property :path, String,
-               description: "The path to write the file to if different than the resource's name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :private_key_path, String,
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index f0d54dbe37..52ec5bb9e1 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.0"
 
       property :path, String,
-               description: "The path to write the file to it's different than the resource name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :key_length, Integer,
diff --git a/lib/chef/resource/openssl_rsa_public_key.rb b/lib/chef/resource/openssl_rsa_public_key.rb
index b9a4924c3e..eb73f22dae 100644
--- a/lib/chef/resource/openssl_rsa_public_key.rb
+++ b/lib/chef/resource/openssl_rsa_public_key.rb
@@ -30,7 +30,7 @@ class Chef
       introduced "14.0"
 
       property :path, String,
-               description: "The path to the public key file, if it differs from the resource name.",
+               description: "An optional property for specifying the path to the public key if it differs from the resource block's name.",
                name_property: true
 
       property :private_key_path, String,
diff --git a/lib/chef/resource/openssl_x509_certificate.rb b/lib/chef/resource/openssl_x509_certificate.rb
index 192b56026a..d370ef7e5c 100644
--- a/lib/chef/resource/openssl_x509_certificate.rb
+++ b/lib/chef/resource/openssl_x509_certificate.rb
@@ -32,7 +32,7 @@ class Chef
       introduced "14.4"
 
       property :path, String,
-               description: "Optional path to write the file to if you'd like to specify it here instead of in the resource name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :owner, String,
diff --git a/lib/chef/resource/openssl_x509_crl.rb b/lib/chef/resource/openssl_x509_crl.rb
index 06f73bdd51..48ec76857d 100644
--- a/lib/chef/resource/openssl_x509_crl.rb
+++ b/lib/chef/resource/openssl_x509_crl.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.4"
 
       property :path, String,
-               description: "Optional path to write the file to if you'd like to specify it here instead of in the resource name.",
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name.",
                name_property: true
 
       property :serial_to_revoke, [Integer, String],
diff --git a/lib/chef/resource/openssl_x509_request.rb b/lib/chef/resource/openssl_x509_request.rb
index a553e38a89..6808443d80 100644
--- a/lib/chef/resource/openssl_x509_request.rb
+++ b/lib/chef/resource/openssl_x509_request.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.4"
 
       property :path, String, name_property: true,
-               description: "The optional path to write the file to if you'd like to specify it here instead of in the resource name."
+               description: "An optional property for specifying the path to write the file to if it differs from the resource block's name."
 
       property :owner, String,
                description: "The owner applied to all files created by the resource."
diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb
index 8954478ee3..2a94ca6c02 100644
--- a/lib/chef/resource/package.rb
+++ b/lib/chef/resource/package.rb
@@ -61,7 +61,7 @@ class Chef
                default: lazy { Hash.new }, desired_state: false
 
       property :source, String,
-               description: "The direct path to a the package on the host.",
+               description: "The optional path to a package on the local file system.",
                desired_state: false
 
       property :timeout, [ String, Integer ],
diff --git a/lib/chef/resource/rhsm_errata.rb b/lib/chef/resource/rhsm_errata.rb
index 11aa49c34a..e37278de79 100644
--- a/lib/chef/resource/rhsm_errata.rb
+++ b/lib/chef/resource/rhsm_errata.rb
@@ -29,7 +29,7 @@ class Chef
       introduced "14.0"
 
       property :errata_id, String,
-               description: "An optional property for specifying the errata ID if not using the resource's name.",
+               description: "An optional property for specifying the errata ID if it differs from the resource block's name.",
                name_property: true
 
       action :install do
diff --git a/lib/chef/resource/rhsm_errata_level.rb b/lib/chef/resource/rhsm_errata_level.rb
index 213487537b..1e82ee73aa 100644
--- a/lib/chef/resource/rhsm_errata_level.rb
+++ b/lib/chef/resource/rhsm_errata_level.rb
@@ -29,7 +29,7 @@ class Chef
       property :errata_level, String,
                coerce: proc { |x| x.downcase },
                equal_to: %w{critical moderate important low},
-               description: "The errata level of packages to install.",
+               description: "An optional property for specifying the errata level of packages to install if it differs from the resource block's name.",
                name_property: true
 
       action :install do
diff --git a/lib/chef/resource/rhsm_register.rb b/lib/chef/resource/rhsm_register.rb
index cf1a131c44..4e10e3a03d 100644
--- a/lib/chef/resource/rhsm_register.rb
+++ b/lib/chef/resource/rhsm_register.rb
@@ -30,22 +30,22 @@ class Chef
 
       property :activation_key, [String, Array],
                coerce: proc { |x| Array(x) },
-               description: "A String or array of the activation keys to use when registering. You must also specify the organization property if using activation_key."
+               description: "A string or array of activation keys to use when registering; you must also specify the 'organization' property when using this property."
 
       property :satellite_host, String,
-               description: "The FQDN of the Satellite host to register with. If not specified, the host will be registered with Red Hat's public RHSM service."
+               description: "The FQDN of the Satellite host to register with. If this property is not specified, the host will register with Red Hat's public RHSM service."
 
       property :organization, String,
-               description: "The organization to use when registering, required when using an activation key."
+               description: "The organization to use when registering; required when using the 'activation_key' property."
 
       property :environment, String,
-               description: "The environment to use when registering, required when using username and password."
+               description: "The environment to use when registering; required when using the username and password properties."
 
       property :username, String,
-               description: "The username to use when registering. Not applicable if using an activation key. If specified, password and environment are also required."
+               description: "The username to use when registering. This property is not applicable if using an activation key. If specified, password and environment properties are also required."
 
       property :password, String,
-               description: "The password to use when registering. Not applicable if using an activation key. If specified, username and environment are also required."
+               description: "The password to use when registering. This property is not applicable if using an activation key. If specified, username and environment are also required."
 
       property :auto_attach,
                [TrueClass, FalseClass],
@@ -57,7 +57,7 @@ class Chef
                default: true
 
       property :force, [TrueClass, FalseClass],
-               description: "If true, the system will be registered even if it is already registered. Normally, any register operations will fail if the machine is has already registered.",
+               description: "If true, the system will be registered even if it is already registered. Normally, any register operations will fail if the machine has already been registered.",
                default: false, desired_state: false
 
       action :register do
diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb
index 86857be211..943abc3331 100644
--- a/lib/chef/resource/rhsm_repo.rb
+++ b/lib/chef/resource/rhsm_repo.rb
@@ -28,7 +28,7 @@ class Chef
       introduced "14.0"
 
       property :repo_name, String,
-               description: "An optional property for specifying the repository name if not using the resource's name.",
+               description: "An optional property for specifying the repository name if it differs from the resource block's name.",
                name_property: true
 
       action :enable do
diff --git a/lib/chef/resource/rhsm_subscription.rb b/lib/chef/resource/rhsm_subscription.rb
index f00f801afa..52f4c41653 100644
--- a/lib/chef/resource/rhsm_subscription.rb
+++ b/lib/chef/resource/rhsm_subscription.rb
@@ -29,7 +29,7 @@ class Chef
       introduced "14.0"
 
       property :pool_id, String,
-               description: "An optional property for specifying the Pool ID if not using the resource's name.",
+               description: "An optional property for specifying the Pool ID if it differs from the resource block's name.",
                name_property: true
 
       action :attach do
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 5b70ffa22d..9ace6ee359 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -42,12 +42,12 @@ class Chef
                coerce: proc { |x| x.gsub(/[\.~]/, "__") }
 
       property :users, [String, Array],
-               description: "User(s) to provide sudo privileges to. This accepts either an array or a comma separated.",
+               description: "User(s) to provide sudo privileges to. This property accepts either an array or a comma separated list.",
                default: lazy { [] },
                coerce: proc { |x| x.is_a?(Array) ? x : x.split(/\s*,\s*/) }
 
       property :groups, [String, Array],
-               description: "Group(s) to provide sudo privileges to. This accepts either an array or a comma separated list. Leading % on group names is optional.",
+               description: "Group(s) to provide sudo privileges to. This property accepts either an array or a comma separated list. Leading % on group names is optional.",
                default: lazy { [] },
                coerce: proc { |x| coerce_groups(x) }
 
@@ -72,10 +72,10 @@ class Chef
                default: false
 
       property :template, String,
-               description: "The name of the erb template in your cookbook if you wish to supply your own template."
+               description: "The name of the erb template in your cookbook, if you wish to supply your own template."
 
       property :variables, [Hash, nil],
-               description: "The variables to pass to the custom template. Ignored if not using a custom template.",
+               description: "The variables to pass to the custom template. This property is ignored if not using a custom template.",
                default: nil
 
       property :defaults, Array,
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 643ceb233a..91b9371a0a 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -24,7 +24,7 @@ class Chef
       provides(:sysctl) { true }
       provides(:sysctl_param) { true }
 
-      description "Use the sysctl resource to set kernel parameters using the sysctl"\
+      description "Use the sysctl resource to set or remove kernel parameters using the sysctl"\
                   " command line tool and configuration files in the system's sysctl.d directory. "\
                   "Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If"\
                   " an existing value was already set for the value it will be backed up to the node"\
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index a7508660f7..8197d760ab 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -44,16 +44,24 @@ class Chef
       property :static, [TrueClass, FalseClass], skip_docs: true
 
       # User-provided properties
-      property :user, String, desired_state: false
-      property :content, [String, Hash]
+      property :user, String, desired_state: false,
+               description: "The user account that the systemd unit process is run under. The path to the unit for that user would be something like '/etc/systemd/user/sshd.service'. If no user account is specified, the systemd unit will run under a 'system' account, with the path to the unit being something like '/etc/systemd/system/sshd.service'."
+
+      property :content, [String, Hash],
+                description: "A string or hash that contains a systemd `unit file <https://www.freedesktop.org/software/systemd/man/systemd.unit.html>`_ definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In Chef 14.4 or later, repeatable options can be implemented with an array."
+
       property :triggers_reload, [TrueClass, FalseClass],
-                                 default: true, desired_state: false
+               description: "Specifies whether to trigger a daemon reload when creating or deleting a unit.",
+               default: true, desired_state: false
+
       property :verify, [TrueClass, FalseClass],
-                        default: true, desired_state: false
+               default: true, desired_state: false,
+               description: "Specifies if the unit will be verified before installation. Systemd can be overly strict when verifying units, so in certain cases it is preferable not to verify the unit."
+
       property :unit_name, String, desired_state: false,
-                                   identity: true,
-                                   name_property: true,
-                                   introduced: "13.7"
+               identity: true, name_property: true,
+               description: "The name of the unit file if it differs from the resource block name.",
+               introduced: "13.7"
 
       def to_ini
         case content
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index 0ff8c24bfc..5fb93e1b9e 100644
--- a/lib/chef/resource/windows_auto_run.rb
+++ b/lib/chef/resource/windows_auto_run.rb
@@ -28,7 +28,7 @@ class Chef
       introduced "14.0"
 
       property :program_name, String,
-               description: "The name of the program to run at login if different from the resource name.",
+               description: "The name of the program to run at login, if it differs from the resource block name.",
                name_property: true
 
       property :path, String,
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 781a09fed7..e08ae596a9 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -31,9 +31,18 @@ class Chef
       default_action :create
       allowed_actions :create, :delete, :modify
 
-      property :key_name, String, identity: true, name_property: true
-      property :value, String, required: true
-      property :delim, [ String, nil, false ], desired_state: false
+      property :key_name, String,
+               description: "The name of the key that is to be created, deleted, or modified.",
+               identity: true, name_property: true
+
+      property :value, String,
+               description: "The value of the environmental variable to set.",
+               required: true
+
+      property :delim, [ String, nil, false ],
+               description: "The delimiter that is used to separate multiple values for a single key.",
+               desired_state: false
+
       property :user, String, default: "<System>"
     end
   end
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index c80b875fbd..1ae13a9a2f 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -24,35 +24,30 @@ class Chef
       resource_name :windows_feature
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or delete Windows features and roles. This resource calls"\
-                  " the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation"\
-                  " method and defaults to dism, which is available on both Workstation and Server editions of Windows."
+      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method and defaults to dism, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
-               description: "The name of the feature/role(s) to install. The same feature may have different"\
-                            " names depending on the underlying resource being used (ie DHCPServer vs DHCP;"\
-                            " DNS-Server-Full-Role vs DNS).",
+               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
                name_property: true
 
       property :source, String,
-               description: "Use a local repository for the feature install."
+               description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
                description: "Install all sub features.",
                default: false
 
       property :management_tools, [TrueClass, FalseClass],
-               description: "Install all applicable management tools of the roles, role services, or features (PowerShell only).",
+               description: "Install all applicable management tools for the roles, role services, or features (PowerShell-only).",
                default: false
 
       property :install_method, Symbol,
-               description: "If DISM or PowerShell should be used for the installation. Note feature names differ"\
-                            " between the two installation methods.",
+               description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
                equal_to: [:windows_feature_dism, :windows_feature_powershell, :windows_feature_servermanagercmd]
 
       property :timeout, Integer,
-               description: "Specifies a timeout (in seconds) for feature install.",
+               description: "Specifies a timeout (in seconds) for the feature installation.",
                default: 600
 
       action :install do
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 2c2d7fc431..2f430f41f4 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -25,7 +25,7 @@ class Chef
       resource_name :windows_feature_dism
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove or delete Windows features and roles using DISM"
+      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
 
       property :feature_name, [Array, String],
@@ -41,7 +41,7 @@ class Chef
                default: false
 
       property :timeout, Integer,
-               description: "Specifies a timeout (in seconds) for feature install.",
+               description: "Specifies a timeout (in seconds) for the feature installation.",
                default: 600
 
       # @return [Array] lowercase the array unless we're on < Windows 2012
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index ff9a501815..9f1a3b151d 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -27,27 +27,23 @@ class Chef
       resource_name :windows_feature_powershell
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove or"\
-                  " delete Windows features and roles using PowerShell. This resource"\
-                  " offers significant speed benefits over the windows_feature_dism resource,"\
-                  " but requires installing the Remote Server Administration Tools on"\
-                  " non-server releases of Windows"
+      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installing the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
-               description: "The name of the feature/role(s) to install if it differs from the resource name.",
+               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block name.",
                coerce: proc { |x| to_formatted_array(x) },
                name_property: true
 
       property :source, String,
-               description: "Use a local repository for the feature install."
+               description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-               description: "Install all sub features. This is equivalent to using the -InstallAllSubFeatures switch with Add-WindowsFeature.",
+               description: "Install all subfeatures. When set to 'true', this is the equivalent of specifying the '-InstallAllSubFeatures' switch with 'Add-WindowsFeature'.",
                default: false
 
       property :timeout, Integer,
-               description: "Specifies a timeout (in seconds) for feature install.",
+               description: "Specifies a timeout (in seconds) for the feature installation.",
                default: 600
 
       property :management_tools, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/windows_path.rb b/lib/chef/resource/windows_path.rb
index 0c5aaa9ce1..7f2e79d9d2 100644
--- a/lib/chef/resource/windows_path.rb
+++ b/lib/chef/resource/windows_path.rb
@@ -30,7 +30,9 @@ class Chef
       allowed_actions :add, :remove
       default_action :add
 
-      property :path, String, name_property: true
+      property :path, String,
+               description: "The name of the value to add to the system path",
+               name_property: true
     end
   end
 end
diff --git a/lib/chef/resource/windows_printer.rb b/lib/chef/resource/windows_printer.rb
index 1b9047a222..605b7b8521 100644
--- a/lib/chef/resource/windows_printer.rb
+++ b/lib/chef/resource/windows_printer.rb
@@ -42,7 +42,7 @@ class Chef
                default: false
 
       property :driver_name, String,
-               description: "Exact name of printer driver. Note that the printer driver must already be installed on the node.",
+               description: "The exact name of printer driver installed on the system.",
                required: true
 
       property :location, String,
diff --git a/lib/chef/resource/windows_printer_port.rb b/lib/chef/resource/windows_printer_port.rb
index 07f0778d9b..799a37a651 100644
--- a/lib/chef/resource/windows_printer_port.rb
+++ b/lib/chef/resource/windows_printer_port.rb
@@ -34,7 +34,7 @@ class Chef
                name_property: true,
                regex: Resolv::IPv4::Regex,
                validation_message: "The ipv4_address property must be in the format of WWW.XXX.YYY.ZZZ!",
-               description: "The IPv4 address of the printer port."
+               description: "An optional property for the IPv4 address of the printer if it differs from the resource block's name."
 
       property :port_name, String,
                description: "The port name."
@@ -51,7 +51,7 @@ class Chef
                default: false
 
       property :port_protocol, Integer,
-               description: "The printer port protocol, 1 (RAW), or 2 (LPR).",
+               description: "The printer port protocol: 1 (RAW) or 2 (LPR).",
                validation_message: "port_protocol must be either 1 for RAW or 2 for LPR!",
                default: 1, equal_to: [1, 2]
 
diff --git a/lib/chef/resource/windows_share.rb b/lib/chef/resource/windows_share.rb
index b84be3dc36..93ce6148ed 100644
--- a/lib/chef/resource/windows_share.rb
+++ b/lib/chef/resource/windows_share.rb
@@ -48,17 +48,17 @@ class Chef
       # Specifies which accounts are granted full permission to access the share. Use a comma-separated list to specify multiple accounts. An account may not be specified more than once in the FullAccess, ChangeAccess, or ReadAccess parameter lists, but may be specified once in the FullAccess, ChangeAccess, or ReadAccess parameter list and once in the NoAccess parameter list.
       property :full_users, Array,
                description: "The users that should have 'Full control' permissions on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies which users are granted modify permission to access the share
       property :change_users, Array,
                description: "The users that should have 'modify' permission on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies which users are granted read permission to access the share. Multiple users can be specified by supplying a comma-separated list.
       property :read_users, Array,
                description: "The users that should have 'read' permission on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies the lifetime of the new SMB share. A temporary share does not persist beyond the next restart of the computer. By default, new SMB shares are persistent, and non-temporary.
       property :temporary, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index a4b78e2ca4..7ee0cd88d4 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -74,7 +74,7 @@ class Chef
                default: true
 
       property :gpgkey, [String, Array],
-               description: "URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed."
+               description: "URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed.\nMultiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed."
 
       property :http_caching, String, equal_to: %w{packages all none},
                description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)"
diff --git a/lib/chef/resource/zypper_package.rb b/lib/chef/resource/zypper_package.rb
index c4b967381b..f31dbe2f93 100644
--- a/lib/chef/resource/zypper_package.rb
+++ b/lib/chef/resource/zypper_package.rb
@@ -29,14 +29,14 @@ class Chef
 
       property :gpg_check, [ TrueClass, FalseClass ],
                description: "Verify the package's GPG signature. Can also be controlled site-wide using the ``zypper_check_gpg`` config option.",
-               default: lazy { Chef::Config[:zypper_check_gpg] }
+               default: lazy { Chef::Config[:zypper_check_gpg] }, default_description: "true"
 
       property :allow_downgrade, [ TrueClass, FalseClass ],
                description: "Allow downgrading a package to satisfy requested version requirements.",
                default: false, introduced: "13.6"
 
       property :global_options, [ String, Array ],
-               description: "One (or more) additional options that are passed to the package resource other than options to the command.",
+               description: "One (or more) additional command options that are passed to the command. For example, common zypper directives, such as '--no-recommends'. See the zypper man page at https://en.opensuse.org/SDB:Zypper_manual_(plain) for the full list.",
                coerce: proc { |x| x.is_a?(String) ? x.shellsplit : x },
                introduced: "14.6"
     end
diff --git a/lib/chef/resource_inspector.rb b/lib/chef/resource_inspector.rb
index 1888f9a8bc..ac65e55e99 100644
--- a/lib/chef/resource_inspector.rb
+++ b/lib/chef/resource_inspector.rb
@@ -31,7 +31,7 @@ module ResourceInspector
       # code for the resource ourselves and just no
       "lazy default"
     else
-      default.inspect # inspect properly returns symbols
+      default.is_a?(Symbol) ? default.inspect : default # inspect properly returns symbols
     end
   end