Merge pull request #11922 from chef/docs

Add more descriptions to actions for documentation

9 files changed, 133 insertions, 36 deletions

diff --git a/lib/chef/provider/subversion.rb b/lib/chef/provider/subversion.rb
index 7f49e2139f..e60b684bce 100644
--- a/lib/chef/provider/subversion.rb
+++ b/lib/chef/provider/subversion.rb
@@ -55,7 +55,7 @@ class Chef
         end
       end
 
-      action :checkout do
+      action :checkout, description: "Clone or check out the source. When a checkout is available, this provider does nothing." do
         if target_dir_non_existent_or_empty?
           converge_by("perform checkout of #{new_resource.repository} into #{new_resource.destination}") do
             shell_out!(checkout_command, run_options)
@@ -65,7 +65,7 @@ class Chef
         end
       end
 
-      action :export do
+      action :export, description: "Export the source, excluding or removing any version control artifacts." do
         if target_dir_non_existent_or_empty?
           action_force_export
         else
@@ -73,13 +73,13 @@ class Chef
         end
       end
 
-      action :force_export do
+      action :force_export, description: "Export the source, excluding or removing any version control artifacts and force an export of the source that is overwriting the existing copy (if it exists)." do
         converge_by("export #{new_resource.repository} into #{new_resource.destination}") do
           shell_out!(export_command, run_options)
         end
       end
 
-      action :sync do
+      action :sync, description: "Update the source to the specified version, or get a new clone or checkout. This action causes a hard reset of the index and working tree, discarding any uncommitted changes." do
         assert_target_directory_valid!
         if ::File.exist?(::File.join(new_resource.destination, ".svn"))
           current_rev = find_current_revision
diff --git a/lib/chef/provider/systemd_unit.rb b/lib/chef/provider/systemd_unit.rb
index 26a20814f5..c0e0aee93c 100644
--- a/lib/chef/provider/systemd_unit.rb
+++ b/lib/chef/provider/systemd_unit.rb
@@ -22,6 +22,7 @@ require_relative "../resource/file"
 require_relative "../resource/file/verification/systemd_unit"
 require "iniparse"
 require "shellwords" unless defined?(Shellwords)
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Provider
@@ -75,7 +76,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Create a systemd unit file, if it does not already exist." do
         if current_resource.content != new_resource.to_ini
           converge_by("creating unit: #{new_resource.unit_name}") do
             manage_unit_file(:create)
@@ -84,7 +85,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Delete a systemd unit file, if it exists." do
         if ::File.exist?(unit_path)
           converge_by("deleting unit: #{new_resource.unit_name}") do
             manage_unit_file(:delete)
@@ -93,19 +94,19 @@ class Chef
         end
       end
 
-      action :preset do
+      action :preset, description: "Restore the preset '`enable`/`disable`' configuration for a systemd unit. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do
         converge_by("restoring enable/disable preset configuration for unit: #{new_resource.unit_name}") do
           systemctl_execute!(:preset, new_resource.unit_name)
         end
       end
 
-      action :revert do
+      action :revert, description: "Revert to a vendor's version of a systemd unit file. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do
         converge_by("reverting to vendor version of unit: #{new_resource.unit_name}") do
           systemctl_execute!(:revert, new_resource.unit_name)
         end
       end
 
-      action :enable do
+      action :enable, description: "Ensure the unit will be started after the next system boot." do
         if current_resource.static
           logger.debug("#{new_resource.unit_name} is a static unit, enabling is a NOP.")
         end
@@ -121,7 +122,7 @@ class Chef
         end
       end
 
-      action :disable do
+      action :disable, description: "Ensure the unit will not be started after the next system boot." do
         if current_resource.static
           logger.debug("#{new_resource.unit_name} is a static unit, disabling is a NOP.")
         end
@@ -138,14 +139,14 @@ class Chef
         end
       end
 
