Merge pull request #10988 from chef/docs_automation

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

32 files changed, 69 insertions, 165 deletions

diff --git a/lib/chef/resource/archive_file.rb b/lib/chef/resource/archive_file.rb
index 4d77ee979b..c1e51cfaa1 100644
--- a/lib/chef/resource/archive_file.rb
+++ b/lib/chef/resource/archive_file.rb
@@ -85,8 +85,7 @@ class Chef
       alias_method :extract_options, :options
       alias_method :extract_to, :destination
 
-      action :extract do
-        description "Extract and archive file."
+      action :extract, description: "Extract and archive file." do
 
         require_libarchive
 
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 3039f709c8..e17bf3bea2 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -57,10 +57,7 @@ class Chef
         introduced: "15.5",
         default: false, desired_state: false # FIXME: make this default to true
 
-      action :install do
-
-        description "Install build essential packages"
-
+      action :install, description: "Install build essential packages" do
         case
         when debian?
           package %w{ autoconf binutils-doc bison build-essential flex gettext ncurses-dev }
@@ -122,8 +119,7 @@ class Chef
         end
       end
 
-      action :upgrade do
-        description "Upgrade build essential (Xcode Command Line) tools on macOS"
+      action :upgrade, description: "Upgrade build essential (Xcode Command Line) tools on macOS" do
 
         if macos?
           pkg_label = xcode_cli_package_label
diff --git a/lib/chef/resource/chef_handler.rb b/lib/chef/resource/chef_handler.rb
index a006b2648a..a66d290380 100644
--- a/lib/chef/resource/chef_handler.rb
+++ b/lib/chef/resource/chef_handler.rb
@@ -194,9 +194,7 @@ class Chef
 
       # This action needs to find an rb file that presumably contains the indicated class in it and the
       # load that file. It then instantiates that class by name and registers it as a handler.
-      action :enable do
-        description "Enables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node"
-
+      action :enable, description: "Enables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node" do
         class_name = new_resource.class_name
         new_resource.type.each do |type, enable|
           next unless enable
@@ -218,9 +216,7 @@ class Chef
         end
       end
 
-      action :disable do
-        description "Disables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node"
-
+      action :disable, description: "Disables the handler for the current #{ChefUtils::Dist::Infra::PRODUCT} run on the current node" do
         new_resource.type.each_key do |type|
           unregister_handler(type, new_resource.class_name)
         end
diff --git a/lib/chef/resource/chef_vault_secret.rb b/lib/chef/resource/chef_vault_secret.rb
index 1c8fa985f9..80e3f0f471 100644
--- a/lib/chef/resource/chef_vault_secret.rb
+++ b/lib/chef/resource/chef_vault_secret.rb
@@ -88,8 +88,7 @@ class Chef
 
       end
 
-      action :create do
-        description "Creates the item, or updates it if it already exists."
+      action :create, description: "Creates the item, or updates it if it already exists." do
 
         converge_if_changed do
           item = ChefVault::Item.new(new_resource.data_bag, new_resource.id)
@@ -111,15 +110,11 @@ class Chef
         end
       end
 
-      action :create_if_missing do
-        description "Calls the create action unless it exists."
-
+      action :create_if_missing, description: "Calls the create action unless it exists." do
         action_create if current_resource.nil?
       end
 
-      action :delete do
-        description "Deletes the item and the item's keys ('id'_keys)."
-
+      action :delete, description: "Deletes the item and the item's keys ('id'_keys)." do
         chef_data_bag_item new_resource.id do
           data_bag new_resource.data_bag
           action :delete
diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb
index c4f100c28d..637d250e9b 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -68,9 +68,7 @@ class Chef
         data ? data.attribute("value").to_s : nil # REXML just returns nil if it can't find anything so avoid an undefined method error
       end
 
-      action :set do
-        description "Sets a Chocolatey config value."
-
+      action :set, description: "Sets a Chocolatey config value." do
         raise "#{new_resource}: When adding a Chocolatey config you must pass the 'value' property!" unless new_resource.value
 
         converge_if_changed do
@@ -78,9 +76,7 @@ class Chef
         end
       end
 
-      action :unset do
-        description "Unsets a Chocolatey config value."
-
+      action :unset, description: "Unsets a Chocolatey config value." do
         if current_resource
           converge_by("unset Chocolatey config '#{new_resource.config_key}'") do
             shell_out!(choco_cmd("unset"))
diff --git a/lib/chef/resource/chocolatey_feature.rb b/lib/chef/resource/chocolatey_feature.rb
index 66752fbd5d..764bbca99d 100644
--- a/lib/chef/resource/chocolatey_feature.rb
+++ b/lib/chef/resource/chocolatey_feature.rb
@@ -65,9 +65,7 @@ class Chef
         data ? data.attribute("enabled").to_s : nil # REXML just returns nil if it can't find anything so avoid an undefined method error
       end
 
-      action :enable do
-        description "Enables a named Chocolatey feature."
-
+      action :enable, description: "Enables a named Chocolatey feature" do
         if current_resource.feature_state != true
           converge_by("enable Chocolatey feature '#{new_resource.feature_name}'") do
             shell_out!(choco_cmd("enable"))
@@ -75,9 +73,7 @@ class Chef
         end
       end
 
-      action :disable do
-        description "Disables a named Chocolatey feature."
-
+      action :disable, description: "Disables a named Chocolatey feature" do
         if current_resource.feature_state == true
           converge_by("disable Chocolatey feature '#{new_resource.feature_name}'") do
             shell_out!(choco_cmd("disable"))
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index cee4289682..796860a531 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -89,8 +89,7 @@ class Chef
         data ? data.attributes : nil # REXML just returns nil if it can't find anything so avoid an undefined method error
       end
 
-      action :add do
-        description "Adds a Chocolatey source."
+      action :add, description: "Adds a Chocolatey source" do
 
         raise "#{new_resource}: When adding a Chocolatey source you must pass the 'source' property!" unless new_resource.source
 
@@ -99,8 +98,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Removes a Chocolatey source."
+      action :remove, description: "Removes a Chocolatey source" do
 
         if current_resource
           converge_by("remove Chocolatey source '#{new_resource.source_name}'") do
@@ -109,9 +107,7 @@ class Chef
         end
       end
 
-      action :disable do
-        description "Disables a Chocolatey source."
-
+      action :disable, description: "Disables a Chocolatey source." do
         if current_resource.disabled != true
           converge_by("disable Chocolatey source '#{new_resource.source_name}'") do
             shell_out!(choco_cmd("disable"))
@@ -119,9 +115,7 @@ class Chef
         end
       end
 
-      action :enable do
-        description "Enables a Chocolatey source."
-
+      action :enable, description: "Enables a Chocolatey source." do
         if current_resource.disabled == true
           converge_by("enable Chocolatey source '#{new_resource.source_name}'") do
             shell_out!(choco_cmd("enable"))
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index 3ea777ce9c..2183e6fb33 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -64,8 +64,7 @@ class Chef
           "default" => "/etc",
       }.freeze
 
-      action :allow do
-        description "Add the user to the cron.allow file."
+      action :allow, description: "Add the user to the cron.allow file" do
         allow_path = ::File.join(value_for_platform_family(CRON_PATHS), "cron.allow")
 
         with_run_context :root do
@@ -81,8 +80,7 @@ class Chef
         end
       end
 
-      action :deny do
-        description "Add the user to the cron.deny file."
+      action :deny, description: "Add the user to the cron.deny file." do
         deny_path = ::File.join(value_for_platform_family(CRON_PATHS), "cron.deny")
 
         with_run_context :root do
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index c6cd04156c..f294515895 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -121,9 +121,7 @@ class Chef
         end
       end
 
-      action :install do
-        description "Installs the application."
-
+      action :install, description: "Installs the application" do
         if current_resource.nil?
           if new_resource.source
             remote_file dmg_file do
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index 4c68afaab0..31134545fc 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -53,9 +53,7 @@ class Chef
         description: "The owner of the Homebrew installation.",
         default: lazy { find_homebrew_username }
 
-      action :install do
-        description "Install an application packaged as a Homebrew cask."
-
+      action :install, description: "Install an application packaged as a Homebrew cask" do
         homebrew_tap "homebrew/cask" if new_resource.install_cask
 
         unless casked?
@@ -68,9 +66,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove an application packaged as a Homebrew cask."
-
+      action :remove, description: "Remove an application packaged as a Homebrew cask" do
         homebrew_tap "homebrew/cask" if new_resource.install_cask
 
         if casked?
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index 937a9ab420..672f2f9995 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -53,9 +53,7 @@ class Chef
         description: "The owner of the Homebrew installation.",
         default: lazy { find_homebrew_username }
 
-      action :tap do
-        description "Add a Homebrew tap."
-
+      action :tap, description: "Add a Homebrew tap" do
         unless tapped?(new_resource.tap_name)
           converge_by("tap #{new_resource.tap_name}") do
             shell_out!("#{new_resource.homebrew_path} tap #{new_resource.full ? "--full" : ""} #{new_resource.tap_name} #{new_resource.url || ""}",
@@ -66,9 +64,7 @@ class Chef
         end
       end
 
-      action :untap do
-        description "Remove a Homebrew tap."
-
+      action :untap, description: "Remove a Homebrew tap" do
         if tapped?(new_resource.tap_name)
           converge_by("untap #{new_resource.tap_name}") do
             shell_out!("#{new_resource.homebrew_path} untap #{new_resource.tap_name}",
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index e63c0be54e..746ef34a5b 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -99,9 +99,7 @@ class Chef
         end
       end
 
-      action :set do
-        description "Sets the node's hostname."
-
+      action :set, description: "Sets the node's hostname" do
         if !windows?
           ohai "reload hostname" do
             plugin "hostname"
diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb
index 485511470e..e51c1e038d 100644
--- a/lib/chef/resource/kernel_module.rb
+++ b/lib/chef/resource/kernel_module.rb
@@ -93,9 +93,7 @@ class Chef
         description: "The modprobe.d directory.",
         default: "/etc/modprobe.d"
 
-      action :install do
-        description "Load kernel module, and ensure it loads on reboot."
-
+      action :install, description: "Load kernel module, and ensure it loads on reboot" do
         with_run_context :root do
           find_resource(:execute, "update initramfs") do
             command initramfs_command
@@ -123,8 +121,7 @@ class Chef
         end
       end
 
-      action :uninstall do
-        description "Unload a kernel module and remove module config, so it doesn't load on reboot."
+      action :uninstall, description: "Unload a kernel module and remove module config, so it doesn't load on reboot" do
         with_run_context :root do
           find_resource(:execute, "update initramfs") do
             command initramfs_command
@@ -149,9 +146,7 @@ class Chef
         action_unload
       end
 
-      action :blacklist do
-        description "Blacklist a kernel module."
-
+      action :blacklist, description: "Blacklist a kernel module" do
         with_run_context :root do
           find_resource(:execute, "update initramfs") do
             command initramfs_command
@@ -167,9 +162,7 @@ class Chef
         action_unload
       end
 
-      action :disable do
-        description "Disable a kernel module."
-
+      action :disable, description: "Disable a kernel module" do
         with_run_context :root do
           find_resource(:execute, "update initramfs") do
             command initramfs_command
@@ -185,9 +178,7 @@ class Chef
         action_unload
       end
 
-      action :load do
-        description "Load a kernel module."
-
+      action :load, description: "Load a kernel module" do
         unless module_loaded?
           converge_by("load kernel module #{new_resource.modname}") do
             shell_out!("modprobe #{new_resource.modname}")
@@ -195,9 +186,7 @@ class Chef
         end
       end
 
-      action :unload do
-        description "Unload kernel module."
-
+      action :unload, description: "Unload kernel module" do
         if module_loaded?
           converge_by("unload kernel module #{new_resource.modname}") do
             shell_out!("modprobe -r #{new_resource.modname}")
diff --git a/lib/chef/resource/locale.rb b/lib/chef/resource/locale.rb
index fafa1a5caa..8800ec04f2 100644
--- a/lib/chef/resource/locale.rb
+++ b/lib/chef/resource/locale.rb
@@ -97,8 +97,7 @@ class Chef
         powershell_exec("Get-WinSystemLocale").result["Name"]
       end
 
-      action :update do
-        description "Update the system's locale."
+      action :update, description: "Update the system's locale" do
         converge_if_changed do
           set_system_locale
         end
diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index a150aeb9ed..59d9773ed3 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -140,9 +140,7 @@ class Chef
         state_cmd
       end
 
-      action :write do
-        description "Write the value to the specified domain/key."
-
+      action :write, description: "Write the value to the specified domain/key" do
         converge_if_changed do
           cmd = defaults_modify_cmd
           Chef::Log.debug("Updating defaults value by shelling out: #{cmd.join(" ")}")
@@ -151,9 +149,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Delete a key from a domain."
-
+      action :delete, description: "Delete a key from a domain" do
         # if it's not there there's nothing to remove
         return unless current_resource
 
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index bf9424f35f..49f8a180ee 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -131,9 +131,7 @@ class Chef
 
       end
 
-      action :apply do
-        description "Apply a sysctl value."
-
+      action :apply, description: "Apply a sysctl value" do
         converge_if_changed do
           # set it temporarily
           set_sysctl_param(new_resource.key, new_resource.value)
@@ -152,9 +150,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove a sysctl value."
-
+      action :remove, description: "Remove a sysctl value" 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/timezone.rb b/lib/chef/resource/timezone.rb
index 04e5884b88..584c2437c7 100644
--- a/lib/chef/resource/timezone.rb
+++ b/lib/chef/resource/timezone.rb
@@ -119,9 +119,7 @@ class Chef
         end
       end
 
-      action :set do
-        description "Set the timezone."
-
+      action :set, description: "Set the system timezone" do
         # we have to check windows first since the value isn't case sensitive here
         if windows?
           unless current_windows_tz.casecmp?(new_resource.timezone)
diff --git a/lib/chef/resource/user_ulimit.rb b/lib/chef/resource/user_ulimit.rb
index d138eeabf3..8679161693 100644
--- a/lib/chef/resource/user_ulimit.rb
+++ b/lib/chef/resource/user_ulimit.rb
@@ -78,7 +78,7 @@ class Chef
                coerce: proc { |m| m.end_with?(".conf") ? m : m + ".conf" },
                default: lazy { |r| r.username == "*" ? "00_all_limits.conf" : "#{r.username}_limits.conf" }
 
-      action :create do
+      action :create, description: "Create a ulimit configuration file" do
         template "/etc/security/limits.d/#{new_resource.filename}" do
           source ::File.expand_path("support/ulimit.erb", __dir__)
           local true
@@ -106,7 +106,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Delete an existing ulimit configuration file"  do
         file "/etc/security/limits.d/#{new_resource.filename}" do
           action :delete
         end
diff --git a/lib/chef/resource/windows_ad_join.rb b/lib/chef/resource/windows_ad_join.rb
index 731ce9333e..0c14150753 100644
--- a/lib/chef/resource/windows_ad_join.rb
+++ b/lib/chef/resource/windows_ad_join.rb
@@ -97,9 +97,7 @@ class Chef
       property :sensitive, [TrueClass, FalseClass],
         default: true, desired_state: false
 
-      action :join do
-        description "Join the Active Directory domain."
-
+      action :join, description: "Join the Active Directory domain" do
         unless on_desired_domain?
           cmd = "$pswd = ConvertTo-SecureString \'#{new_resource.domain_password}\' -AsPlainText -Force;"
           cmd << "$credential = New-Object System.Management.Automation.PSCredential (\"#{sanitize_usename}\",$pswd);"
@@ -129,9 +127,7 @@ class Chef
         end
       end
 
-      action :leave do
-        description "Leave the Active Directory domain."
-
+      action :leave, description: "Leave an Active Directory domain and re-join a workgroup" do
         if joined_to_domain?
           cmd = ""
           cmd << "$pswd = ConvertTo-SecureString \'#{new_resource.domain_password}\' -AsPlainText -Force;"
diff --git a/lib/chef/resource/windows_audit_policy.rb b/lib/chef/resource/windows_audit_policy.rb
index 433e18e197..922a4eaf66 100644
--- a/lib/chef/resource/windows_audit_policy.rb
+++ b/lib/chef/resource/windows_audit_policy.rb
@@ -152,7 +152,7 @@ class Chef
       property :audit_base_directories, [true, false],
                description: "Setting this audit policy option to true will force the system to assign a System Access Control List to named objects to enable auditing of container objects such as directories."
 
-      action :set do
+      action :set, description: "Configure an audit policy" do
         unless new_resource.subcategory.nil?
           new_resource.subcategory.each do |subcategory|
             next if subcategory_configured?(subcategory, new_resource.success, new_resource.failure)
diff --git a/lib/chef/resource/windows_auto_run.rb b/lib/chef/resource/windows_auto_run.rb
index 4885a02676..4d3f7cdcaa 100644
--- a/lib/chef/resource/windows_auto_run.rb
+++ b/lib/chef/resource/windows_auto_run.rb
@@ -57,8 +57,7 @@ class Chef
 
       alias_method :program, :path
 
-      action :create do
-        description "Create an item to be run at login."
+      action :create, description: "Create an item to be run at login" do
 
         data = "\"#{new_resource.path}\""
         data << " #{new_resource.args}" if new_resource.args
@@ -73,9 +72,7 @@ class Chef
         end
       end
 
-      action :remove do
-        description "Remove an item that was previously setup to run at login"
-
+      action :remove, description: "Remove an item that was previously configured to run at login" do
         registry_key registry_path do
           values [{
             name: new_resource.program_name,
diff --git a/lib/chef/resource/windows_certificate.rb b/lib/chef/resource/windows_certificate.rb
index 0879f04636..6d0e080b3f 100644
--- a/lib/chef/resource/windows_certificate.rb
+++ b/lib/chef/resource/windows_certificate.rb
@@ -92,9 +92,7 @@ class Chef
         default: false,
         introduced: "16.8"
 
-      action :create do
-        description "Creates or updates a certificate."
-
+      action :create, description: "Creates or updates a certificate" do
         # Extension of the certificate
         ext = ::File.extname(new_resource.source)
 
@@ -103,8 +101,7 @@ class Chef
       end
 
       # acl_add is a modify-if-exists operation : not idempotent
-      action :acl_add do
-        description "Adds read-only entries to a certificate's private key ACL."
+      action :acl_add, description: "Adds read-only entries to a certificate's private key ACL" do
 
         if ::File.exist?(new_resource.source)
           hash = "$cert.GetCertHashString()"
@@ -127,8 +124,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Deletes a certificate."
+      action :delete, description: "Deletes a certificate" do
         cert_obj = fetch_cert
         if cert_obj
           converge_by("Deleting certificate #{new_resource.source} from Store #{new_resource.store_name}") do
@@ -139,9 +135,7 @@ class Chef
         end
       end
 
-      action :fetch do
-        description "Fetches a certificate."
-
+      action :fetch, description: "Fetches a certificate" do
         cert_obj = fetch_cert
         if cert_obj
           show_or_store_cert(cert_obj)
@@ -150,9 +144,7 @@ class Chef
         end
       end
 
-      action :verify do
-        description ""
-
+      action :verify, description: "Verifies a certificate and logs the result" do
         out = verify_cert
         if !!out == out
           out = out ? "Certificate is valid" : "Certificate not valid"
diff --git a/lib/chef/resource/windows_dfs_folder.rb b/lib/chef/resource/windows_dfs_folder.rb
index 31f6814bcf..9d81255dea 100644
--- a/lib/chef/resource/windows_dfs_folder.rb
+++ b/lib/chef/resource/windows_dfs_folder.rb
@@ -42,9 +42,7 @@ class Chef
       property :description, String,
         description: "Description for the share."
 
-      action :create do
-        description "Creates the folder in dfs namespace."
-
+      action :create, description: "Creates the folder in dfs namespace" do
         raise "target_path is required for install" unless property_is_set?(:target_path)
         raise "description is required for install" unless property_is_set?(:description)
 
@@ -62,9 +60,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Deletes the folder in the dfs namespace."
-
+      action :delete, description: "Deletes the folder in the dfs namespace" do
         powershell_script "Delete DFS Namespace" do
           code <<-EOH
             Remove-DfsnFolder -Path '\\\\#{ENV["COMPUTERNAME"]}\\#{new_resource.namespace_name}\\#{new_resource.folder_path}' -Force
diff --git a/lib/chef/resource/windows_dfs_namespace.rb b/lib/chef/resource/windows_dfs_namespace.rb
index ddd8a0ee26..a0e2ed20fc 100644
--- a/lib/chef/resource/windows_dfs_namespace.rb
+++ b/lib/chef/resource/windows_dfs_namespace.rb
@@ -52,9 +52,7 @@ class Chef
         description: "The root from which to create the DFS tree. Defaults to C:\\DFSRoots.",
         default: 'C:\\DFSRoots'
 
-      action :create do
-        description "Creates the dfs namespace on the server."
-
+      action :create, description: "Creates the dfs namespace on the server" do
         directory file_path do
           action :create
           recursive true
@@ -84,9 +82,7 @@ class Chef
         end
       end
 
-      action :delete do
-        description "Deletes a DFS Namespace including the directory on disk."
-
+      action :delete, description: "Deletes a DFS Namespace including the directory on disk" do
         powershell_script "Delete DFS Namespace" do
           code <<-EOH
             Remove-DfsnRoot -Path '\\\\#{ENV["COMPUTERNAME"]}\\#{new_resource.namespace_name}' -Force
diff --git a/lib/chef/resource/windows_dfs_server.rb b/lib/chef/resource/windows_dfs_server.rb
index fc161f8189..e93185c245 100644
--- a/lib/chef/resource/windows_dfs_server.rb
+++ b/lib/chef/resource/windows_dfs_server.rb
@@ -65,9 +65,7 @@ class Chef
         sync_interval_secs results["SyncIntervalSec"]
       end
 
-      action :configure do
-        description "Configure DFS settings."
-
+      action :configure, description: "Configure DFS settings" do
         converge_if_changed do
           dfs_cmd = "Set-DfsnServerConfiguration -ComputerName '#{ENV["COMPUTERNAME"]}' -UseFqdn $#{new_resource.use_fqdn} -LdapTimeoutSec #{new_resource.ldap_timeout_secs} -SyncIntervalSec #{new_resource.sync_interval_secs}"
           dfs_cmd << " -EnableSiteCostedReferrals $#{new_resource.enable_site_costed_referrals}" if new_resource.enable_site_costed_referrals != current_resource.enable_site_costed_referrals
diff --git a/lib/chef/resource/windows_dns_record.rb b/lib/chef/resource/windows_dns_record.rb
index 329e1a3857..f68412aee6 100644
--- a/lib/chef/resource/windows_dns_record.rb
+++ b/lib/chef/resource/windows_dns_record.rb
@@ -49,9 +49,7 @@ class Chef
         default: "localhost",
         introduced: "16.3"
 
-      action :create do
-        description "Creates and updates the DNS entry."
-
+      action :create, description: "Creates and updates the DNS entry" do
         windows_feature "RSAT-DNS-Server" do
           not_if new_resource.dns_server.casecmp?("localhost")
         end
@@ -61,9 +59,7 @@ class Chef
         run_dsc_resource "Present"
       end
 
-      action :delete do
-        description "Deletes a DNS entry."
-
+      action :delete, description: "Deletes a DNS entry" do
         windows_feature "RSAT-DNS-Server" do
           not_if new_resource.dns_server.casecmp?("localhost")
         end
diff --git a/lib/chef/resource/windows_dns_zone.rb b/lib/chef/resource/windows_dns_zone.rb
index 09555c880c..91a4a22147 100644
--- a/lib/chef/resource/windows_dns_zone.rb
+++ b/lib/chef/resource/windows_dns_zone.rb
@@ -40,17 +40,13 @@ class Chef
         description: "The type of DNS server, Domain or Standalone.",
         default: "Domain", equal_to: %w{Domain Standalone}
 
-      action :create do
-        description "Creates and updates a DNS Zone."
-
+      action :create, description: "Creates and updates a DNS Zone" do
         powershell_package "xDnsServer"
 
         run_dsc_resource "Present"
       end
 
-      action :delete do
-        description "Deletes a DNS Zone."
-
+      action :delete, description: "Deletes a DNS Zone" do
         powershell_package "xDnsServer"
 
         run_dsc_resource "Absent"
diff --git a/lib/chef/resource/windows_shortcut.rb b/lib/chef/resource/windows_shortcut.rb
index f2264445ba..a40a90fe40 100644
--- a/lib/chef/resource/windows_shortcut.rb
+++ b/lib/chef/resource/windows_shortcut.rb
@@ -69,9 +69,7 @@ class Chef
         iconlocation(link.IconLocation)
       end
 
-      action :create do
-        description "Create or modify a Windows shortcut."
-
+      action :create, description: "Create or modify a Windows shortcut" do
         converge_if_changed do
           converge_by "creating shortcut #{new_resource.shortcut_name}" do
             link = WIN32OLE.new("WScript.Shell").CreateShortcut(new_resource.shortcut_name)
diff --git a/lib/chef/resource/windows_uac.rb b/lib/chef/resource/windows_uac.rb
index db5d5fd173..23a5e4fc28 100644
--- a/lib/chef/resource/windows_uac.rb
+++ b/lib/chef/resource/windows_uac.rb
@@ -72,7 +72,7 @@ class Chef
         equal_to: %i{auto_deny secure_prompt_for_creds prompt_for_creds},
         default: :prompt_for_creds
 
-      action :configure do
+      action :configure, description: "Configures UAC by setting registry keys at `HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System`" do
         description 'Configures UAC by setting registry keys at \'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System\''
 
         registry_key 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System' do
diff --git a/lib/chef/resource/windows_user_privilege.rb b/lib/chef/resource/windows_user_privilege.rb
index 971338303d..cd106ab58b 100644
--- a/lib/chef/resource/windows_user_privilege.rb
+++ b/lib/chef/resource/windows_user_privilege.rb
@@ -147,7 +147,7 @@ class Chef
         end
       end
 
-      action :add do
+      action :add, description: "Add a user privilege" do
         ([*new_resource.privilege] - [*current_resource.privilege]).each do |user_right|
           converge_by("adding user '#{new_resource.principal}' privilege #{user_right}") do
             Chef::ReservedNames::Win32::Security.add_account_right(new_resource.principal, user_right)
@@ -155,7 +155,7 @@ class Chef
         end
       end
 
-      action :set do
+      action :set, description: "Set the privileges that are listed in the `privilege` property for only the users listed in the `users` property" do
         if new_resource.users.nil? || new_resource.users.empty?
           raise Chef::Exceptions::ValidationFailed, "Users are required property with set action."
         end
@@ -190,7 +190,7 @@ class Chef
         end
       end
 
-      action :clear do
+      action :clear, description: "Clear all user privileges" do
         new_resource.privilege.each do |privilege|
           accounts = Chef::ReservedNames::Win32::Security.get_account_with_user_rights(privilege)
 
@@ -204,7 +204,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove a user privilege" do
         curr_res_privilege = current_resource.privilege
         missing_res_privileges = (new_resource.privilege - curr_res_privilege)
 
diff --git a/lib/chef/resource/windows_workgroup.rb b/lib/chef/resource/windows_workgroup.rb
index 3c49f7cb3e..f5bd0e91fc 100644
--- a/lib/chef/resource/windows_workgroup.rb
+++ b/lib/chef/resource/windows_workgroup.rb
@@ -87,8 +87,7 @@ class Chef
       property :sensitive, [TrueClass, FalseClass],
         default: true, desired_state: false
 
-      action :join do
-        description "Update the workgroup."
+      action :join, description: "Update the workgroup." do
 
         unless workgroup_member?
           converge_by("join workstation workgroup #{new_resource.workgroup_name}") do
diff --git a/tasks/docs.rb b/tasks/docs.rb
index 5d336a7b14..0a31ead498 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -35,6 +35,8 @@ namespace :docs_site do
       text = ""
       text << "#{resource_name} 'name' do\n"
       properties.each do |p|
+        next if p["name"] == "sensitive" # we don't need to document sensitive twice
+
         pretty_default = pretty_default(p["default"])
 
         text << "  #{p["name"].ljust(padding_size)}"
@@ -139,7 +141,9 @@ namespace :docs_site do
     # TODO:
     # - what to do about "lazy default" for default?
     def properties_list(properties)
-      properties.map do |property|
+      properties.filter_map do |property|
+        next if property["name"] == "sensitive" # we don't need to document sensitive twice
+
         default_val = friendly_default_value(property)
 
         values = {}