Move code comments to resource description and add warning from the docs site.

Signed-off-by: Pete Higgins <pete@peterhiggins.org>

1 files changed, 18 insertions, 13 deletions

diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index a7b19c967c..492c14e81d 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -22,19 +22,6 @@ require_relative "../dist"
 
 class Chef
   class Resource
-    # Use the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the chef-client.
-    # When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file
-    # resources.
-    #
-    # The chef_gem resource works with all of the same properties and options as the gem_package resource, but does not
-    # accept the gem_binary property because it always uses the CurrentGemEnvironment under which the chef-client is
-    # running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the
-    # following:
-    #  - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is
-    #    installed
-    #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
-    #    immediately after it is installed
-
     require_relative "gem_package"
     require_relative "../dist"
 
@@ -42,6 +29,24 @@ class Chef
       unified_mode true
       provides :chef_gem
 
+      description <<~DESC
+        Use the **chef_gem** resource to install a gem only for the instance of Ruby that is dedicated to the chef-client.
+        When a gem is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources.
+
+        The **chef_gem** resource works with all of the same properties and options as the **gem_package** resource, but does not
+        accept the `gem_binary` property because it always uses the `CurrentGemEnvironment` under which the `chef-client` is
+        running. In addition to performing actions similar to the **gem_package** resource, the **chef_gem** resource does the
+        following:
+        - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is installed.
+        - Runs `Gem.clear_paths` after the action, ensuring that gem is aware of changes so that it can be required immediately after it is installed.
+
+        Warning: The **chef_gem** and **gem_package** resources are both used to install Ruby gems. For any machine on which Chef Infra Client is
+        installed, there are two instances of Ruby. One is the standard, system-wide instance of Ruby and the other is a dedicated instance that is
+        available only to Chef Infra Client.
+        Use the **chef_gem** resource to install gems into the instance of Ruby that is dedicated to Chef Infra Client.
+        Use the **gem_package** resource to install all other gems (i.e. install gems system-wide).
+      DESC
+
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
         identity: true