Improve our automated resource documentation generation

Add more note values to the descriptions, update a few examples for cookstyle and modern gems, and identify a few more resources as providing package on their platform

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

9 files changed, 17 insertions, 21 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/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..7053a14861 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 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."
 
       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..8aa28be369 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. Note: The **ruby** script resource (which is based on the **script** resource) is different from the **ruby_block** resource because Ruby code that is run with this resource is created as a temporary file and executed like other script resources, rather than run inline."
 
       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