Merge pull request #11448 from chef/docs_improve

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

9 files changed, 47 insertions, 25 deletions

diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 8b3991251e..33a9435ae4 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -36,7 +36,7 @@ class Chef
       examples <<~DOC
         **Add repository with basic settings**:
 
-         ```ruby
+        ```ruby
         apt_repository 'nginx' do
           uri        'http://nginx.org/packages/ubuntu/'
           components ['nginx']
diff --git a/lib/chef/resource/chef_sleep.rb b/lib/chef/resource/chef_sleep.rb
index c6d3e45877..2cd43af1ae 100644
--- a/lib/chef/resource/chef_sleep.rb
+++ b/lib/chef/resource/chef_sleep.rb
@@ -62,7 +62,7 @@ class Chef
         coerce: proc { |s| Integer(s) },
         name_property: true
 
-      action :sleep do
+      action :sleep, description: "Pause the #{ChefUtils::Dist::Infra::PRODUCT} run for a specified number of seconds" do
         converge_by("sleep #{new_resource.seconds} seconds") do
           sleep(new_resource.seconds)
         end
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index 796860a531..b4d7c6234a 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -107,7 +107,7 @@ class Chef
         end
       end
 
-      action :disable, description: "Disables a Chocolatey source." do
+      action :disable, description: "Disables a Chocolatey source. **New in Chef Infra Client 15.1.**" do
         if current_resource.disabled != true
           converge_by("disable Chocolatey source '#{new_resource.source_name}'") do
             shell_out!(choco_cmd("disable"))
@@ -115,7 +115,7 @@ class Chef
         end
       end
 
-      action :enable, description: "Enables a Chocolatey source." do
+      action :enable, description: "Enables a Chocolatey source. **New in Chef Infra Client 15.1.**" do
         if current_resource.disabled == true
           converge_by("enable Chocolatey source '#{new_resource.source_name}'") do
             shell_out!(choco_cmd("enable"))
diff --git a/lib/chef/resource/rhsm_errata.rb b/lib/chef/resource/rhsm_errata.rb
index 7a1e3df325..354a641fe5 100644
--- a/lib/chef/resource/rhsm_errata.rb
+++ b/lib/chef/resource/rhsm_errata.rb
@@ -25,12 +25,27 @@ class Chef
 
       description "Use the **rhsm_errata** resource to install packages associated with a given Red Hat Subscription Manager Errata ID. This is helpful if packages to mitigate a single vulnerability must be installed on your hosts."
       introduced "14.0"
+      examples <<~DOC
+        **Install a package from an Errata ID**
+
+        ```ruby
+        rhsm_errata 'RHSA:2018-1234'
+        ```
+
+        **Specify an Errata ID that differs from the resource name**
+
+        ```ruby
+        rhsm_errata 'errata-install'
+          errata_id 'RHSA:2018-1234'
+        end
+        ```
+      DOC
 
       property :errata_id, String,
         description: "An optional property for specifying the errata ID if it differs from the resource block's name.",
         name_property: true
 
-      action :install do
+      action :install, description: "Install a package for a specific errata ID." do
         description "Installs a package for a specific errata ID."
 
         execute "Install errata packages for #{new_resource.errata_id}" do
diff --git a/lib/chef/resource/rhsm_errata_level.rb b/lib/chef/resource/rhsm_errata_level.rb
index 9ac3944153..7aa61ad90c 100644
--- a/lib/chef/resource/rhsm_errata_level.rb
+++ b/lib/chef/resource/rhsm_errata_level.rb
@@ -25,6 +25,15 @@ class Chef
 
       description "Use the **rhsm_errata_level** resource to install all packages of a specified errata level from the Red Hat Subscription Manager. For example, you can ensure that all packages associated with errata marked at a 'Critical' security level are installed."
       introduced "14.0"
+      examples <<~DOC
+        **Specify an errata level that differs from the resource name**
+
+        ```ruby
+        rhsm_errata_level 'example_install_moderate' do
+          errata_level 'moderate'
+        end
+        ```
+      DOC
 
       property :errata_level, String,
         coerce: proc { |x| x.downcase },
@@ -32,7 +41,7 @@ class Chef
         description: "An optional property for specifying the errata level of packages to install if it differs from the resource block's name.",
         name_property: true
 
-      action :install do
+      action :install, description: "Install all packages of the specified errata level." do
         description "Install all packages of the specified errata level."
 
         if rhel6?
