Merge pull request #7969 from chef/descriptions_14_v2

Chef 14: Improve resource descriptions

25 files changed, 77 insertions, 50 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 e9452e8f3c..10e133594f 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -24,7 +24,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 5319f82ab4..a2db254603 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -24,7 +24,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.rb b/lib/chef/resource/cron.rb
index 57cc483c8a..7e9f3022a7 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -134,14 +134,33 @@ class Chef
         )
       end
 
-      property :time, Symbol, equal_to: Chef::Provider::Cron::SPECIAL_TIME_VALUES
-      property :mailto, String
-      property :path, String
-      property :home, String
-      property :shell, String
-      property :command, String, identity: true
-      property :user, String, default: "root"
-      property :environment, Hash, default: lazy { Hash.new }
+      property :time, Symbol,
+               description: "A time interval. Possible values: :annually, :daily, :hourly, :midnight, :monthly, :reboot, :weekly, or :yearly.",
+               equal_to: Chef::Provider::Cron::SPECIAL_TIME_VALUES
+
+      property :mailto, String,
+               description: "Set the MAILTO environment variable."
+
+      property :path, String,
+               description: "Set the PATH environment variable."
+
+      property :home, String,
+               description: "Set the HOME environment variable."
+
+      property :shell, String,
+               description: "Set the SHELL environment variable."
+
+      property :command, String,
+               description: "The command to be run, or the path to a file that contains the command to be run.",
+               identity: true
+
+      property :user, String,
+               description: "The name of the user that runs the command. If the user property is changed, the original user for the crontab program continues to run until that crontab program is deleted. This property is not applicable on the AIX platform.",
+               default: "root"
+
+      property :environment, Hash,
+               description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}).",
+               default: lazy { Hash.new }
 
       private
 
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index b6b822ba40..8f43ed1891 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -31,7 +31,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 6beff4936e..1c3f86069f 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -88,7 +88,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
@@ -98,31 +98,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 should 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) },
                }
@@ -132,7 +132,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,
@@ -151,7 +151,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'})``.",
                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..e6695ac5e3 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's 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 dffbfc9231..9eb86a2fef 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'})."
 
       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..6b5a5617cf 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 hostname 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 ea33d19ff1..0f2053334e 100644
--- a/lib/chef/resource/kernel_module.rb
+++ b/lib/chef/resource/kernel_module.rb
@@ -18,7 +18,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 ],
diff --git a/lib/chef/resource/scm.rb b/lib/chef/resource/scm.rb
index 9346405e53..fb0e70ad44 100644
--- a/lib/chef/resource/scm.rb
+++ b/lib/chef/resource/scm.rb
@@ -66,7 +66,7 @@ class Chef
                default: "deploy"
 
       property :environment, [Hash, nil],
-               description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}). (These variables must exist for a command to be run successfully.)",
+               description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}).",
                default: nil
 
       alias :env :environment
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index 87920e3d9b..f4f95cb28c 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :path, String,
-               description: "The path where the swap file will be created on the system, if it differs from the resource block name.",
+               description: "The path where the swap file will be created on the system, if it differs from the resource block's name.",
                name_property: true
 
       property :size, Integer,
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 91b9371a0a..a5568904ba 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -33,7 +33,7 @@ class Chef
       introduced "14.0"
 
       property :key, String,
-               description: "The kernel parameter key in dotted format, if it differs from the resource block name.",
+               description: "The kernel parameter key in dotted format, if it differs from the resource block's name.",
                name_property: true
 
       property :ignore_error, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index 8197d760ab..89bc30b9d1 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -60,7 +60,7 @@ class Chef
 
       property :unit_name, String, desired_state: false,
                identity: true, name_property: true,
-               description: "The name of the unit file if it differs from the resource block name.",
+               description: "The name of the unit file if it differs from the resource block's name.",
                introduced: "13.7"
 
       def to_ini
diff --git a/lib/chef/resource/template.rb b/lib/chef/resource/template.rb
index 26e85cc679..bd8325f2c1 100644
--- a/lib/chef/resource/template.rb
+++ b/lib/chef/resource/template.rb
@@ -57,9 +57,17 @@ class Chef
         )
       end
 
-      property :variables, Hash, default: lazy { Hash.new }
-      property :cookbook, String
-      property :local, [ TrueClass, FalseClass ], default: false
+      property :variables, Hash,
+               description: "The variables property of the template resource can be used to reference a partial template file by using a Hash.",
+               default: lazy { Hash.new }
+
+      property :cookbook, String,
+               description: "The cookbook in which a file is located (if it is not located in the current cookbook). The default value is the current cookbook.",
+               desired_state: false
+
+      property :local, [ TrueClass, FalseClass ],
+               default: false, desired_state: false,
+               description: "Load a template from a local path. By default, the chef-client loads templates from a cookbook’s /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node."
 
       # Declares a helper method to be defined in the template context when
       # rendering.
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index 5fb93e1b9e..74c3d85520 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 it differs from the resource block name.",
+               description: "The name of the program to run at login, if it differs from the resource block's name.",
                name_property: true
 
       property :path, String,
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index d705de857f..24f555a86c 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -28,7 +28,7 @@ class Chef
       introduced "14.0"
 
       property :feature_name, [Array, String],
-               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).",
+               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block's 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,
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index 9f1a3b151d..9a7b725575 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.0"
 
       property :feature_name, [Array, String],
-               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block name.",
+               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block's name.",
                coerce: proc { |x| to_formatted_array(x) },
                name_property: true