More resource documentation formatting / clarity improvements

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

3 files changed, 9 insertions, 8 deletions

diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index 86c87aeb75..a3a1e7bcda 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -49,7 +49,7 @@ class Chef
         description: "The user’s password. The user property must be set if using this property."
 
       property :run_level, Symbol, equal_to: %i{highest limited},
-               description: "Run with ':limited' or ':highest' privileges.",
+               description: "Run with `:limited` or `:highest` privileges.",
                default: :limited
 
       property :force, [TrueClass, FalseClass],
@@ -86,17 +86,18 @@ class Chef
         description: "The day(s) on which the task runs."
 
       property :months, String,
-        description: "The Months of the year on which the task runs, such as: 'JAN, FEB' or '\*'. Multiple months should be comma delimited. e.g. 'Jan, Feb, Mar, Dec'."
+        description: "The Months of the year on which the task runs, such as: `JAN, FEB` or `*`. Multiple months should be comma delimited. e.g. `Jan, Feb, Mar, Dec`."
 
       property :idle_time, Integer,
-        description: "For :on_idle frequency, the time (in minutes) without user activity that must pass to trigger the task, from 1 - 999."
+        description: "For `:on_idle` frequency, the time (in minutes) without user activity that must pass to trigger the task, from 1 - 999."
 
       property :random_delay, [String, Integer],
         description: "Delays the task up to a given time (in seconds)."
 
       property :execution_time_limit, [String, Integer],
-        description: "The maximum time (in seconds) the task will run.",
-        default: "PT72H" # 72 hours in ISO8601 duration format
+        description: "The maximum time the task will run. This field can accept either seconds or an ISO8601 duration value",
+        default: "PT72H",
+        default_description: "PT72H (72 hours in ISO8601 duration format)"
 
       property :minutes_duration, [String, Integer],
         description: ""
diff --git a/lib/chef/resource/windows_workgroup.rb b/lib/chef/resource/windows_workgroup.rb
index bcb791af77..8d01c8a494 100644
--- a/lib/chef/resource/windows_workgroup.rb
+++ b/lib/chef/resource/windows_workgroup.rb
@@ -36,11 +36,11 @@ class Chef
         name_property: true
 
       property :user, String,
-        description: "The local administrator user to use to change the workgroup. Required if using the password property.",
+        description: "The local administrator user to use to change the workgroup. Required if using the `password` property.",
         desired_state: false
 
       property :password, String,
-        description: "The password for the local administrator user. Required if using the user property.",
+        description: "The password for the local administrator user. Required if using the `user` property.",
         desired_state: false
 
       property :reboot, Symbol,
diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb
index cac2156e93..53d2edd5d2 100644
--- a/lib/chef/resource/yum_package.rb
+++ b/lib/chef/resource/yum_package.rb
@@ -46,7 +46,7 @@ class Chef
         identity: true, coerce: proc { |x| x.is_a?(Array) ? x.to_a : x }
 
       property :version, [ String, Array ],
-        description: "The version of a package to be installed or upgraded. This property is ignored when using the ':upgrade' action.",
+        description: "The version of a package to be installed or upgraded. This property is ignored when using the `:upgrade` action.",
         coerce: proc { |x| x.is_a?(Array) ? x.to_a : x }
 
       property :arch, [ String, Array ],