-      action :reenable do
+      action :reenable, description: "Reenable a unit file. *New in #{ChefUtils::Dist::Infra::PRODUCT} 14.0.*" do
         converge_by("reenabling unit: #{new_resource.unit_name}") do
           systemctl_execute!(:reenable, new_resource.unit_name)
           logger.info("#{new_resource} reenabled")
         end
       end
 
-      action :mask do
+      action :mask, description: "Ensure the unit will not start, even to satisfy dependencies." do
         unless current_resource.masked
           converge_by("masking unit: #{new_resource.unit_name}") do
             systemctl_execute!(:mask, new_resource.unit_name)
@@ -154,7 +155,7 @@ class Chef
         end
       end
 
-      action :unmask do
+      action :unmask, description: "Stop the unit from being masked and cause it to start as specified." do
         if current_resource.masked
           converge_by("unmasking unit: #{new_resource.unit_name}") do
             systemctl_execute!(:unmask, new_resource.unit_name)
@@ -163,7 +164,7 @@ class Chef
         end
       end
 
-      action :start do
+      action :start, description: "Start a systemd unit." do
         unless current_resource.active
           converge_by("starting unit: #{new_resource.unit_name}") do
             systemctl_execute!(:start, new_resource.unit_name, default_env: false)
@@ -172,7 +173,7 @@ class Chef
         end
       end
 
-      action :stop do
+      action :stop, description: "Stop a running systemd unit." do
         if current_resource.active
           converge_by("stopping unit: #{new_resource.unit_name}") do
             systemctl_execute!(:stop, new_resource.unit_name, default_env: false)
@@ -181,14 +182,14 @@ class Chef
         end
       end
 
-      action :restart do
+      action :restart, description: "Restart a systemd unit." do
         converge_by("restarting unit: #{new_resource.unit_name}") do
           systemctl_execute!(:restart, new_resource.unit_name, default_env: false)
           logger.info("#{new_resource} restarted")
         end
       end
 
-      action :reload do
+      action :reload, description: "Reload the configuration file for a systemd unit." do
         if current_resource.active
           converge_by("reloading unit: #{new_resource.unit_name}") do
             systemctl_execute!(:reload, new_resource.unit_name, default_env: false)
@@ -199,21 +200,21 @@ class Chef
         end
       end
 
-      action :try_restart do
+      action :try_restart, description: "Try to restart a systemd unit if the unit is running." do
         converge_by("try-restarting unit: #{new_resource.unit_name}") do
           systemctl_execute!("try-restart", new_resource.unit_name, default_env: false)
           logger.info("#{new_resource} try-restarted")
         end
       end
 
-      action :reload_or_restart do
+      action :reload_or_restart, description: "For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will restart the service so the new configuration is applied." do
         converge_by("reload-or-restarting unit: #{new_resource.unit_name}") do
           systemctl_execute!("reload-or-restart", new_resource.unit_name, default_env: false)
           logger.info("#{new_resource} reload-or-restarted")
         end
       end
 
-      action :reload_or_try_restart do
+      action :reload_or_try_restart, description: "For systemd units that are services, this action reloads the configuration of the service without restarting, if possible; otherwise, it will try to restart the service so the new configuration is applied." do
         converge_by("reload-or-try-restarting unit: #{new_resource.unit_name}") do
           systemctl_execute!("reload-or-try-restart", new_resource.unit_name, default_env: false)
           logger.info("#{new_resource} reload-or-try-restarted")
diff --git a/lib/chef/provider/yum_repository.rb b/lib/chef/provider/yum_repository.rb
index 8269487bbd..a3d19e95d3 100644
--- a/lib/chef/provider/yum_repository.rb
+++ b/lib/chef/provider/yum_repository.rb
@@ -31,7 +31,7 @@ class Chef
 
       def load_current_resource; end
 
-      action :create do
+      action :create, description: "Create a repository based on the properties." do
         template ::File.join(new_resource.reposdir, "#{new_resource.repositoryid}.repo") do
           if template_available?(new_resource.source)
             source new_resource.source
@@ -69,7 +69,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Remove a repository." do
         # clean the repo cache first
         execute "yum clean all #{new_resource.repositoryid}" do
           command "yum clean all --disablerepo=* --enablerepo=#{new_resource.repositoryid}"
