Improve resource descriptions for documentation

Mostly cleaning up how we describe name properties, but also copying over some edits that happened on the docs site.

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

16 files changed, 32 insertions, 32 deletions

diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 3f4a36489d..e55d37fcc8 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -32,7 +32,7 @@ class Chef
 
       property :overwrite_config_files, [TrueClass, FalseClass],
                introduced: "14.0",
-               description: "Overwrite existing config files with those in the package if prompted by apt.",
+               description: "Overwrite existing configuration files with those supplied by the package, if prompted by APT.",
                default: false
 
     end
diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 7ece829ba2..caa0f01305 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -30,7 +30,7 @@ class Chef
 
       property :package_name, String,
                name_property: true,
-               description: "The name of the package.",
+               description: "An optional property to set the package name if it differs from the resource block's name.",
                regex: [/^([a-z]|[A-Z]|[0-9]|_|-|\.|\*|\+)+$/],
                validation_message: "The provided package name is not valid. Package names can only contain alphanumeric characters as well as _, -, +, or *!"
 
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 9a7632cde9..145b515a41 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -34,7 +34,7 @@ class Chef
       # to allow that so don't refactor this however tempting it is
       property :repo_name, String,
                regex: [/^[^\/]+$/],
-               description: "The name of the repository to configure, if it differs from the name of the resource block. The value of this setting must not contain spaces.",
+               description: "An optional property to set the repository name if it differs from the resource block's name. The value of this setting must not contain spaces.",
                validation_message: "repo_name property cannot contain a forward slash '/'",
                introduced: "14.1", name_property: true
 
diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb
index 84c91e0167..d742c6e37a 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -23,7 +23,7 @@ class Chef
       introduced "14.3"
 
       property :config_key, String, name_property: true,
-               description: "The name of the config. The resource's name will be used if this isn't provided."
+               description: "An optional property to set the config key name if it differs from the resource block's name."
 
       property :value, String,
                description: "The value to set."
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index 05f8848117..ce0287a67c 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -23,7 +23,7 @@ class Chef
       introduced "14.3"
 
       property :source_name, String, name_property: true,
-               description: "The name of the source to add. The resource's name will be used if this isn't provided."
+               description: "An optional property to set the source name if it differs from the resource block's name."
 
       property :source, String,
                description: "The source URL."
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index cf50d4ace4..5785eddbe5 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -30,7 +30,7 @@ class Chef
       description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files."
 
       property :user, String,
-               description: "The user to allow or deny. If not provided we'll use the resource name.",
+               description: "An optional property to set the user name if it differs from the resource block's name.",
                name_property: true
 
       action :allow do
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index a42e3e0246..92bfe34d40 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -87,7 +87,7 @@ class Chef
       end
 
       property :cron_name, String,
-               description: "Set the name of the cron job. If this isn't specified we'll use the resource name.",
+               description: "An optional property to set the cron name if it differs from the resource block's name.",
                name_property: true
 
       property :cookbook, String, desired_state: false
@@ -97,31 +97,31 @@ class Chef
                equal_to: %w{ @reboot @yearly @annually @monthly @weekly @daily @midnight @hourly }
 
       property :minute, [Integer, String],
-               description: "The minute to schedule the cron job to run at. Valid values: 0-59.",
+               description: "The minute at which the cron entry should run (0 - 59).",
                default: "*", callbacks: {
                  "should be a valid minute spec" => ->(spec) { validate_numeric(spec, 0, 59) },
                }
 
       property :hour, [Integer, String],
-               description: "The hour to schedule the cron job to run at. Valid values: 0-23.",
+               description: "The hour at which the cron entry is to run (0 - 23).",
                default: "*", callbacks: {
                  "should be a valid hour spec" => ->(spec) { validate_numeric(spec, 0, 23) },
                }
 
       property :day, [Integer, String],
-               description: "The day to schedule the cron job to run at. Valid values: 1-31.",
+               description: "The day of month at which the cron entry should run (1 - 31).",
                default: "*", callbacks: {
                  "should be a valid day spec" => ->(spec) { validate_numeric(spec, 1, 31) },
                }
 
       property :month, [Integer, String],
-               description: "The month to schedule the cron job to run at. Valid values: 1-12, jan-dec, or *.",
+               description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).",
                default: "*", callbacks: {
                  "should be a valid month spec" => ->(spec) { validate_month(spec) },
                }
 
       property :weekday, [Integer, String],
-               description: "The day to schedule the cron job to run at. Valid values: 0-7, mon-sun, or *.",
+               description: "The day of the week on which this entry is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7.",
                default: "*", callbacks: {
                  "should be a valid weekday spec" => ->(spec) { validate_dow(spec) },
                }
@@ -131,7 +131,7 @@ class Chef
                required: true
 
       property :user, String,
-               description: "The user to run the cron job as.",
+               description: "The name of the user that runs the command.",
                default: "root"
 
       property :mailto, String,
@@ -150,7 +150,7 @@ class Chef
                description: "A comment to place in the cron.d file."
 
       property :environment, Hash,
-               description: "A Hash containing additional arbitrary environment variables under which the cron job will be run.",
+               description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``. (These variables must exist for a command to be run successfully.)",
                default: lazy { Hash.new }
 
       property :mode, [String, Integer],
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index cd2f0b5c3a..93dfd524b8 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -27,31 +27,31 @@ class Chef
       introduced "14.0"
 
       property :app, String,
-               description: "The name of the application used by default for the /Volumes directory and the .app directory copied to /Applications.",
+               description: "The name of the application as it appears in the /Volumes directory, if it differs from the resource block name.",
                name_property: true
 
       property :source, String,
