Merge pull request #9775 from chef/more_docs_stuff

Add more examples to resources

21 files changed, 341 insertions, 26 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/bff_package.rb b/lib/chef/resource/bff_package.rb
index 5c18373b32..d0b67d081b 100644
--- a/lib/chef/resource/bff_package.rb
+++ b/lib/chef/resource/bff_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :bff_package
 
-      description "Use the **bff_package** resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **bff_package** resource to manage packages for the AIX platform using the installp utility. When a package is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources."
       introduced "12.0"
 
       property :package_name, String,
diff --git a/lib/chef/resource/cron.rb b/lib/chef/resource/cron.rb
index 6caeaf7d97..73460859fa 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -41,25 +41,25 @@ class Chef
       end
 
       property :minute, [Integer, String],
-        description: "The minute at which the cron entry should run (0 - 59).",
+        description: "The minute at which the cron entry should run (`0 - 59`).",
         default: "*", callbacks: {
           "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
         }
 
       property :hour, [Integer, String],
-        description: "The hour at which the cron entry is to run (0 - 23).",
+        description: "The hour at which the cron entry is to run (`0 - 23`).",
         default: "*", callbacks: {
           "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
         }
 
       property :day, [Integer, String],
-        description: "The day of month at which the cron entry should run (1 - 31).",
+        description: "The day of month at which the cron entry should run (`1 - 31`).",
         default: "*", callbacks: {
           "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
         }
 
       property :month, [Integer, String],
-        description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).",
+        description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
         default: "*", callbacks: {
           "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
         }
@@ -122,10 +122,10 @@ class Chef
       property :time_out, Hash,
         description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
-        preserve-status (BOOL, default: 'false'),
-        foreground (BOOL, default: 'false'),
-        kill-after (in seconds),
-        signal (a name like 'HUP' or a number)",
+        `preserve-status` (BOOL, default: 'false'),
+        `foreground` (BOOL, default: 'false'),
+        `kill-after` (in seconds),
+        `signal` (a name like 'HUP' or a number)",
         default: lazy { {} },
         introduced: "15.7",
         coerce: proc { |h|
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index 2863a88380..d06d479cc9 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -89,31 +89,31 @@ class Chef
         equal_to: %w{ @reboot @yearly @annually @monthly @weekly @daily @midnight @hourly }
 
       property :minute, [Integer, String],
-        description: "The minute at which the cron entry should run (0 - 59).",
+        description: "The minute at which the cron entry should run (`0 - 59`).",
         default: "*", callbacks: {
           "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
         }
 
       property :hour, [Integer, String],
-        description: "The hour at which the cron entry is to run (0 - 23).",
+        description: "The hour at which the cron entry is to run (`0 - 23`).",
         default: "*", callbacks: {
           "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
         }
 
       property :day, [Integer, String],
-        description: "The day of month at which the cron entry should run (1 - 31).",
+        description: "The day of month at which the cron entry should run (`1 - 31`).",
         default: "*", callbacks: {
           "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
         }
 
       property :month, [Integer, String],
-        description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).",
+        description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
         default: "*", callbacks: {
           "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
         }
 
       property :weekday, [Integer, String],
-        description: "The day of the week on which this entry is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7.",
+        description: "The day of the week on which this entry is to run (`0-7`, `mon-sun`, or `*`), where Sunday is both `0` and `7`.",
         default: "*", callbacks: {
           "should be a valid weekday spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_dow(spec) },
         }
@@ -151,10 +151,10 @@ class Chef
       property :time_out, Hash,
         description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
-        preserve-status (BOOL, default: 'false'),
-        foreground (BOOL, default: 'false'),
-        kill-after (in seconds),
-        signal (a name like 'HUP' or a number)",
+        `preserve-status` (BOOL, default: 'false'),
+        `foreground` (BOOL, default: 'false'),
+        `kill-after` (in seconds),
+        `signal` (a name like 'HUP' or a number)",
         default: lazy { {} },
         introduced: "15.7",
         coerce: proc { |h|
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/dpkg_package.rb b/lib/chef/resource/dpkg_package.rb
index ffc15b49c5..466b17d702 100644
--- a/lib/chef/resource/dpkg_package.rb
+++ b/lib/chef/resource/dpkg_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :dpkg_package
 
-      description "Use the **dpkg_package** resource to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the remote_file or cookbook_file resources."
+      description "Use the **dpkg_package** resource to manage packages for the dpkg platform. When a package is installed from a local file, it must be added to the node using the **remote_file** or **cookbook_file** resources."
 
       property :source, [ String, Array, nil ],
         description: "The path to a package in the local file system."
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..1035b23da9 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 %w(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 %w(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..7dba197bb1 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
diff --git a/lib/chef/resource_inspector.rb b/lib/chef/resource_inspector.rb
index 932bbaff4e..bc96ffd4a3 100644
--- a/lib/chef/resource_inspector.rb
+++ b/lib/chef/resource_inspector.rb
@@ -59,7 +59,7 @@ module ResourceInspector
                required: opts[:required] || false,
                default: opts[:default_description] || get_default(opts[:default]),
                name_property: opts[:name_property] || false,
-               equal_to: opts[:equal_to] || [] }
+               equal_to: Array(opts[:equal_to]).sort.map(&:inspect) }
     end
     data
   end
diff --git a/tasks/docs.rb b/tasks/docs.rb
index ea9afc051e..cfa937c58d 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -180,7 +180,7 @@ namespace :docs_site do
         values["required"] = property["required"]
         values["default_value"] = default_val unless default_val.nil?
         values["new_in"] = property["introduced"] unless property["introduced"].nil?
-        # values["allowed_values"] = property["equal_to"].join(', ')
+        values["allowed_values"] = property["equal_to"].join(', ') unless property["equal_to"].empty?
         values["description_list"] = [{ "markdown" => property["description"] }]
         values
       end