Add more resource examples to the codebaseexamples

I'm also adding these same examples to the docs.

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

11 files changed, 184 insertions, 1 deletions

diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index e11d35664f..5bb646b548 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -26,6 +26,19 @@ class Chef
 
       description "Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms."
       introduced "12.7"
+      examples <<~DOC
+        Update the Apt repository at a specified interval
+         ```ruby
+        apt_update 'all platforms' do
+        frequency 86400
+        action :periodic
+        end
+        ```
+         Update the Apt repository at the start of a Chef Infra Client run
+         ```ruby
+        apt_update 'update'
+        ```
+      DOC
 
       # allow bare apt_update with no name
       property :name, String, default: ""
diff --git a/lib/chef/resource/archive_file.rb b/lib/chef/resource/archive_file.rb
index 958da23a1b..0cf74bf3e5 100644
--- a/lib/chef/resource/archive_file.rb
+++ b/lib/chef/resource/archive_file.rb
@@ -30,6 +30,15 @@ class Chef
 
       introduced "15.0"
       description "Use the archive_file resource to extract archive files to disk. This resource uses the libarchive library to extract multiple archive formats including tar, gzip, bzip, and zip formats."
+      examples <<~DOC
+        Extract a zip file to a specified directory
+         ```ruby
+        archive_file 'Precompiled.zip' do
+          path '/tmp/Precompiled.zip'
+          destination '/srv/files'
+        end
+        ```
+      DOC
 
       property :path, String,
         name_property: true,
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index b38ec6b24a..c4b4bdb161 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -24,6 +24,18 @@ class Chef
 
       description "Use the build_essential resource to install packages required for compiling C software from source."
       introduced "14.0"
+      examples <<~DOC
+        Install compilation packages
+         ```ruby
+        build_essential
+        ```
+         Install compilation packages during the compilation phase
+         ```ruby
+        build_essential 'Install compilation tools' do
+          compile_time true
+        end
+        ```
+      DOC
 
       # this allows us to use build_essential without setting a name
       property :name, String, default: ""
diff --git a/lib/chef/resource/chocolatey_config.rb b/lib/chef/resource/chocolatey_config.rb
index 2be4b7be0a..1ae7550eec 100644
--- a/lib/chef/resource/chocolatey_config.rb
+++ b/lib/chef/resource/chocolatey_config.rb
@@ -21,6 +21,21 @@ class Chef
 
       description "Use the chocolatey_config resource to add or remove Chocolatey configuration keys."
       introduced "14.3"
+      examples <<~DOC
+        Set the Chocolatey cacheLocation config
+         ```ruby
+        chocolatey_config 'Set cacheLocation config' do
+          config_key 'cacheLocation'
+          value 'C:\temp\choco'
+        end
+        ```
+         Unset a Chocolatey config
+         ```ruby
+        chocolatey_config 'BogusConfig' do
+          action :unset
+        end
+        ```
+      DOC
 
       property :config_key, String, name_property: true,
                description: "An optional property to set the config key name if it differs from the resource block's name."
diff --git a/lib/chef/resource/chocolatey_feature.rb b/lib/chef/resource/chocolatey_feature.rb
index 0fa053935d..447b8546fa 100644
--- a/lib/chef/resource/chocolatey_feature.rb
+++ b/lib/chef/resource/chocolatey_feature.rb
@@ -21,6 +21,20 @@ class Chef
 
       description "Use the chocolatey_feature resource to enable and disable Chocolatey features."
       introduced "15.1"
+      examples <<~DOC
+        Enable the checksumFiles Chocolatey feature
+         ```ruby
+        chocolatey_feature 'checksumFiles' do
+          action :enable
+        end
+        ```
+         Disable the checksumFiles Chocolatey feature
+         ```ruby
+        chocolatey_feature 'checksumFiles' do
+          action :disable
+        end
+        ```
+      DOC
 
       property :feature_name, String, name_property: true,
                description: "The name of the Chocolatey feature to enable or disable."
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 6feae23686..8159452738 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -26,6 +26,21 @@ class Chef
 
       description "Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform."
       introduced "12.7"
+      examples <<~DOC
+        Install a Chocolatey package
+         ```ruby
+        chocolatey_package 'name of package' do
+          action :install
+        end
+        ```
+         Install a package with options with Chocolatey's ``--checksum`` option
+         ```ruby
+        chocolatey_package 'name of package' do
+          options '--checksum 1234567890'
+          action :install
+        end
+        ```
+      DOC
 
       allowed_actions :install, :upgrade, :remove, :purge, :reconfig
 