-               description: "The remote URL for the dmg to download if specified."
+               description: "The remote URL that is used to download the .dmg file, if specified."
 
       property :file, String,
-               description: "The local dmg full file path."
+               description: "The full path to the .dmg file on the local system."
 
       property :owner, String,
-               description: "The owner that should own the package installation."
+               description: "The user that should own the package installation."
 
       property :destination, String,
                description: "The directory to copy the .app into.",
                default: "/Applications"
 
       property :checksum, String,
-               description: "The sha256 checksum of the dmg to download."
+               description: "The sha256 checksum of the .dmg file to download."
 
       property :volumes_dir, String,
-               description: "The Directory under /Volumes where the dmg is mounted as not all dmgs are mounted into a /Volumes location matching the name of the dmg.",
+               description: "The directory under /Volumes where the dmg is mounted, if it differs from the name of the .dmg file.",
                default: lazy { |r| r.app }, default_description: "The value passed for the application name."
 
       property :dmg_name, String,
-               description: "The name of the dmg if it is not the same as app, or if the name has spaces.",
+               description: "The name of the .dmg file if it differs from that of the app, or if the name has spaces.",
                desired_state: false,
                default: lazy { |r| r.app }, default_description: "The value passed for the application name."
 
@@ -61,10 +61,10 @@ class Chef
                default: "app", desired_state: false
 
       property :package_id, String,
-               description: "The package id registered with pkgutil when a pkg or mpkg is installed."
+               description: "The package ID that is registered with pkgutil when a pkg or mpkg is installed."
 
       property :dmg_passphrase, String,
-               description: "Specify a passphrase to use to unencrypt the dmg while mounting.",
+               description: "Specify a passphrase to be used to decrypt the .dmg file during the mount process.",
                desired_state: false
 
       property :accept_eula, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index e74d0c1439..e2f389325e 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -65,7 +65,7 @@ class Chef
                description: "The current working directory from which the command will be run."
 
       property :environment, Hash,
-               description: "Specify a Hash of environment variables to be set."
+               description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}). (These variables must exist for a command to be run successfully.)"
 
       alias :env :environment
 
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index 7c47fbbfcd..71b40c55bf 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -32,7 +32,7 @@ class Chef
       include Chef::Mixin::HomebrewUser
 
       property :cask_name, String,
-               description: "The name of the Homebrew cask, if it differs from the resource block name.",
+               description: "An optional property to set the cask name if it differs from the resource block's name.",
                regex: %r{^[\w/-]+$},
                validation_message: "The provided Homebrew cask name is not valid. Cask names can contain alphanumeric characters, _, -, or / only!",
                name_property: true
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index a4591e9ed8..aff65685b7 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -32,7 +32,7 @@ class Chef
       include Chef::Mixin::HomebrewUser
 
       property :tap_name, String,
-               description: "Optional tap name to override the resource name",
+               description: "An optional property to set the tap name if it differs from the resource block's name.",
                validation_message: "Homebrew tap names must be in the form REPO/TAP format!",
                regex: %r{^[\w-]+(?:\/[\w-]+)+$},
                name_property: true
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 37106efd74..89c4c0c6d0 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :hostname, String,
-               description: "Used to specify the hostname if it is different than the resource's name.",
+               description: "An optional property to set the hostnam if it differs from the resource block's name.",
                name_property: true
 
       property :compile_time, [ TrueClass, FalseClass ],
@@ -36,7 +36,7 @@ class Chef
 
       property :ipaddress, String,
                description: "The IP address to use when configuring the hosts file.",
-               default: lazy { node["ipaddress"] }
+               default: lazy { node["ipaddress"] }, default_description: "The node's IP address as determined by Ohai."
 
       property :aliases, [ Array, nil ],
                description: "An array of hostname aliases to use when configuring the hosts file.",
diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb
index 041ada9fed..39c792cf3b 100644
--- a/lib/chef/resource/kernel_module.rb
+++ b/lib/chef/resource/kernel_module.rb
@@ -17,7 +17,7 @@ class Chef
       introduced "14.3"
 
       property :modname, String,
-               description: "The name of the kernel module.",
+               description: "An optional property to set the kernel module name if it differs from the resource block's name.",
                name_property: true, identity: true
 
       property :load_dir, String,
diff --git a/lib/chef/resource/link.rb b/lib/chef/resource/link.rb
index 00ce69dddd..45d1e3011a 100644
--- a/lib/chef/resource/link.rb
+++ b/lib/chef/resource/link.rb
@@ -48,7 +48,7 @@ class Chef
       end
 
       property :target_file, String,
-               description: "The name of the link. Default value: the name of the resource block.",
+               description: "An optional property to set the target file if it differs from the resource block's name.",
                name_property: true, identity: true
 
       property :to, String,
diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb
index d1b538c70f..0a710a166c 100644
--- a/lib/chef/resource/ohai_hint.rb
+++ b/lib/chef/resource/ohai_hint.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :hint_name, String,
-               description: "The name of the hints file, if it differs from the resource name.",
+               description: "An optional property to set the hint name if it differs from the resource block's name.",
                name_property: true
 
       property :content, Hash,
diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb
index 2a94ca6c02..670671e22b 100644
--- a/lib/chef/resource/package.rb
+++ b/lib/chef/resource/package.rb
@@ -42,7 +42,7 @@ class Chef
       end
 
       property :package_name, [ String, Array ],
-               description: "The name of the package. Defaults to the name of the resourse block unless specified.",
+               description: "An optional property to set the package name if it differs from the resource block's name.",
                identity: true
 
       property :version, [ String, Array ],