Add more examples to resources

Backfilling the world!

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

15 files changed, 320 insertions, 5 deletions

diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 0fcce64d2d..7b5a56463c 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -20,7 +20,6 @@ require_relative "../resource"
 
 class Chef
   class Resource
-    # @since 13.3
     class AptPreference < Chef::Resource
       unified_mode true
 
@@ -28,6 +27,36 @@ class Chef
 
       description "Use the **apt_preference** resource to create APT [preference files](https://wiki.debian.org/AptPreferences). Preference files are used to control which package versions and sources are prioritized during installation."
       introduced "13.3"
+      examples <<~DOC
+      **Pin libmysqlclient16 to a version 5.1.49-3**:
+
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        pin          'version 5.1.49-3'
+        pin_priority '700'
+      end
+      ```
+
+      Note: The `pin_priority` of `700` ensures that this version will be preferred over any other available versions.
+
+      **Unpin a libmysqlclient16**:
+
+      ```ruby
+      apt_preference 'libmysqlclient16' do
+        action :remove
+      end
+      ```
+
+      **Pin all packages to prefer the packages.dotdeb.org repository**:
+
+      ```ruby
+      apt_preference 'dotdeb' do
+        glob         '*'
+        pin          'origin packages.dotdeb.org'
+        pin_priority '700'
+      end
+      ```
+      DOC
 
       property :package_name, String,
         name_property: true,
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 37382dd621..b1d464b547 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -24,7 +24,7 @@ class Chef
 
       provides(:dmg_package) { true }
 
-      description "Use the **dmg_package** resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using macOS' `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]``."
+      description "Use the **dmg_package** resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using macOS' `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**:
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index e5dd892a9e..35070d6623 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -26,6 +26,15 @@ class Chef
       provides :env # backwards compat with the pre-Chef 14 resource name
 
       description "Use the **windows_env** resource to manage environment keys in Microsoft Windows. After an environment key is set, Microsoft Windows must be restarted before the environment key will be available to the Task Scheduler."
+      examples <<~DOC
+      **Set an environment variable**:
+
+      ```ruby
+      windows_env 'ComSpec' do
+        value 'C:\\Windows\\system32\\cmd.exe'
+      end
+      ```
+      DOC
 
       default_action :create
       allowed_actions :create, :delete, :modify
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index e243eb365e..79d305c634 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -25,6 +25,61 @@ class Chef
 
       description "Use the **windows_feature** resource to add, remove or entirely delete Windows features and roles. This resource calls the 'windows_feature_dism' or 'windows_feature_powershell' resources depending on the specified installation method, and defaults to DISM, which is available on both Workstation and Server editions of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Install the DHCP Server feature**:
+
+      ```ruby
+      windows_feature 'DHCPServer' do
+        action :install
+      end
+      ```
+
+      **Install the .Net 3.5.1 feature using repository files on DVD**:
+
+      ```ruby
+      windows_feature "NetFx3" do
+        action :install
+        source "d:\sources\sxs"
+      end
+      ```
+
+      **Remove Telnet Server and Client features**:
+
+      ```ruby
+      windows_feature ['TelnetServer', 'TelnetClient'] do
+        action :remove
+      end
+      ```
+
+      **Add the SMTP Server feature using the PowerShell provider**:
+
+      ```ruby
+      windows_feature "smtp-server" do
+        action :install
+        all true
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install multiple features using one resource with the PowerShell provider**:
+
+      ```ruby
+      windows_feature ['Web-Asp-Net45', 'Web-Net-Ext45'] do
+        action :install
+        install_method :windows_feature_powershell
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature, including the management tools**:
+
+      ```ruby
+      windows_feature 'NPAS' do
+        action :install
+        management_tools true
+        install_method :windows_feature_powershell
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name. The same feature may have different names depending on the underlying installation method being used (ie DHCPServer vs DHCP; DNS-Server-Full-Role vs DNS).",
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 7b0206f96b..cd53a76434 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -26,6 +26,19 @@ class Chef
 
       description "Use the **windows_feature_dism** resource to add, remove, or entirely delete Windows features and roles using DISM."
       introduced "14.0"
+      examples <<~DOC
+      **Installing the TelnetClient service**:
+
+      ```ruby
+      windows_feature_dism "TelnetClient"
+      ```
+
+      **Installing two features by using an array**:
+
+      ```ruby
+      windows_feature_dism %w(TelnetClient TFTP)
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource name.",
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index ac33dfa0a3..b8a7956358 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -27,6 +27,33 @@ class Chef
 
       description "Use the **windows_feature_powershell** resource to add, remove, or entirely delete Windows features and roles using PowerShell. This resource offers significant speed benefits over the windows_feature_dism resource, but requires installation of the Remote Server Administration Tools on non-server releases of Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Add the SMTP Server feature**:
+
+      ```ruby
+      windows_feature_powershell "smtp-server" do
+        action :install
+        all true
+      end
+      ```
+
+      **Install multiple features using one resource**:
+
+      ```ruby
+      windows_feature_powershell ['Web-Asp-Net45', 'Web-Net-Ext45'] do
+        action :install
+      end
+      ```
+
+      **Install the Network Policy and Access Service feature**:
+
+      ```ruby
+      windows_feature_powershell 'NPAS' do
+        action :install
+        management_tools true
+      end
+      ```
+      DOC
 
       property :feature_name, [Array, String],
         description: "The name of the feature(s) or role(s) to install if they differ from the resource block's name.",
diff --git a/lib/chef/resource/windows_font.rb b/lib/chef/resource/windows_font.rb
index dfb73f8a75..007fe5db58 100644
--- a/lib/chef/resource/windows_font.rb
+++ b/lib/chef/resource/windows_font.rb
@@ -26,6 +26,15 @@ class Chef
 
       description "Use the **windows_font** resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
       introduced "14.0"
+      examples <<~DOC
+      **Install a font from a https source**:
+
+      ```ruby
+      windows_font 'Custom.otf' do
+        source "https://example.com/Custom.otf"
+      end
+      ```
+      DOC
 
       property :font_name, String,
         description: "An optional property to set the name of the font to install if it differs from the resource block's name.",
diff --git a/lib/chef/resource/windows_package.rb b/lib/chef/resource/windows_package.rb
index 27379da1a3..10205e847b 100644
--- a/lib/chef/resource/windows_package.rb
+++ b/lib/chef/resource/windows_package.rb
@@ -32,6 +32,66 @@ class Chef
 
       description "Use the **windows_package** resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
       introduced "11.12"
