Merge pull request #7938 from chef/descriptions2

Add additional resource description fields

13 files changed, 50 insertions, 23 deletions

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_d.rb b/lib/chef/resource/cron_d.rb
index 92bfe34d40..f42318b574 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -103,7 +103,7 @@ class Chef
                }
 
       property :hour, [Integer, String],
-               description: "The hour at which the cron entry is to run (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) },
                }
@@ -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 in the form of ``({'ENV_VARIABLE' => 'VALUE'})``. (These variables must exist for a command to be run successfully.)",
+               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 93dfd524b8..e6695ac5e3 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :app, String,
-               description: "The name of the application as it appears in the /Volumes directory, if it differs from the resource block name.",
+               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,
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index e2f389325e..05a76ab5e3 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: "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'})."
 
       alias :env :environment
 
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 89c4c0c6d0..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: "An optional property to set the hostnam if it differs from the resource block'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 ],
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