More resource description updates

Better descriptions for many name properties and copy edits from the docs site.

Signed-off-by: Tim Smith <tsmith@chef.io>

22 files changed, 33 insertions, 36 deletions

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/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index c6bcaac2dc..9809f01a5e 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -28,9 +28,7 @@ class Chef
       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,
@@ -41,16 +39,15 @@ class Chef
                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.",
                equal_to: [:windows_feature_dism, :windows_feature_powershell, :windows_feature_servermanagercmd]
+               description: "The underlying installation method to use for feature installation. Specify ':windows_feature_dism' for DISM or ':windows_feature_powershell' for PowerShell.",
 
       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 967c767497..2f430f41f4 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -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 a04aca525a..9f1a3b151d 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -43,7 +43,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
 
       property :management_tools, [TrueClass, FalseClass],
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/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