+      examples <<~DOC
+      **Install a package**:
+
+      ```ruby
+      windows_package '7zip' do
+        action :install
+        source 'C:\\7z920.msi'
+      end
+      ```
+
+      **Specify a URL for the source attribute**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+      end
+      ```
+
+      **Specify path and checksum**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        checksum '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+      end
+      ```
+
+      **Modify remote_file resource attributes**:
+
+      The windows_package resource may specify a package at a remote location using the remote_file_attributes property. This uses the remote_file resource to download the contents at the specified URL and passes in a Hash that modifies the properties of the remote_file resource.
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        remote_file_attributes ({
+          :path => 'C:\\7zip.msi',
+          :checksum => '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+        })
+      end
+      ```
+
+      **Download a nsis (Nullsoft) package resource**:
+
+      ```ruby
+      windows_package 'Mercurial 3.6.1 (64-bit)' do
+        source 'http://mercurial.selenic.com/release/windows/Mercurial-3.6.1-x64.exe'
+        checksum 'febd29578cb6736163d232708b834a2ddd119aa40abc536b2c313fc5e1b5831d'
+      end
+      ```
+
+      **Download a custom package**:
+
+      ```ruby
+      windows_package 'Microsoft Visual C++ 2005 Redistributable' do
+        source 'https://download.microsoft.com/download/6/B/B/6BB661D6-A8AE-4819-B79F-236472F6070C/vcredist_x86.exe'
+        installer_type :custom
+        options '/Q'
+      end
+      ```
+      DOC
 
       allowed_actions :install, :remove
 
@@ -75,7 +135,7 @@ class Chef
           end
         end),
         default_description: "The resource block's name", # this property is basically a name_property but not really so we need to spell it out
-        description: "The path to a package in the local file system. The location of the package may be at a URL. \n"
+        description: "The path to a package in the local file system. The location of the package may be at a URL."
 
       property :checksum, String,
         desired_state: false, coerce: (proc { |c| c.downcase }),
diff --git a/lib/chef/resource/windows_pagefile.rb b/lib/chef/resource/windows_pagefile.rb
index d49e85eec8..d459b01033 100644
--- a/lib/chef/resource/windows_pagefile.rb
+++ b/lib/chef/resource/windows_pagefile.rb
@@ -24,6 +24,34 @@ class Chef
 
       description "Use the **windows_pagefile** resource to configure pagefile settings on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Set the system to manage pagefiles**:
+
+      ```ruby
+      windows_pagefile 'Enable automatic management of pagefiles' do
+        automatic_managed true
+      end
+      ```
+
+      **Delete a pagefile**:
+
+      ```ruby
+      windows_pagefile 'Delete the pagefile' do
+        path 'C:\pagefile.sys'
+        action :delete
+      end
+      ```
+
+      **Create a pagefile with an initial and maximum size**:
+
+      ```ruby
+      windows_pagefile 'create the pagefile' do
+        path 'C:\pagefile.sys'
+        initial_size 100
+        maximum_size 200
+      end
+      ```
+      DOC
 
       property :path, String,
         coerce: proc { |x| x.tr("/", '\\') },
diff --git a/lib/chef/resource/windows_path.rb b/lib/chef/resource/windows_path.rb
index 70364eadff..850be66ba0 100644
--- a/lib/chef/resource/windows_path.rb
+++ b/lib/chef/resource/windows_path.rb
@@ -25,6 +25,23 @@ class Chef
 
       description "Use the **windows_path** resource to manage the path environment variable on Microsoft Windows."
       introduced "13.4"
+      examples <<~DOC
+      **Add Sysinternals to the system path**:
+
+      ```ruby
+      windows_path 'C:\\Sysinternals' do
+        action :add
+      end
+      ```
+
+      **Remove 7-Zip from the system path**:
+
+      ```ruby
+      windows_path 'C:\\7-Zip' do
+        action :remove
+      end
+      ```
+      DOC
 
       allowed_actions :add, :remove
       default_action :add
diff --git a/lib/chef/resource/windows_printer.rb b/lib/chef/resource/windows_printer.rb
index 868598374d..3608cae5be 100644
--- a/lib/chef/resource/windows_printer.rb
+++ b/lib/chef/resource/windows_printer.rb
@@ -28,6 +28,26 @@ class Chef
 
       description "Use the **windows_printer** resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system."
       introduced "14.0"
+      examples <<~DOC
+      **Create a printer**:
+
+      ```ruby
+      windows_printer 'HP LaserJet 5th Floor' do
+        driver_name 'HP LaserJet 4100 Series PCL6'
+        ipv4_address '10.4.64.38'
+      end
+      ```
+
+      **Delete a printer**:
+
+      Note: this doesn’t delete the associated printer port. See windows_printer_port above for how to delete the port.
+
+      ```ruby
+      windows_printer 'HP LaserJet 5th Floor' do
+        action :delete
+      end
+      ```
+      DOC
 
       property :device_id, String,
         description: "An optional property to set the printer queue name if it differs from the resource block's name. Example: `HP LJ 5200 in fifth floor copy room`.",
diff --git a/lib/chef/resource/windows_printer_port.rb b/lib/chef/resource/windows_printer_port.rb
index faa4d6a708..57b78bb5b6 100644
--- a/lib/chef/resource/windows_printer_port.rb
+++ b/lib/chef/resource/windows_printer_port.rb
@@ -28,6 +28,34 @@ class Chef
 
       description "Use the **windows_printer_port** resource to create and delete TCP/IPv4 printer ports on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Delete a printer port**
+
+      ```ruby
+      windows_printer_port '10.4.64.37' do
+        action :delete
+      end
+      ```
+
+      **Delete a port with a custom port_name**
+
+      ```ruby
+      windows_printer_port '10.4.64.38' do
+        port_name 'My awesome port'
+        action :delete
+      end
+      ```
+
+      **Create a port with more options**
+
+      ```ruby
+      windows_printer_port '10.4.64.39' do
+        port_name 'My awesome port'
+        snmp_enabled true
+        port_protocol 2
+      end
+      ```
+      DOC
 
       property :ipv4_address, String,
         name_property: true,
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index 2a38082539..bd53744f0a 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -24,7 +24,7 @@ class Chef
     class WindowsTask < Chef::Resource
       provides(:windows_task) { true }
 
-      description "Use the **windows_task** resource to create, delete or run a Windows scheduled task. Requires Windows Server 2008 or later due to API usage."
+      description "Use the **windows_task** resource to create, delete or run a Windows scheduled task."
       introduced "13.0"
       examples <<~DOC
       **Create a scheduled task to run every 15 minutes as the Administrator user**:
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 3552e3e558..4e23244dfe 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -27,6 +27,26 @@ class Chef
 
       description "Use the **yum_repository** resource to manage a Yum repository configuration file located at `/etc/yum.repos.d/repositoryid.repo` on the local machine. This configuration file specifies which repositories to reference, how to handle cached data, etc."
       introduced "12.14"
+      examples <<~DOC
+      **Add an internal company repository**:
+
+      ```ruby
+      yum_repository 'OurCo' do
+        description 'OurCo yum repository'
+        mirrorlist 'http://artifacts.ourco.org/mirrorlist?repo=ourco-8&arch=$basearch'
+        gpgkey 'http://artifacts.ourco.org/pub/yum/RPM-GPG-KEY-OURCO-8'
+        action :create
+      end
+      ```ruby
+
+      **Delete a repository**:
+
+      ```ruby
+      yum_repository 'CentOS-Media' do
+        action :delete
+      end
+      ```
+      DOC
 
       # http://linux.die.net/man/5/yum.conf as well as
       # http://dnf.readthedocs.io/en/latest/conf_ref.html
diff --git a/lib/chef/resource/zypper_repository.rb b/lib/chef/resource/zypper_repository.rb
index 52240f5c49..05856cc9bc 100644
--- a/lib/chef/resource/zypper_repository.rb
+++ b/lib/chef/resource/zypper_repository.rb
@@ -29,7 +29,7 @@ class Chef
       description "Use the **zypper_repository** resource to create Zypper package repositories on SUSE Enterprise Linux and openSUSE systems. This resource maintains full compatibility with the **zypper_repository** resource in the existing **zypper** cookbook."
       introduced "13.3"
       examples <<~DOC
-        **Add the Apache repo on openSUSE Leap 15**
+        **Add the Apache repo on openSUSE Leap 15**:
 
         ``` ruby
         zypper_repository 'apache' do