Merge pull request #10739 from chef/docs

Improve our automated resource documentation generation

10 files changed, 19 insertions, 23 deletions

diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index fc23555cbd..2c5b342bce 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -49,7 +49,7 @@ class Chef
 
         To install a gem while #{ChefUtils::Dist::Infra::PRODUCT} is configuring the node (the converge phase), set the `compile_time` property to `false`:
         ```ruby
-        chef_gem 'right_aws' do
+        chef_gem 'loofah' do
           compile_time false
           action :install
         end
@@ -57,7 +57,7 @@ class Chef
 
         To install a gem while the resource collection is being built (the compile phase), set the `compile_time` property to `true`:
         ```ruby
-        chef_gem 'right_aws' do
+        chef_gem 'loofah' do
           compile_time true
           action :install
         end
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index 214f8018ab..b2bba06185 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -32,7 +32,7 @@ class Chef
 
       provides :file
 
-      description "Use the **file** resource to manage files directly on a node."
+      description "Use the **file** resource to manage files directly on a node. Note: Use the **cookbook_file** resource to copy a file from a cookbook's `/files` directory. Use the **template** resource to create a file based on a template in a cookbook's `/templates` directory. And use the **remote_file** resource to transfer a file to a node from a remote location."
 
       if ChefUtils.windows?
         # Use Windows rights instead of standard *nix permissions
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index c893e7a2f9..a3ad5f614b 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -44,8 +44,8 @@ class Chef
         **Install a gem file from the local file system**
 
         ```ruby
-        gem_package 'right_aws' do
-          source '/tmp/right_aws-1.11.0.gem'
+        gem_package 'loofah' do
+          source '/tmp/loofah-2.7.0.gem'
           action :install
         end
         ```
diff --git a/lib/chef/resource/http_request.rb b/lib/chef/resource/http_request.rb
index de714ab4ab..f53d3e731f 100644
--- a/lib/chef/resource/http_request.rb
+++ b/lib/chef/resource/http_request.rb
@@ -26,7 +26,7 @@ class Chef
 
       provides :http_request
 
-      description "Use the **http_request** resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary message. This resource is often useful when custom callbacks are necessary."
+      description "Use the **http_request** resource to send an HTTP request (`GET`, `PUT`, `POST`, `DELETE`, `HEAD`, or `OPTIONS`) with an arbitrary message. This resource is often useful when custom callbacks are necessary."
 
       default_action :get
       allowed_actions :get, :patch, :put, :post, :delete, :head, :options
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index 7c1d066488..f2e610c1cf 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -36,7 +36,7 @@ class Chef
 
       property :chunk, Integer,
         default: 16,
-        description: "The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the level property is set to 1)."
+        description: "The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the `level` property is set to `1`)."
 
       property :devices, Array,
         default: lazy { [] },
@@ -63,7 +63,7 @@ class Chef
         description: "An optional property to specify the name of the RAID device if it differs from the resource block's name."
 
       property :layout, String,
-        description: "The RAID5 parity algorithm. Possible values: left-asymmetric (or la), left-symmetric (or ls), right-asymmetric (or ra), or right-symmetric (or rs)."
+        description: "The RAID5 parity algorithm. Possible values: `left-asymmetric` (or `la`), `left-symmetric` (or ls), `right-asymmetric` (or `ra`), or `right-symmetric` (or `rs`)."
 
       action_class do
         def load_current_resource
diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb
index 6c0028301d..491f30be43 100644
--- a/lib/chef/resource/osx_profile.rb
+++ b/lib/chef/resource/osx_profile.rb
@@ -65,13 +65,13 @@ class Chef
                   {
                     'mcx_preference_settings' => {
                       'idleTime' => 0,
-                    }
-                  }
-                ]
-              }
-            }
-          }
-        ]
+                    },
+                  },
+                ],
+              },
+            },
+          },
+        ],
       }
 
       osx_profile 'Install screensaver profile' do
diff --git a/lib/chef/resource/remote_directory.rb b/lib/chef/resource/remote_directory.rb
index b6dc0b7a98..b87fe8c085 100644
--- a/lib/chef/resource/remote_directory.rb
+++ b/lib/chef/resource/remote_directory.rb
@@ -29,7 +29,7 @@ class Chef
 
       provides :remote_directory
 
-      description "Use the **remote_directory** resource to incrementally transfer a directory from a cookbook to a node. The director that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The remote_directory resource will obey file specificity."
+      description "Use the **remote_directory** resource to incrementally transfer a directory from a cookbook to a node. The directory that is copied from the cookbook should be located under `COOKBOOK_NAME/files/default/REMOTE_DIRECTORY`. The `remote_directory` resource will obey file specificity."
 
       default_action :create
       allowed_actions :create, :create_if_missing, :delete
diff --git a/lib/chef/resource/ruby.rb b/lib/chef/resource/ruby.rb
index a9f3ae24fd..2c0e65e9da 100644
--- a/lib/chef/resource/ruby.rb
+++ b/lib/chef/resource/ruby.rb
@@ -25,11 +25,7 @@ class Chef
 
       provides :ruby
 
-      description "Use the **ruby** resource to execute scripts using the Ruby interpreter. This"\
-                  " resource may also use any of the actions and properties that are available"\
-                  " to the **execute** resource. Commands that are executed with this resource are (by"\
-                  " their nature) not idempotent, as they are typically unique to the environment"\
-                  " in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
+      description "Use the **ruby** resource to execute scripts using the Ruby interpreter. This resource may also use any of the actions and properties that are available to the **execute** resource. Commands that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are run. Use `not_if` and `only_if` to guard this resource for idempotence."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index 427c3e25da..2d7d2fe8b6 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -28,7 +28,7 @@ class Chef
 
       provides :ruby_block, target_mode: true
 
-      description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} run. Ruby code in the ruby_block resource is evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block resource is evaluated before other resources, as the recipe is compiled."
+      description "Use the **ruby_block** resource to execute Ruby code during a #{ChefUtils::Dist::Infra::PRODUCT} run. Ruby code in the `ruby_block` resource is evaluated with other resources during convergence, whereas Ruby code outside of a `ruby_block` resource is evaluated before other resources, as the recipe is compiled."
 
       default_action :run
       allowed_actions :create, :run
diff --git a/tasks/docs.rb b/tasks/docs.rb
index efb0d5420f..b815988b8b 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -246,7 +246,7 @@ namespace :docs_site do
       end
 
       # if we're on a package resource, depending on the OS we want to inject a warning / note that you can just use 'package' instead
-      description << { "notes_resource_based_on_package" => true } if %w{apt_package bff_package dnf_package homebrew_package ips_package openbsd_package pacman_package portage_package smartos_package windows_package yum_package zypper_package}.include?(name)
+      description << { "notes_resource_based_on_package" => true } if %w{apt_package bff_package dnf_package homebrew_package ips_package openbsd_package pacman_package portage_package smartos_package windows_package yum_package zypper_package pacman_package freebsd_package}.include?(name)
 
       description
     end