Improve the automatically generated docs

Get a few more resources to the point where they are 100% automatically generated. For others there's a long road ahead.

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

12 files changed, 85 insertions, 15 deletions

diff --git a/lib/chef/resource/group.rb b/lib/chef/resource/group.rb
index b76d546b60..545cd0b35d 100644
--- a/lib/chef/resource/group.rb
+++ b/lib/chef/resource/group.rb
@@ -43,16 +43,16 @@ class Chef
 
       property :excluded_members, [String, Array], default: [],
                coerce: proc { |arg| arg.is_a?(String) ? arg.split(/\s*,\s*/) : arg },
-               description: "Remove users from a group. May only be used when append is set to true."
+               description: "Remove users from a group. May only be used when `append` is set to `true`."
 
       property :append, [ TrueClass, FalseClass ], default: false,
-               description: "How members should be appended and/or removed from a group. When true, members are appended and excluded_members are removed. When false, group members are reset to the value of the members property."
+               description: "How members should be appended and/or removed from a group. When true, `members` are appended and `excluded_members` are removed. When `false`, group members are reset to the value of the `members` property."
 
       property :system, [ TrueClass, FalseClass ], default: false,
-               description: "Set if a group belongs to a system group. Set to true if the group belongs to a system group."
+               description: "Set to `true` if the group belongs to a system group."
 
       property :non_unique, [ TrueClass, FalseClass ], default: false,
-               description: "Allow gid duplication. May only be used with the Groupadd provider."
+               description: "Allow gid duplication. May only be used with the `Groupadd` user resource provider."
 
       property :comment, String,
         introduced: "14.9",
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index ccfea70708..7a862e8638 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -51,7 +51,8 @@ class Chef
 
       property :owner, [String, Integer],
         description: "The owner of the Homebrew installation.",
-        default: lazy { find_homebrew_username }
+        default: lazy { find_homebrew_username },
+        default_description: "Calculated default username"\
 
       action :install, description: "Install an application that is packaged as a Homebrew cask." do
         if new_resource.install_cask
diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb
index 3874622005..abdc177512 100644
--- a/lib/chef/resource/homebrew_package.rb
+++ b/lib/chef/resource/homebrew_package.rb
@@ -62,7 +62,7 @@ class Chef
       DOC
 
       property :homebrew_user, [ String, Integer ],
-        description: "The name or uid of the Homebrew owner to be used by #{ChefUtils::Dist::Infra::PRODUCT} when executing a command."
+        description: "The name or uid of the Homebrew owner to be used by #{ChefUtils::Dist::Infra::PRODUCT} when executing a command.\n#{ChefUtils::Dist::Infra::PRODUCT}, by default, will attempt to execute a Homebrew command as the owner of the `/usr/local/bin/brew` executable. If that executable does not exist, #{ChefUtils::Dist::Infra::PRODUCT} will attempt to find the user by executing `which brew`. If that executable cannot be found, #{ChefUtils::Dist::Infra::PRODUCT} will print an error message: `Could not find the 'brew' executable in /usr/local/bin or anywhere on the path.`.\nSet this property to specify the Homebrew owner for situations where Chef Infra Client cannot automatically detect the correct owner.'"
 
     end
   end
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index 9f31463652..05567c5166 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -51,7 +51,8 @@ class Chef
 
       property :owner, String,
         description: "The owner of the Homebrew installation.",
-        default: lazy { find_homebrew_username }
+        default: lazy { find_homebrew_username },
+        default_description: "Calculated default username"
 
       action :tap, description: "Add a Homebrew tap." do
         unless tapped?(new_resource.tap_name)
diff --git a/lib/chef/resource/homebrew_update.rb b/lib/chef/resource/homebrew_update.rb
index 27b352bfb6..ee353f1fe5 100644
--- a/lib/chef/resource/homebrew_update.rb
+++ b/lib/chef/resource/homebrew_update.rb
@@ -88,7 +88,7 @@ class Chef
         end
       end
 
-      action :periodic do
+      action :periodic, description: "Run a periodic update based on the frequency property." do
         return unless macos?
 
         unless brew_up_to_date?
@@ -98,7 +98,7 @@ class Chef
         end
       end
 
-      action :update do
+      action :update, description: "Run an immediate update." do
         return unless macos?
 
         converge_by "force update new lists of packages" do
diff --git a/lib/chef/resource/openbsd_package.rb b/lib/chef/resource/openbsd_package.rb
index af632ebb57..eecb188999 100644
--- a/lib/chef/resource/openbsd_package.rb
+++ b/lib/chef/resource/openbsd_package.rb
@@ -31,6 +31,23 @@ class Chef
 
       description "Use the **openbsd_package** resource to manage packages for the OpenBSD platform."
       introduced "12.1"