@@ -86,7 +86,7 @@ class Chef
         end
       end
 
-      action :makecache do
+      action :makecache, description: "Force the creation of the repository cache. This is also done automatically when a repository is updated." do
         execute "yum-makecache-#{new_resource.repositoryid}" do
           command "yum -q -y makecache --disablerepo=* --enablerepo=#{new_resource.repositoryid}"
           action :run
diff --git a/lib/chef/provider/zypper_repository.rb b/lib/chef/provider/zypper_repository.rb
index c1c863e20e..08e254b6b8 100644
--- a/lib/chef/provider/zypper_repository.rb
+++ b/lib/chef/provider/zypper_repository.rb
@@ -29,7 +29,7 @@ class Chef
 
       def load_current_resource; end
 
-      action :create do
+      action :create, description: "Add a new Zypper repository." do
         if new_resource.gpgautoimportkeys
           install_gpg_keys(new_resource.gpgkey)
         else
@@ -50,13 +50,13 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Remove a Zypper repository." do
         execute "zypper --quiet --non-interactive removerepo #{escaped_repo_name}" do
           only_if "zypper --quiet lr #{escaped_repo_name}"
         end
       end
 
-      action :refresh do
+      action :refresh, description: "Refresh Zypper repository." do
         execute "zypper --quiet --non-interactive refresh --force #{escaped_repo_name}" do
           only_if "zypper --quiet lr #{escaped_repo_name}"
         end
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index 2d7d2fe8b6..b0ab19002f 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -29,6 +29,106 @@ 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."
+      examples <<~'DOC'
+        **Reload Chef Infra Client configuration data**
+
+        ```ruby
+        ruby_block 'reload_client_config' do
+          block do
+            Chef::Config.from_file('/etc/chef/client.rb')
+          end
+          action :run
+        end
+        ```
+
+        **Run a block on a particular platform**
+        
+        The following example shows how an if statement can be used with the `windows?` method in the Chef Infra Language to run code specific to Microsoft Windows. The code is defined using the ruby_block resource:
+        
+        ```ruby
+        if windows?
+          ruby_block 'copy libmysql.dll into ruby path' do
+            block do
+              require 'fileutils'
+              FileUtils.cp "#{node['mysql']['client']['lib_dir']}\\libmysql.dll",
+                node['mysql']['client']['ruby_dir']
+            end
+            not_if { ::File.exist?("#{node['mysql']['client']['ruby_dir']}\\libmysql.dll") }
+          end
+        end
+        ```
+        
+        **Stash a file in a data bag**
+        
+        The following example shows how to use the ruby_block resource to stash a BitTorrent file in a data bag so that it can be distributed to nodes in the organization.
+        
+        ```ruby
+        ruby_block 'share the torrent file' do
+          block do
+            f = File.open(node['bittorrent']['torrent'],'rb')
+            #read the .torrent file and base64 encode it
+            enc = Base64.encode64(f.read)
+            data = {
+              'id'=>bittorrent_item_id(node['bittorrent']['file']),
+              'seed'=>node.ipaddress,
+              'torrent'=>enc
+            }
+            item = Chef::DataBagItem.new
+            item.data_bag('bittorrent')
+            item.raw_data = data
+            item.save
+          end
+          action :nothing
+          subscribes :create, "bittorrent_torrent[#{node['bittorrent']['torrent']}]", :immediately
+        end
+        ```
+        
+        **Update the /etc/hosts file**
+        
+        The following example shows how the ruby_block resource can be used to update the /etc/hosts file:
+        
+        ```ruby
+        ruby_block 'edit etc hosts' do
+          block do
+            rc = Chef::Util::FileEdit.new('/etc/hosts')
+            rc.search_file_replace_line(/^127\.0\.0\.1 localhost$/,
+              '127.0.0.1 #{new_fqdn} #{new_hostname} localhost')
+            rc.write_file
+          end
+        end
+        ```
+        
+        **Set environment variables**
+        
+        The following example shows how to use variables within a Ruby block to set environment variables using rbenv.
+        
+        ```ruby
+        node.override[:rbenv][:root] = rbenv_root
+        node.override[:ruby_build][:bin_path] = rbenv_binary_path
+        
+        ruby_block 'initialize' do
+          block do
+            ENV['RBENV_ROOT'] = node[:rbenv][:root]
+            ENV['PATH'] = "#{node[:rbenv][:root]}/bin:#{node[:ruby_build][:bin_path]}:#{ENV['PATH']}"
+          end
+        end
+        ```
+
+        **Call methods in a gem**
+        
+        The following example shows how to call methods in gems not shipped in Chef Infra Client
+        
+        ```ruby
+        chef_gem 'mongodb'
+
+        ruby_block 'config_replicaset' do
+          block do
+            MongoDB.configure_replicaset(node, replicaset_name, rs_nodes)
+          end
+          action :run
+        end
+        ```
+        DOC
 
       default_action :run
       allowed_actions :create, :run
diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb
index db20787aa5..7216aa53dd 100644
--- a/lib/chef/resource/scm/subversion.rb
+++ b/lib/chef/resource/scm/subversion.rb
@@ -28,7 +28,7 @@ class Chef
 
       provides :subversion
 
-      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository."
+      description "Use the **subversion** resource to manage source control resources that exist in a Subversion repository. Warning: The subversion resource has known bugs and may not work as expected. For more information see Chef GitHub issues, particularly [#4050](https://github.com/chef/chef/issues/4050) and [#4257](https://github.com/chef/chef/issues/4257)."
       examples <<~DOC
       **Get the latest version of an application**
 
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 9c36206e14..8604590d46 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -131,7 +131,7 @@ class Chef
 
       end
 
-      action :apply, description: "Apply a sysctl value." do
+      action :apply, description: "Set the kernel parameter and update the `sysctl` settings." do
         converge_if_changed do
           # set it temporarily
           set_sysctl_param(new_resource.key, new_resource.value)
@@ -150,7 +150,7 @@ class Chef
         end
       end
 
-      action :remove, description: "Remove a sysctl value." do
+      action :remove, description: "Remove the kernel parameter and update the `sysctl` settings." do
         # only converge the resource if the file actually exists to delete
         if ::File.exist?("#{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf")
           converge_by "removing sysctl config at #{new_resource.conf_dir}/99-chef-#{new_resource.key.tr("/", ".")}.conf" do
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index a100f29add..61294d833d 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -34,7 +34,7 @@ class Chef
 
       ```ruby
       systemd_unit 'etcd.service' do
-        content(Unit: {
+        content({ Unit: {
                   Description: 'Etcd',
                   Documentation: ['https://coreos.com/etcd', 'man:etcd(1)'],
                   After: 'network.target',
@@ -46,7 +46,7 @@ class Chef
                 },
                 Install: {
                   WantedBy: 'multi-user.target',
-                })
+                } })
         action [:create, :enable]
       end
       ```
diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb
index 53e02bf609..c8446bf9b0 100644
--- a/lib/chef/resource/yum_package.rb
+++ b/lib/chef/resource/yum_package.rb
@@ -27,11 +27,7 @@ class Chef
       provides :yum_package
       provides :package, platform_family: "fedora_derived"
 
-      description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum"\
-                  " for the Red Hat and CentOS platforms. The yum_package resource is able to resolve"\
-                  " `provides` data for packages much like Yum can do when it is run from the command line."\
-                  " This allows a variety of options for installing packages, like minimum versions,"\
-                  " virtual provides, and library names."
+      description "Use the **yum_package** resource to install, upgrade, and remove packages with Yum for the Red Hat and CentOS platforms. The yum_package resource is able to resolve `provides` data for packages much like Yum can do when it is run from the command line. This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names. Note: Support for using file names to install packages (as in `yum_package '/bin/sh'`) is not available because the volume of data required to parse for this is excessive."
       examples <<~DOC
         **Install an exact version**: