Add more descriptions to actions for documentation

Improve the automatically generated docs.

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

5 files changed, 26 insertions, 25 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/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
       ```