diff --git a/lib/chef/resource/chocolatey_source.rb b/lib/chef/resource/chocolatey_source.rb
index 9f57e0dbdc..3edb9cb435 100644
--- a/lib/chef/resource/chocolatey_source.rb
+++ b/lib/chef/resource/chocolatey_source.rb
@@ -21,6 +21,21 @@ class Chef
 
       description "Use the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources."
       introduced "14.3"
+      examples <<~DOC
+        Add a Chocolatey source
+         ```ruby
+        chocolatey_source 'MySource' do
+          source 'http://example.com/something'
+          action :add
+        end
+        ```
+         Remove a Chocolatey source
+         ```ruby
+        chocolatey_source 'MySource' do
+          action :remove
+        end
+        ```
+      DOC
 
       property :source_name, String, name_property: true,
                description: "An optional property to set the source name if it differs from the resource block's name."
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index 6c0272b667..37dd5959c5 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -28,6 +28,25 @@ class Chef
 
       introduced "14.4"
       description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files."
+      examples <<~DOC
+        Add the mike user to cron.allow
+         ```ruby
+        cron_access 'mike'
+        ```
+         Add the mike user to cron.deny
+         ```ruby
+        cron_access 'mike' do
+          action :deny
+        end
+        ```
+         Specify the username with the user property
+         ```ruby
+        cron_access 'Deny the tomcat access to cron for security purposes' do
+          user 'jenkins'
+          action :deny
+        end
+        ```
+      DOC
 
       property :user, String,
         description: "An optional property to set the user name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index c9bc8fcb1d..115f60973f 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -26,6 +26,48 @@ class Chef
 
       introduced "14.4"
       description "Use the cron_d resource to manage cron definitions in /etc/cron.d. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      examples <<~DOC
+        To run a program on the fifth hour of the day
+         ```ruby
+        cron_d 'noop' do
+          hour '5'
+          minute '0'
+          command '/bin/true'
+        end
+        ```
+         To run an entry if a folder exists
+         ```ruby
+        cron_d 'ganglia_tomcat_thread_max' do
+          command "/usr/bin/gmetric
+            -n 'tomcat threads max'
+            -t uint32
+            -v '/usr/local/bin/tomcat-stat
+            --thread-max'"
+          only_if { ::File.exist?('/home/jboss') }
+        end
+        ```
+         To run an entry every Saturday, 8:00 AM
+         ```ruby
+        cron_d 'name_of_cron_entry' do
+          minute '0'
+          hour '8'
+          weekday '6'
+          mailto 'admin@example.com'
+          action :create
+        end
+        ```
+         To run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November
+         ```ruby
+        cron_d 'name_of_cron_entry' do
+          minute '0'
+          hour '20'
+          day '*'
+          month '11'
+          weekday '1-5'
+          action :create
+        end
+        ```
+      DOC
 
       # validate a provided value is between two other provided values
       # we also allow * as a valid input
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 403716cad7..72de77b47e 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -25,6 +25,32 @@ class Chef
 
       description "Use the dmg_package resource to install a dmg 'package'. The resource will retrieve the dmg file from a remote URL, mount it using OS X's hdidutil, copy the application (.app directory) to the specified destination (/Applications), and detach the image using hdiutil. The dmg file will be stored in the Chef::Config[:file_cache_path]."
       introduced "14.0"
+      examples <<~DOC
+        Install Google Chrome via the DMG package
+         ```ruby
+        dmg_package 'Google Chrome' do
+          dmg_name 'googlechrome'
+          source   'https://dl-ssl.google.com/chrome/mac/stable/GGRM/googlechrome.dmg'
+          checksum '7daa2dc5c46d9bfb14f1d7ff4b33884325e5e63e694810adc58f14795165c91a'
+          action   :install
+        end
+        ```
+         Install Virtualbox from the .mpkg
+         ```ruby
+        dmg_package 'Virtualbox' do
+          source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg'
+          type   'mpkg'
+        end
+        ```
+         Install pgAdmin and automatically accept the EULA
+         ```ruby
+        dmg_package 'pgAdmin3' do
+          source   'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg'
+          checksum '9435f79d5b52d0febeddfad392adf82db9df159196f496c1ab139a6957242ce9'
+          accept_eula true
+        end
+        ```
+      DOC
 
       property :app, String,
         description: "The name of the application as it appears in the /Volumes directory if it differs from the resource block's name.",
diff --git a/tasks/docs.rb b/tasks/docs.rb
index db89354517..8fa56e9e09 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -327,7 +327,10 @@ The <%= @name %> resource has the following properties:
 <% if @properties.empty? %>This resource does not have any properties.\n<% end -%>
 <%= boilerplate_content %>
 Examples
-==========================================
+=====================================================
+
+The following examples demonstrate various approaches for using resources in recipes:
+
 <%= @examples -%>
 }