Merge pull request #10020 from chef/add_sudo_examples

Add more examples to the resource code

6 files changed, 78 insertions, 4 deletions

diff --git a/lib/chef/resource/alternatives.rb b/lib/chef/resource/alternatives.rb
index 58de3d5102..fe5af6b7b6 100644
--- a/lib/chef/resource/alternatives.rb
+++ b/lib/chef/resource/alternatives.rb
@@ -89,7 +89,7 @@ class Chef
         description: "The path to the alternatives link."
 
       property :path, String,
-        description: "The full path to the original application binary such as `/usr/bin/ruby27`."
+        description: "The absolute path to the original application binary such as `/usr/bin/ruby27`."
 
       property :priority, [String, Integer],
         coerce: proc { |n| n.to_i },
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index b1d464b547..1b996e4c5e 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -66,7 +66,7 @@ class Chef
         description: "The remote URL that is used to download the `.dmg` file, if specified."
 
       property :file, String,
-        description: "The full path to the `.dmg` file on the local system."
+        description: "The absolute path to the `.dmg` file on the local system."
 
       property :owner, [String, Integer],
         description: "The user that should own the package installation."
diff --git a/lib/chef/resource/ssh_known_hosts_entry.rb b/lib/chef/resource/ssh_known_hosts_entry.rb
index 95a1b75644..0bc835392c 100644
--- a/lib/chef/resource/ssh_known_hosts_entry.rb
+++ b/lib/chef/resource/ssh_known_hosts_entry.rb
@@ -29,6 +29,21 @@ class Chef
 
       description "Use the **ssh_known_hosts_entry** resource to add an entry for the specified host in /etc/ssh/ssh_known_hosts or a user's known hosts file if specified."
       introduced "14.3"
+      examples <<~DOC
+      **Add a single entry for github.com with the key auto detected**
+
+      ```ruby
+      ssh_known_hosts_entry 'github.com'
+      ```
+
+      **Add a single entry with your own provided key**
+
+      ```ruby
+      ssh_known_hosts_entry 'github.com' do
+        key 'node.example.com ssh-rsa ...'
+      end
+      ```
+      DOC
 
       property :host, String,
         description: "The host to add to the known hosts file.",
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 377e0e432e..d7babd8f96 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -34,6 +34,33 @@ class Chef
                   " installation of the required sudo version. Chef-supported releases of Ubuntu, SuSE, Debian,"\
                   " and RHEL (6+) all support this feature."
       introduced "14.0"
+      examples <<~DOC
+      **Grant a user sudo privileges for any command**
+
+      ```ruby
+      sudo 'admin' do
+        user 'admin'
+      end
+      ```
+
+      **Grant a user and groups sudo privileges for any command**
+
+      ```ruby
+      sudo 'admins' do
+        users 'bob'
+        groups 'sysadmins, superusers'
+      end
+      ```
+
+      **Grant passwordless sudo privileges for specific commands**
+
+      ```ruby
+      sudo 'passwordless-access' do
+        commands ['/bin/systemctl restart httpd', '/bin/systemctl restart mysql']
+        nopasswd true
+      end
+      ```
+      DOC
 
       # According to the sudo man pages sudo will ignore files in an include dir that have a `.` or `~`
       # We convert either to `__`
@@ -53,7 +80,7 @@ class Chef
         coerce: proc { |x| coerce_groups(x) }
 
       property :commands, Array,
-        description: "An array of commands this sudoer can execute.",
+        description: "An array of full paths to commands this sudoer can execute.",
         default: ["ALL"]
 
       property :host, String,
@@ -112,7 +139,7 @@ class Chef
 
       # handle legacy cookbook property
       def after_created
-        raise "The 'visudo_path' property from the sudo cookbook has been replaced with the 'visudo_binary' property. The path is now more intelligently determined and for most users specifying the path should no longer be necessary. If this resource still cannot determine the path to visudo then provide the full path to the binary with the 'visudo_binary' property." if visudo_path
+        raise "The 'visudo_path' property from the sudo cookbook has been replaced with the 'visudo_binary' property. The path is now more intelligently determined and for most users specifying the path should no longer be necessary. If this resource still cannot determine the path to visudo then provide the absolute path to the binary with the 'visudo_binary' property." if visudo_path
       end
 
       # VERY old legacy properties
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index 7049b34ea7..3d8f31de48 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -26,6 +26,23 @@ class Chef
 
       description "Use the **swap_file** resource to create or delete swap files on Linux systems, and optionally to manage the swappiness configuration for a host."
       introduced "14.0"
+      examples <<~DOC
+      **Create a swap file**
+
+      ```ruby
+      swap_file '/dev/sda1' do
+        size 1024
+      end
+      ```
+
+      **Remove a swap file**
+
+      ```ruby
+      swap_file '/dev/sda1' do
+        action :remove
+      end
+      ```
+      DOC
 
       property :path, String,
         description: "The path where the swap file will be created on the system if it differs from the resource block's name.",
diff --git a/lib/chef/resource/timezone.rb b/lib/chef/resource/timezone.rb
index a7813ce9c2..fe03940e1d 100644
--- a/lib/chef/resource/timezone.rb
+++ b/lib/chef/resource/timezone.rb
@@ -28,6 +28,21 @@ class Chef
 
       description "Use the **timezone** resource to change the system timezone on Windows, Linux, and macOS hosts. Timezones are specified in tz database format, with a complete list of available TZ values for Linux and macOS here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones and for Windows here: https://ss64.com/nt/timezones.html."
       introduced "14.6"
+      examples <<~DOC
+      **Set the timezone to UTC**
+
+      ```ruby
+      timezone 'UTC'
+      ```
+
+      **Set the timezone to UTC with a friendly resource name**
+
+      ```ruby
+      timezone 'Set the host's timezone to UTC' do
+        timezone 'UTC'
+      end
+      ```
+      DOC
 
       property :timezone, String,
         description: "An optional property to set the timezone value if it differs from the resource block's name.",