+      examples <<~DOC
+        **Install a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :install
+        end
+        ```
+
+        **Remove a package**
+
+        ```ruby
+        openbsd_package 'name of package' do
+          action :remove
+        end
+        ```
+      DOC
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb
index 3523cb536d..ebeb8e34ca 100644
--- a/lib/chef/resource/osx_profile.rb
+++ b/lib/chef/resource/osx_profile.rb
@@ -172,7 +172,7 @@ class Chef
         end
       end
 
-      action :install do
+      action :install, description: "Install the specified configuration profile." do
         unless profile_installed?
           converge_by("install profile #{new_profile_identifier}") do
             profile_path = write_profile_to_disk
@@ -182,7 +182,7 @@ class Chef
         end
       end
 
-      action :remove do
+      action :remove, description: "Remove the specified configuration profile." do
         # Clean up profile after removing it
         if profile_installed?
           converge_by("remove profile #{new_profile_identifier}") do
diff --git a/lib/chef/resource/plist.rb b/lib/chef/resource/plist.rb
index 034b2f319d..4a43605607 100644
--- a/lib/chef/resource/plist.rb
+++ b/lib/chef/resource/plist.rb
@@ -81,7 +81,7 @@ class Chef
         group file_group_cmd.stdout.chomp
       end
 
-      action :set do
+      action :set, description: "Set a value in a plist file." do
         converge_if_changed :path do
           converge_by "create new plist: '#{new_resource.path}'" do
             file new_resource.path do
diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb
index 717b9255b6..be99a397f4 100644
--- a/lib/chef/resource/reboot.rb
+++ b/lib/chef/resource/reboot.rb
@@ -33,6 +33,41 @@ class Chef
                   " immediate notifications. Delayed notifications produce unintuitive and"\
                   " probably undesired results."
       introduced "12.0"
+      examples <<~DOC
+        **Reboot a node immediately**
+
+        ```ruby
+        reboot 'now' do
+          action :nothing
+          reason 'Cannot continue Chef run without a reboot.'
+          delay_mins 2
+        end
+
+        execute 'foo' do
+          command '...'
+          notifies :reboot_now, 'reboot[now]', :immediately
+        end
+        ```
+
+        **Reboot a node at the end of a Chef Infra Client run**
+
+        ```ruby
+        reboot 'app_requires_reboot' do
+          action :request_reboot
+          reason 'Need to reboot when the run completes successfully.'
+          delay_mins 5
+        end
+        ```
+
+        **Cancel a reboot**
+
+        ```ruby
+        reboot 'cancel_reboot_request' do
+          action :cancel
+          reason 'Cancel a previous end-of-run reboot request.'
+        end
+        ```
+    DOC
 
       property :reason, String,
         description: "A string that describes the reboot action.",
diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb
index 502419beb0..03567e004b 100644
--- a/lib/chef/resource/rhsm_repo.rb
+++ b/lib/chef/resource/rhsm_repo.rb
@@ -26,6 +26,21 @@ class Chef
 
       description "Use the **rhsm_repo** resource to enable or disable Red Hat Subscription Manager repositories that are made available via attached subscriptions."
       introduced "14.0"
+      examples <<~DOC
+        **Enable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms'
+        ```
+
+        **Disable an RHSM repository**
+
+        ```ruby
+        rhsm_repo 'rhel-7-server-extras-rpms' do
+          action :disable
+        end
+        ```
+      DOC
 
       property :repo_name, String,
         description: "An optional property for specifying the repository name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/ssh_known_hosts_entry.rb b/lib/chef/resource/ssh_known_hosts_entry.rb
index 3040732ce8..a8d45f4c12 100644
--- a/lib/chef/resource/ssh_known_hosts_entry.rb
+++ b/lib/chef/resource/ssh_known_hosts_entry.rb
@@ -75,7 +75,8 @@ class Chef
 
       property :group, [String, Integer],
         description: "The file group for the ssh_known_hosts file.",
-        default: lazy { node["root_group"] }
+        default: lazy { node["root_group"] },
+        default_description: "The root user's group depending on platform."
 
       property :hash_entries, [TrueClass, FalseClass],
         description: "Hash the hostname and addresses in the ssh_known_hosts file for privacy.",
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 12b01b7f95..d028af80bf 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -170,7 +170,7 @@ class Chef
         end
       end
 
-      action :create, description: "Create a single sudoers config in the sudoers.d directory." do
+      action :create, description: "Create a single sudoers configuration file in the `sudoers.d` directory." do
         validate_properties
 
         if docker? # don't even put this into resource collection unless we're in docker
@@ -228,7 +228,7 @@ class Chef
       end
 
       # Removes a user from the sudoers group
-      action :delete, description: "Remove a sudoers config from the sudoers.d directory." do
+      action :delete, description: "Remove a sudoers configuration file from the `sudoers.d` directory." do
         file "#{new_resource.config_prefix}/sudoers.d/#{new_resource.filename}" do
           action :delete
         end