Add additional descriptions to resource and update otherswording

Update descriptions to match the edits that were done to the docs site. Also fix windows_share to lazily eval the arrays, which is a bugfix + a docs fix the way we generate docs right now.

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

11 files changed, 47 insertions, 34 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index f6ae227e97..9352130481 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -660,7 +660,7 @@ Use the swap_file resource to create or delete swap files on Linux systems, and
 
 ### sysctl
 
-Use the sysctl resource to set kernel parameters using the sysctl command line tool and configuration files in the system's `sysctl.d` directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If an existing value was already set for the value it will be backed up to the node and restored if the :remove action is used later. This resource was ported from the `sysctl` community cookbook.
+Use the sysctl resource to set or remove kernel parameters using the sysctl command line tool and configuration files in the system's `sysctl.d` directory. Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If an existing value was already set for the value it will be backed up to the node and restored if the :remove action is used later. This resource was ported from the `sysctl` community cookbook.
 
 `Note`: This resource no longer backs up existing key values to the node when changing values as we have done in the sysctl cookbook previously. The resource has also been renamed from `sysctl_param` to `sysctl` with backwards compatibility for the previous name.
 
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 5b70ffa22d..9ace6ee359 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -42,12 +42,12 @@ class Chef
                coerce: proc { |x| x.gsub(/[\.~]/, "__") }
 
       property :users, [String, Array],
-               description: "User(s) to provide sudo privileges to. This accepts either an array or a comma separated.",
+               description: "User(s) to provide sudo privileges to. This property accepts either an array or a comma separated list.",
                default: lazy { [] },
                coerce: proc { |x| x.is_a?(Array) ? x : x.split(/\s*,\s*/) }
 
       property :groups, [String, Array],
-               description: "Group(s) to provide sudo privileges to. This accepts either an array or a comma separated list. Leading % on group names is optional.",
+               description: "Group(s) to provide sudo privileges to. This property accepts either an array or a comma separated list. Leading % on group names is optional.",
                default: lazy { [] },
                coerce: proc { |x| coerce_groups(x) }
 
@@ -72,10 +72,10 @@ class Chef
                default: false
 
       property :template, String,
-               description: "The name of the erb template in your cookbook if you wish to supply your own template."
+               description: "The name of the erb template in your cookbook, if you wish to supply your own template."
 
       property :variables, [Hash, nil],
-               description: "The variables to pass to the custom template. Ignored if not using a custom template.",
+               description: "The variables to pass to the custom template. This property is ignored if not using a custom template.",
                default: nil
 
       property :defaults, Array,
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 643ceb233a..91b9371a0a 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -24,7 +24,7 @@ class Chef
       provides(:sysctl) { true }
       provides(:sysctl_param) { true }
 
-      description "Use the sysctl resource to set kernel parameters using the sysctl"\
+      description "Use the sysctl resource to set or remove kernel parameters using the sysctl"\
                   " command line tool and configuration files in the system's sysctl.d directory. "\
                   "Configuration files managed by this resource are named 99-chef-KEYNAME.conf. If"\
                   " an existing value was already set for the value it will be backed up to the node"\
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index a7508660f7..8197d760ab 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -44,16 +44,24 @@ class Chef
       property :static, [TrueClass, FalseClass], skip_docs: true
 
       # User-provided properties
-      property :user, String, desired_state: false
-      property :content, [String, Hash]
+      property :user, String, desired_state: false,
+               description: "The user account that the systemd unit process is run under. The path to the unit for that user would be something like '/etc/systemd/user/sshd.service'. If no user account is specified, the systemd unit will run under a 'system' account, with the path to the unit being something like '/etc/systemd/system/sshd.service'."
+
+      property :content, [String, Hash],
+                description: "A string or hash that contains a systemd `unit file <https://www.freedesktop.org/software/systemd/man/systemd.unit.html>`_ definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In Chef 14.4 or later, repeatable options can be implemented with an array."
+
       property :triggers_reload, [TrueClass, FalseClass],
-                                 default: true, desired_state: false
+               description: "Specifies whether to trigger a daemon reload when creating or deleting a unit.",
+               default: true, desired_state: false
+
       property :verify, [TrueClass, FalseClass],
-                        default: true, desired_state: false
+               default: true, desired_state: false,
+               description: "Specifies if the unit will be verified before installation. Systemd can be overly strict when verifying units, so in certain cases it is preferable not to verify the unit."
+
       property :unit_name, String, desired_state: false,
-                                   identity: true,
-                                   name_property: true,
-                                   introduced: "13.7"
+               identity: true, name_property: true,
+               description: "The name of the unit file if it differs from the resource block name.",
+               introduced: "13.7"
 
       def to_ini
         case content
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index 0ff8c24bfc..5fb93e1b9e 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 different from the resource name.",
+               description: "The name of the program to run at login, if it differs from the resource block name.",
                name_property: true
 
       property :path, String,
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 781a09fed7..e08ae596a9 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -31,9 +31,18 @@ class Chef
       default_action :create
       allowed_actions :create, :delete, :modify
 