diff --git a/lib/chef/resource/rhsm_register.rb b/lib/chef/resource/rhsm_register.rb
index 07c4dbc8d7..3e1d251e76 100644
--- a/lib/chef/resource/rhsm_register.rb
+++ b/lib/chef/resource/rhsm_register.rb
@@ -27,6 +27,16 @@ class Chef
 
       description "Use the **rhsm_register** resource to register a node with the Red Hat Subscription Manager or a local Red Hat Satellite server."
       introduced "14.0"
+      examples <<~DOC
+        **Register a node with RHSM*
+
+        ```ruby
+        rhsm_register 'my-host' do
+          activation_key 'ABCD1234'
+          organization 'my_org'
+        end
+        ```
+      DOC
 
       property :activation_key, [String, Array],
         coerce: proc { |x| Array(x) },
@@ -69,9 +79,7 @@ class Chef
         default: false, desired_state: false,
         introduced: "15.9"
 
-      action :register do
-        description "Register the node with RHSM."
-
+      action :register, description: "Register the node with RHSM." do
         package "subscription-manager"
 
         unless new_resource.satellite_host.nil? || registered_with_rhsm?
@@ -106,9 +114,7 @@ class Chef
         end
       end
 
-      action :unregister do
-        description "Unregister the node from RHSM."
-
+      action :unregister, description: "Unregister the node from RHSM." do
         execute "Unregister from RHSM" do
           command "subscription-manager unregister"
           default_env true
diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb
index d8959695cf..502419beb0 100644
--- a/lib/chef/resource/rhsm_repo.rb
+++ b/lib/chef/resource/rhsm_repo.rb
@@ -31,9 +31,7 @@ class Chef
         description: "An optional property for specifying the repository name if it differs from the resource block's name.",
         name_property: true
 
-      action :enable do
-        description "Enable a RHSM repository."
-
+      action :enable, description: "Enable a RHSM repository." do
         execute "Enable repository #{new_resource.repo_name}" do
           command "subscription-manager repos --enable=#{new_resource.repo_name}"
           default_env true
@@ -42,9 +40,7 @@ class Chef
         end
       end
 
-      action :disable do
-        description "Disable a RHSM repository."
-
+      action :disable, description: "Disable a RHSM repository." do
         execute "Enable repository #{new_resource.repo_name}" do
           command "subscription-manager repos --disable=#{new_resource.repo_name}"
           default_env true
diff --git a/lib/chef/resource/rhsm_subscription.rb b/lib/chef/resource/rhsm_subscription.rb
index 15a4822ecd..5ae04bbfcd 100644
--- a/lib/chef/resource/rhsm_subscription.rb
+++ b/lib/chef/resource/rhsm_subscription.rb
@@ -31,9 +31,7 @@ class Chef
         description: "An optional property for specifying the Pool ID if it differs from the resource block's name.",
         name_property: true
 
-      action :attach do
-        description "Attach the node to a subscription pool."
-
+      action :attach, description: "Attach the node to a subscription pool." do
         execute "Attach subscription pool #{new_resource.pool_id}" do
           command "subscription-manager attach --pool=#{new_resource.pool_id}"
           default_env true
@@ -42,9 +40,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove the node from a subscription pool."
-
+      action :remove, description: "Remove the node from a subscription pool." do
         execute "Remove subscription pool #{new_resource.pool_id}" do
           command "subscription-manager remove --serial=#{pool_serial(new_resource.pool_id)}"
           default_env true
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 7620e90bad..dde3412ef5 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -29,7 +29,7 @@ class Chef
       provides :windows_env
       provides :env # backwards compat with the pre-Chef 14 resource name
 
-      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.\nThis resource was previously called the **env** resource; its name was updated in #{ChefUtils::Dist::Infra::PRODUCT} 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using `env` will continue to function, but should be updated to use the new name. Note: On UNIX-based systems, the best way to manipulate environment keys is with the `ENV` variable in Ruby; however, this approach does not have the same permanent effect as using the windows_env resource."
+      description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler.\n\nThis resource was previously called the **env** resource; its name was updated in #{ChefUtils::Dist::Infra::PRODUCT} 14.0 to reflect the fact that only Windows is supported. Existing cookbooks using `env` will continue to function, but should be updated to use the new name. Note: On UNIX-based systems, the best way to manipulate environment keys is with the `ENV` variable in Ruby; however, this approach does not have the same permanent effect as using the windows_env resource."
       examples <<~DOC
       **Set an environment variable**: