Update resources text (#13495)

Signed-off-by: Ian Maddaus <ian.maddaus@progress.com>

10 files changed, 24 insertions, 20 deletions

diff --git a/lib/chef/resource/dsc_script.rb b/lib/chef/resource/dsc_script.rb
index ac18f7e11e..cb13bc2de6 100644
--- a/lib/chef/resource/dsc_script.rb
+++ b/lib/chef/resource/dsc_script.rb
@@ -34,7 +34,7 @@ class Chef
         resource in #{ChefUtils::Dist::Infra::PRODUCT}, such as the Archive resource, a custom DSC resource, an existing DSC script that performs an important
         task, and so on. Use the dsc_script resource to embed the code that defines a DSC configuration directly within a #{ChefUtils::Dist::Infra::PRODUCT} recipe.
 
-        Warning: The **dsc_script** resource may not be used with the 32 bit Chef Infra client. It must be executed from a 64 bit Chef Infra client.
+        Warning: The **dsc_script** resource is only available on 64-bit Chef Infra Client.
       DESC
 
       default_action :run
diff --git a/lib/chef/resource/launchd.rb b/lib/chef/resource/launchd.rb
index dbd5062403..5ddf6ea0f9 100644
--- a/lib/chef/resource/launchd.rb
+++ b/lib/chef/resource/launchd.rb
@@ -130,7 +130,7 @@ class Chef
         description: "If a job dies, all remaining processes with the same process ID may be kept running. Set to true to kill all remaining processes."
 
       property :associated_bundle_identifiers, Hash,
-        description: "This optional key indicates which bundles the Login Items Added by Apps panel associates with the helper executable."
+        description: "This optional key indicates which bundles the **Login Items Added by Apps** panel associates with the helper executable."
 
       property :debug, [ TrueClass, FalseClass ],
         description: "Sets the log mask to `LOG_DEBUG` for this job."
diff --git a/lib/chef/resource/rhsm_register.rb b/lib/chef/resource/rhsm_register.rb
index c414f4dcde..7ab8200ed1 100644
--- a/lib/chef/resource/rhsm_register.rb
+++ b/lib/chef/resource/rhsm_register.rb
@@ -92,7 +92,7 @@ class Chef
 
       property :release,
         [Float, String],
-        description: "Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to the specified minor release version. This is used with the `auto_attach` option, it may also be used with activation keys.  For example, `release '6.4'` will append `--release=6.4` to the register command.",
+        description: "Sets the operating system minor release to use for subscriptions for the system. Products and updates are limited to the specified minor release version. This is used with the `auto_attach` or `activation_key` options.  For example, `release '6.4'` will append `--release=6.4` to the register command.",
         introduced: "17.8"
 
       action :register, description: "Register the node with RHSM." do
diff --git a/lib/chef/resource/selinux_fcontext.rb b/lib/chef/resource/selinux_fcontext.rb
index 243b180f3c..0ea2889428 100644
--- a/lib/chef/resource/selinux_fcontext.rb
+++ b/lib/chef/resource/selinux_fcontext.rb
@@ -22,7 +22,7 @@ class Chef
 
       provides :selinux_fcontext
 
-      description "Use **selinux_fcontext** resource to set the SELinux context of files with semanage fcontext."
+      description "Use the **selinux_fcontext** resource to set the SELinux context of files using the `semanage fcontext` command."
       introduced "18.0"
       examples <<~DOC
       **Allow http servers (e.g. nginx/apache) to modify moodle files**:
diff --git a/lib/chef/resource/selinux_permissive.rb b/lib/chef/resource/selinux_permissive.rb
index 155f4ef390..712d4b6b16 100644
--- a/lib/chef/resource/selinux_permissive.rb
+++ b/lib/chef/resource/selinux_permissive.rb
@@ -20,7 +20,7 @@ class Chef
 
       provides :selinux_permissive
 
-      description "Use **selinux_permissive** resource to allows some types to misbehave without stopping them. Not as good as specific policies, but better than disabling SELinux entirely."
+      description "Use the **selinux_permissive** resource to allow some domains to misbehave without stopping them. This is not as good as setting specific policies, but better than disabling SELinux entirely."
       introduced "18.0"
       examples <<~DOC
       **Disable enforcement on Apache**:
diff --git a/lib/chef/resource/selinux_port.rb b/lib/chef/resource/selinux_port.rb
index 8690adf9b1..14291fac89 100644
--- a/lib/chef/resource/selinux_port.rb
+++ b/lib/chef/resource/selinux_port.rb
@@ -21,7 +21,7 @@ class Chef
 
       provides :selinux_port
 
-      description "Use **selinux_port** resource to allows assigning a network port to a certain SELinux context, e.g. for running a webserver on a non-standard port."
+      description "Use the **selinux_port** resource to assign a network port to a specific SELinux context. For example, running a web server on a non-standard port."
       introduced "18.0"
       examples <<~DOC
       **Allow nginx/apache to bind to port 5678 by giving it the http_port_t context**:
diff --git a/lib/chef/resource/selinux_state.rb b/lib/chef/resource/selinux_state.rb
index 095a272ef7..c07e8418c0 100644
--- a/lib/chef/resource/selinux_state.rb
+++ b/lib/chef/resource/selinux_state.rb
@@ -56,7 +56,7 @@ class Chef
 
       property :persistent, [true, false],
                 default: true,
-                description: "Persist status update to the selinux configuration file."
+                description: "Set the status update in the SELinux configuration file."
 
       property :policy, String,
                 default: lazy { default_policy_platform },
diff --git a/lib/chef/resource/service.rb b/lib/chef/resource/service.rb
index d834d99ae0..17b4df5d2b 100644
--- a/lib/chef/resource/service.rb
+++ b/lib/chef/resource/service.rb
@@ -81,7 +81,7 @@ class Chef
       # specify overrides for the start_command, stop_command and
       # restart_command properties.
       property :init_command, String,
-        description: "The path to the init script that is associated with the service. Use init_command to prevent the need to specify overrides for the start_command, stop_command, and restart_command properties. When this property is not specified, the #{ChefUtils::Dist::Infra::PRODUCT} will use the default init command for the service provider being used.",
+        description: "The path to the init script that is associated with the service. Use `init_command` to prevent the need to specify overrides for the `start_command`, `stop_command`, and `restart_command` properties. When this property is not specified, the #{ChefUtils::Dist::Infra::PRODUCT} will use the default init command for the service provider being used.",
         desired_state: false
 
       # if the service is enabled or not
diff --git a/lib/chef/resource/user.rb b/lib/chef/resource/user.rb
index 0e84a6b645..c235fabda8 100644
--- a/lib/chef/resource/user.rb
+++ b/lib/chef/resource/user.rb
@@ -74,12 +74,12 @@ class Chef
       alias_method :group, :gid
 
       property :expire_date, [ String, NilClass ],
-               description: "(Linux) The date on which the user account will be disabled. The date is specified in the format YYYY-MM-DD.",
+               description: "(Linux) The date on which the user account will be disabled. The date is specified in YYYY-MM-DD format.",
                introduced: "18.0",
                desired_state: false
 
       property :inactive, [ String, Integer, NilClass ],
-               description: "(Linux) The number of days after a password expires until the account is permanently disabled. A value of 0 disables the account as soon as the password has expired, and a value of -1 disables the feature.",
+               description: "(Linux) The number of days after a password expires until the account is permanently disabled. A value of `0` disables the account as soon as the password has expired, and a value of `-1` disables the feature.",
                introduced: "18.0",
                desired_state: false
     end
diff --git a/lib/chef/resource/windows_user_privilege.rb b/lib/chef/resource/windows_user_privilege.rb
index ac017a1599..7d8c36571e 100644
--- a/lib/chef/resource/windows_user_privilege.rb
+++ b/lib/chef/resource/windows_user_privilege.rb
@@ -23,12 +23,14 @@ class Chef
     class WindowsUserPrivilege < Chef::Resource
 
       provides :windows_user_privilege
-      description "The windows_user_privilege resource allows to add a privilege to a principal or (User/Group).\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
+      description "Use the **windows_user_privilege** resource to set privileges for a principal, user, or group.\n See [Microsoft's user rights assignment documentation](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment) for more information."
 
       introduced "16.0"
 
       examples <<~DOC
-      **Set the SeNetworkLogonRight Privilege for the Builtin Administrators Group and Authenticated Users**:
+      **Set the SeNetworkLogonRight privilege for the Builtin Administrators and Authenticated Users groups**:
+
+      The `:set` action will add this privilege for these two groups and remove this privilege from all other groups or users.
 
       ```ruby
       windows_user_privilege 'Network Logon Rights' do
@@ -38,7 +40,9 @@ class Chef
       end
       ```
 
-      **Provide only the Builtin Guests and Administrator Groups with the SeCreatePageFile Privilege**:
+      **Set the SeCreatePagefilePrivilege privilege for the Builtin Guests and Administrator groups**:
+
+      The `:set` action will add this privilege for these two groups and remove this privilege from all other groups or users.
 
       ```ruby
       windows_user_privilege 'Create Pagefile' do
@@ -48,7 +52,7 @@ class Chef
       end
       ```
 
-      **Add the SeDenyRemoteInteractiveLogonRight Privilege to the 'Remote interactive logon' principal**:
+      **Add the SeDenyRemoteInteractiveLogonRight privilege to the 'Remote interactive logon' principal**:
 
       ```ruby
       windows_user_privilege 'Remote interactive logon' do
@@ -57,7 +61,7 @@ class Chef
       end
       ```
 
-      **Add to the Builtin Guests Group the SeCreatePageFile Privilege**:
+      **Add the SeCreatePageFilePrivilege privilege to the Builtin Guests group**:
 
       ```ruby
       windows_user_privilege 'Guests add Create Pagefile' do
@@ -67,7 +71,7 @@ class Chef
       end
       ```
 
-      **Remove the SeCreatePageFile Privilege from the Builtin Guests Group**:
+      **Remove the SeCreatePageFilePrivilege privilege from the Builtin Guests group**:
 
       ```ruby
       windows_user_privilege 'Create Pagefile' do
@@ -77,7 +81,7 @@ class Chef
       end
       ```
 
-      **Clear all users from the SeDenyNetworkLogonRight Privilege**:
+      **Clear the SeDenyNetworkLogonRight privilege from all users**:
 
       ```ruby
       windows_user_privilege 'Allow any user the Network Logon right' do
@@ -135,15 +139,15 @@ class Chef
                           }.freeze
 
       property :principal, String,
-               description: "An optional property to add the privilege for given principal. Use only with add and remove action. Principal can either be a User/Group or one of special identities found here Ref: https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/special-identities",
+               description: "An optional property to add the privilege for given principal. Use only with add and remove action. Principal can either be a user, group, or [special identity](https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/special-identities).",
                name_property: true
 
       property :users, [Array, String],
-               description: "An optional property to set the privilege for given users. Use only with set action.",
+               description: "An optional property to set the privilege for the specified users. Use only with `:set` action",
                coerce: proc { |v| Array(v) }
 
       property :privilege, [Array, String],
-               description: "One or more privileges to set for principal or users/groups. For more information on what each privilege does Ref: https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment",
+               description: "One or more privileges to set for principal or users/groups. For more information, see [Microsoft's documentation on what each privilege does](https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment).",
                required: true,
                coerce: proc { |v| Array(v) },
                callbacks: {