-      property :key_name, String, identity: true, name_property: true
-      property :value, String, required: true
-      property :delim, [ String, nil, false ], desired_state: false
+      property :key_name, String,
+               description: "The name of the key that is to be created, deleted, or modified.",
+               identity: true, name_property: true
+
+      property :value, String,
+               description: "The value of the environmental variable to set.",
+               required: true
+
+      property :delim, [ String, nil, false ],
+               description: "The delimiter that is used to separate multiple values for a single key.",
+               desired_state: false
+
       property :user, String, default: "<System>"
     end
   end
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index c80b875fbd..c6bcaac2dc 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -24,9 +24,7 @@ class Chef
       resource_name :windows_feature
       provides(:windows_feature) { true }
 
-      description "Use the windows_feature resource to add, remove or delete Windows features and roles. This resource calls"\
-                  " the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation"\
-                  " method and defaults to dism, which is available on both Workstation and Server editions of Windows."
+      description "Use the windows_feature resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method and defaults to dism, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
@@ -36,7 +34,7 @@ class Chef
                name_property: true
 
       property :source, String,
-               description: "Use a local repository for the feature install."
+               description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
                description: "Install all sub features.",
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 2c2d7fc431..967c767497 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -25,7 +25,7 @@ class Chef
       resource_name :windows_feature_dism
       provides(:windows_feature_dism) { true }
 
-      description "Use the windows_feature_dism resource to add, remove or delete Windows features and roles using DISM"
+      description "Use the windows_feature_dism resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
 
       property :feature_name, [Array, String],
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index ff9a501815..a04aca525a 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -27,23 +27,19 @@ class Chef
       resource_name :windows_feature_powershell
       provides(:windows_feature_powershell) { true }
 
-      description "Use the windows_feature_powershell resource to add, remove or"\
-                  " delete Windows features and roles using PowerShell. This resource"\
-                  " offers significant speed benefits over the windows_feature_dism resource,"\
-                  " but requires installing the Remote Server Administration Tools on"\
-                  " non-server releases of Windows"
+      description "Use the windows_feature_powershell resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installing the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
 
       property :feature_name, [Array, String],
-               description: "The name of the feature/role(s) to install if it differs from the resource name.",
+               description: "The name of the feature(s) or role(s) to install, if it differs from the resource block name.",
                coerce: proc { |x| to_formatted_array(x) },
                name_property: true
 
       property :source, String,
-               description: "Use a local repository for the feature install."
+               description: "Specify a local repository for the feature install."
 
       property :all, [TrueClass, FalseClass],
-               description: "Install all sub features. This is equivalent to using the -InstallAllSubFeatures switch with Add-WindowsFeature.",
+               description: "Install all subfeatures. When set to 'true', this is the equivalent of specifying the '-InstallAllSubFeatures' switch with 'Add-WindowsFeature'.",
                default: false
 
       property :timeout, Integer,
diff --git a/lib/chef/resource/windows_path.rb b/lib/chef/resource/windows_path.rb
index 0c5aaa9ce1..7f2e79d9d2 100644
--- a/lib/chef/resource/windows_path.rb
+++ b/lib/chef/resource/windows_path.rb
@@ -30,7 +30,9 @@ class Chef
       allowed_actions :add, :remove
       default_action :add
 
-      property :path, String, name_property: true
+      property :path, String,
+               description: "The name of the value to add to the system path",
+               name_property: true
     end
   end
 end
diff --git a/lib/chef/resource/windows_share.rb b/lib/chef/resource/windows_share.rb
index b50c5ef2e3..e45a3589e6 100644
--- a/lib/chef/resource/windows_share.rb
+++ b/lib/chef/resource/windows_share.rb
@@ -47,17 +47,17 @@ class Chef
       # Specifies which accounts are granted full permission to access the share. Use a comma-separated list to specify multiple accounts. An account may not be specified more than once in the FullAccess, ChangeAccess, or ReadAccess parameter lists, but may be specified once in the FullAccess, ChangeAccess, or ReadAccess parameter list and once in the NoAccess parameter list.
       property :full_users, Array,
                description: "The users that should have 'Full control' permissions on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies which users are granted modify permission to access the share
       property :change_users, Array,
                description: "The users that should have 'modify' permission on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies which users are granted read permission to access the share. Multiple users can be specified by supplying a comma-separated list.
       property :read_users, Array,
                description: "The users that should have 'read' permission on the share in domain\\username format.",
-               default: [], coerce: proc { |u| u.sort }
+               default: lazy { [] }, coerce: proc { |u| u.sort }
 
       # Specifies the lifetime of the new SMB share. A temporary share does not persist beyond the next restart of the computer. By default, new SMB shares are persistent, and non-temporary.
       property :temporary, [TrueClass, FalseClass],