Merge pull request #10435 from chef/more_docs

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

14 files changed, 431 insertions, 53 deletions

diff --git a/lib/chef/resource/bff_package.rb b/lib/chef/resource/bff_package.rb
index d0b67d081b..ffe5dfac1b 100644
--- a/lib/chef/resource/bff_package.rb
+++ b/lib/chef/resource/bff_package.rb
@@ -17,6 +17,7 @@
 #
 
 require_relative "package"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -27,6 +28,27 @@ class Chef
 
       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"
+      examples <<~DOC
+      The **bff_package** resource is the default package provider on the AIX platform. The base **package** resource may be used, and then when the platform is AIX, #{ChefUtils::Dist::Infra::PRODUCT} will identify the correct package provider. The following examples show how to install part of the IBM XL C/C++ compiler.
+
+      **Installing using the base package resource**
+
+      ```ruby
+      package 'xlccmp.13.1.0' do
+        source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
+        action :install
+      end
+      ```
+
+      **Installing using the bff_package resource**
+
+      ```ruby
+      bff_package 'xlccmp.13.1.0' do
+        source '/var/tmp/IBM_XL_C_13.1.0/usr/sys/inst.images/xlccmp.13.1.0'
+        action :install
+      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/breakpoint.rb b/lib/chef/resource/breakpoint.rb
index 596cb9f1b8..d73a82a6e8 100644
--- a/lib/chef/resource/breakpoint.rb
+++ b/lib/chef/resource/breakpoint.rb
@@ -28,6 +28,61 @@ class Chef
 
       description "Use the **breakpoint** resource to add breakpoints to recipes. Run the #{ChefUtils::Dist::Infra::SHELL} in #{ChefUtils::Dist::Infra::PRODUCT} mode, and then use those breakpoints to debug recipes. Breakpoints are ignored by the #{ChefUtils::Dist::Infra::CLIENT} during an actual #{ChefUtils::Dist::Infra::CLIENT} run. That said, breakpoints are typically used to debug recipes only when running them in a non-production environment, after which they are removed from those recipes before the parent cookbook is uploaded to the Chef server."
       introduced "12.0"
+      examples <<~DOC
+      **A recipe without a breakpoint**
+
+      ```ruby
+      yum_key node['yum']['elrepo']['key'] do
+        url  node['yum']['elrepo']['key_url']
+        action :add
+      end
+
+      yum_repository 'elrepo' do
+        description 'ELRepo.org Community Enterprise Linux Extras Repository'
+        key node['yum']['elrepo']['key']
+        mirrorlist node['yum']['elrepo']['url']
+        includepkgs node['yum']['elrepo']['includepkgs']
+        exclude node['yum']['elrepo']['exclude']
+        action :create
+      end
+      ```
+
+      **The same recipe with breakpoints**
+
+      ```ruby
+      breakpoint "before yum_key node['yum']['repo_name']['key']" do
+        action :break
+      end
+
+      yum_key node['yum']['repo_name']['key'] do
+        url  node['yum']['repo_name']['key_url']
+        action :add
+      end
+
+      breakpoint "after yum_key node['yum']['repo_name']['key']" do
+        action :break
+      end
+
+      breakpoint "before yum_repository 'repo_name'" do
+        action :break
+      end
+
+      yum_repository 'repo_name' do
+        description 'description'
+        key node['yum']['repo_name']['key']
+        mirrorlist node['yum']['repo_name']['url']
+        includepkgs node['yum']['repo_name']['includepkgs']
+        exclude node['yum']['repo_name']['exclude']
+        action :create
+      end
+
+      breakpoint "after yum_repository 'repo_name'" do
+        action :break
+      end
+      ```
+
+      where the name of each breakpoint is an arbitrary string. In the previous examples, the names are used to indicate if the breakpoint is before or after a resource, and then also to specify which resource.
+      DOC
 
       default_action :break
 
diff --git a/lib/chef/resource/cab_package.rb b/lib/chef/resource/cab_package.rb
index 374eac56a4..904fe81701 100644
--- a/lib/chef/resource/cab_package.rb
+++ b/lib/chef/resource/cab_package.rb
@@ -29,6 +29,35 @@ class Chef
 
       description "Use the **cab_package** resource to install or remove Microsoft Windows cabinet (.cab) packages."
       introduced "12.15"
+      examples <<~'DOC'
+      **Using local path in source**
+
+      ```ruby
+      cab_package 'Install .NET 3.5 sp1 via KB958488' do
+        source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
+        action :install
+      end
+
+      cab_package 'Remove .NET 3.5 sp1 via KB958488' do
+        source 'C:\Users\xyz\AppData\Local\Temp\Windows6.1-KB958488-x64.cab'
+        action :remove
+      end
+      ```
+
+      **Using URL in source**
+
+      ```ruby
+      cab_package 'Install .NET 3.5 sp1 via KB958488' do
+        source 'https://s3.amazonaws.com/my_bucket/Windows6.1-KB958488-x64.cab'
+        action :install
+      end
+
+      cab_package 'Remove .NET 3.5 sp1 via KB958488' do
+        source 'https://s3.amazonaws.com/my_bucket/Temp\Windows6.1-KB958488-x64.cab'
+        action :remove
+      end
+      ```
+      DOC
 
       allowed_actions :install, :remove
 
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 81879cdeda..fc23555cbd 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -63,7 +63,7 @@ class Chef
         end
         ```
 
-        Install MySQL for Chef
+        **Install MySQL gem into #{ChefUtils::Dist::Infra::PRODUCT}***
         ```ruby
         apt_update
 
diff --git a/lib/chef/resource/chef_handler.rb b/lib/chef/resource/chef_handler.rb
index 74f6c50b54..7251050394 100644
--- a/lib/chef/resource/chef_handler.rb
+++ b/lib/chef/resource/chef_handler.rb
@@ -25,8 +25,152 @@ class Chef
 
       provides(:chef_handler) { true }
 
-      description "Use the **chef_handler** resource to install or uninstall reporting/exception handlers."
+      description "Use the **chef_handler** resource to enable handlers during a #{ChefUtils::Dist::Infra::PRODUCT} run. The resource allows arguments to be passed to #{ChefUtils::Dist::Infra::PRODUCT}, which then applies the conditions defined by the custom handler to the node attribute data collected during a #{ChefUtils::Dist::Infra::PRODUCT} run, and then processes the handler based on that data.\nThe **chef_handler** resource is typically defined early in a node's run-list (often being the first item). This ensures that all of the handlers will be available for the entire #{ChefUtils::Dist::Infra::PRODUCT} run."
       introduced "14.0"
+      examples <<~'DOC'
+      **Enable the 'MyHandler' handler**
+
+      The following example shows how to enable a fictional 'MyHandler' handler which is located on disk at `/etc/chef/my_handler.rb`. The handler will be configured to run with Chef Infra Client and will be passed values to the handler's initializer method:
+
+      ```ruby
+      chef_handler 'MyHandler' do
+        source '/etc/chef/my_handler.rb' # the file should already be at this path
+        arguments path: '/var/chef/reports'
+        action :enable
+      end
+      ```
+
+      **Enable handlers during the compile phase**
+
+      ```ruby
+      chef_handler 'Chef::Handler::JsonFile' do
+        source 'chef/handler/json_file'
+        arguments path: '/var/chef/reports'
+        action :enable
+        compile_time true
+      end
+      ```
+
+      **Handle only exceptions**
+
+      ```ruby
+      chef_handler 'Chef::Handler::JsonFile' do
+        source 'chef/handler/json_file'
+        arguments path: '/var/chef/reports'
+        type exception: true
+        action :enable
+      end
+      ```
+
+      **Cookbook Versions (a custom handler)**
+
+      [@juliandunn](https://github.com/juliandunn) created a custom report handler that logs all of the cookbooks and cookbook versions that were used during a Chef Infra Client run, and then reports after the run is complete. This handler requires the chef_handler resource (which is available from the chef_handler cookbook).
+
+      cookbook_versions.rb:
+
+      The following custom handler defines how cookbooks and cookbook versions that are used during a Chef Infra Client run will be compiled into a report using the `Chef::Log` class in Chef Infra Client:
+
+      ```ruby
+      require 'chef/log'
+
+      module Chef
+        class CookbookVersionsHandler < Chef::Handler
+          def report
+            cookbooks = run_context.cookbook_collection
+            Chef::Log.info('Cookbooks and versions run: #{cookbooks.map {|x| x.name.to_s + ' ' + x.version }}')
+          end
+        end
+      end
+      ```
+
+      default.rb:
+
+      The following recipe is added to the run-list for every node on which a list of cookbooks and versions will be generated as report output after every Chef Infra Client run.
+
+      ```ruby
+      cookbook_file '/etc/chef/cookbook_versions.rb' do
+        source 'cookbook_versions.rb'
+        action :create
+      end
+
+      chef_handler 'Chef::CookbookVersionsHandler' do
+        source '/etc/chef/cookbook_versions.rb'
+        type report: true
+        action :enable
+      end
+      ```
+
+      This recipe will generate report output similar to the following:
+
+      [2013-11-26T03:11:06+00:00] INFO: Chef Infra Client Run complete in 0.300029878 seconds
+      [2013-11-26T03:11:06+00:00] INFO: Running report handlers
+      [2013-11-26T03:11:06+00:00] INFO: Cookbooks and versions run: ["cookbook_versions_handler 1.0.0"]
+      [2013-11-26T03:11:06+00:00] INFO: Report handlers complete
+      ```
+
+      **JsonFile Handler**
+
+      The json_file handler is available from the `chef_handler` cookbook and can be used with exceptions and reports. It serializes run status data to a JSON file. This handler may be enabled in one of the following ways.
+
+      By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
+
+      ```ruby
+      require 'chef/handler/json_file'
+      report_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
+      exception_handlers << Chef::Handler::JsonFile.new(path: '/var/chef/reports')
+      ```
+
+      By using the `chef_handler` resource in a recipe, similar to the following:
+
+      ```ruby
+      chef_handler 'Chef::Handler::JsonFile' do
+        source 'chef/handler/json_file'
+        arguments path: '/var/chef/reports'
+        action :enable
+      end
+      ```
+
+      After it has run, the run status data can be loaded and inspected via Interactive Ruby (IRb):
+
+      ```
+      irb(main):002:0> require 'json' => true
+      irb(main):003:0> require 'chef' => true
+      irb(main):004:0> r = JSON.parse(IO.read('/var/chef/reports/chef-run-report-20110322060731.json')) => ... output truncated
+      irb(main):005:0> r.keys => ['end_time', 'node', 'updated_resources', 'exception', 'all_resources', 'success', 'elapsed_time', 'start_time', 'backtrace']
+      irb(main):006:0> r['elapsed_time'] => 0.00246
+      ```
+
+      Register the JsonFile handler
+
+      ```ruby
+      chef_handler 'Chef::Handler::JsonFile' do
+        source 'chef/handler/json_file'
+        arguments path: '/var/chef/reports'
+        action :enable
+      end
+      ```
+
+      **ErrorReport Handler**
+
+      The error_report handler is built into Chef Infra Client and can be used for both exceptions and reports. It serializes error report data to a JSON file. This handler may be enabled in one of the following ways.
+
+      By adding the following lines of Ruby code to either the client.rb file or the solo.rb file, depending on how Chef Infra Client is being run:
+
+      ```ruby
+      require 'chef/handler/error_report'
+      report_handlers << Chef::Handler::ErrorReport.new
+      exception_handlers << Chef::Handler::ErrorReport.new
+      ```
+
+      By using the `chef_handler` resource in a recipe, similar to the following:
+
+      ```ruby
+      chef_handler 'Chef::Handler::ErrorReport' do
+        source 'chef/handler/error_report'
+        action :enable
+      end
+      ```
+      DOC
 
       property :class_name, String,
         description: "The name of the handler class. This can be module name-spaced.",
diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb
index 2c962f0957..88ea02c809 100644
--- a/lib/chef/resource/ohai_hint.rb
+++ b/lib/chef/resource/ohai_hint.rb
@@ -26,6 +26,39 @@ class Chef
 
       description "Use the **ohai_hint** resource to aid in configuration detection by passing hint data to Ohai."
       introduced "14.0"
+      examples <<~DOC
+      **Create a hint file**
+
+      ```ruby
+      ohai_hint 'example' do
+        content a: 'test_content'
+      end
+      ```
+
+      **Create a hint file with a name that does not match the resource name**
+
+      ```ruby
+      ohai_hint 'example' do
+        hint_name 'custom'
+      end
+      ```
+
+      **Create a hint file that is not loaded at compile time**
+
+      ```ruby
+      ohai_hint 'example' do
+        compile_time false
+      end
+      ```
+
+      **Delete a hint file**
+
+      ```ruby
+      ohai_hint 'example' do
+        action :delete
+      end
+      ```
+      DOC
 
       property :hint_name, String,
         description: "An optional property to set the hint name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/openssl_dhparam.rb b/lib/chef/resource/openssl_dhparam.rb
index 087296e9a8..3d20b1b439 100644
--- a/lib/chef/resource/openssl_dhparam.rb
+++ b/lib/chef/resource/openssl_dhparam.rb
@@ -27,15 +27,37 @@ class Chef
 
       provides(:openssl_dhparam) { true }
 
-      description "Use the **openssl_dhparam** resource to generate dhparam.pem files. If a valid dhparam.pem file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid dhparam file, it will be overwritten."
+      description "Use the **openssl_dhparam** resource to generate `dhparam.pem` files. If a valid `dhparam.pem` file is found at the specified location, no new file will be created. If a file is found at the specified location but it is not a valid `dhparam.pem` file, it will be overwritten."
       introduced "14.0"
       examples <<~DOC
-        Create a 1024bit dhparam file
+        **Create a dhparam file**
 
         ```ruby
-        openssl_dhparam '/etc/ssl_files/dhparam.pem' do
-          key_length 1024
-          action :create
+        openssl_dhparam '/etc/httpd/ssl/dhparam.pem'
+        ```
+
+        **Create a dhparam file with a specific key length**
+
+        ```ruby
+        openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do
+          key_length 4096
+        end
+        ```
+
+        **Create a dhparam file with specific user/group ownership**
+
+        ```ruby
+        openssl_dhparam '/etc/httpd/ssl/dhparam.pem' do
+          owner 'www-data'
+          group 'www-data'
+        end
+        ```
+
+        **Manually specify the dhparam file path**
+
+        ```ruby
+        openssl_dhparam 'httpd_dhparam' do
+          path '/etc/httpd/ssl/dhparam.pem'
         end
         ```
       DOC
diff --git a/lib/chef/resource/openssl_ec_private_key.rb b/lib/chef/resource/openssl_ec_private_key.rb
index 26f28b1ad8..7625b5ea6e 100644
--- a/lib/chef/resource/openssl_ec_private_key.rb
+++ b/lib/chef/resource/openssl_ec_private_key.rb
@@ -68,6 +68,7 @@ class Chef
       property :key_cipher, String,
         description: "The designed cipher to use when generating your key. Run `openssl list-cipher-algorithms` to see available options.",
         default: lazy { "des3" },
+        default_description: "des3",
         callbacks: {
           "key_cipher must be a cipher known to openssl. Run `openssl list-cipher-algorithms` to see available options." =>
             proc { |v| OpenSSL::Cipher.ciphers.include?(v) },
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 381e2af696..e9e6ef24ca 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -67,6 +67,7 @@ class Chef
       property :key_cipher, String,
         description: "The designed cipher to use when generating your key. Run `openssl list-cipher-algorithms` to see available options.",
         default: lazy { "des3" },
+        default_description: "des3",
         callbacks: {
           "key_cipher must be a cipher known to openssl. Run `openssl list-cipher-algorithms` to see available options." =>
             proc { |v| OpenSSL::Cipher.ciphers.include?(v) },
diff --git a/lib/chef/resource/openssl_x509_certificate.rb b/lib/chef/resource/openssl_x509_certificate.rb
index de0be22f40..c723f47d61 100644
--- a/lib/chef/resource/openssl_x509_certificate.rb
+++ b/lib/chef/resource/openssl_x509_certificate.rb
@@ -86,32 +86,32 @@ class Chef
         description: "The permission mode applied to all files created by the resource."
 
       property :country, String,
-        description: "Value for the C certificate field."
+        description: "Value for the `C` certificate field."
 
       property :state, String,
-        description: "Value for the ST certificate field."
+        description: "Value for the `ST` certificate field."
 
       property :city, String,
-        description: "Value for the L certificate field."
+        description: "Value for the `L` certificate field."
 
       property :org, String,
-        description: "Value for the O certificate field."
+        description: "Value for the `O` certificate field."
 
       property :org_unit, String,
-        description: "Value for the OU certificate field."
+        description: "Value for the `OU` certificate field."
 
       property :common_name, String,
-        description: "Value for the CN certificate field."
+        description: "Value for the `CN` certificate field."
 
       property :email, String,
-        description: "Value for the email certificate field."
+        description: "Value for the `email` certificate field."
 
       property :extensions, Hash,
-        description: "Hash of X509 Extensions entries, in format { 'keyUsage' => { 'values' => %w( keyEncipherment digitalSignature), 'critical' => true } }.",
+        description: "Hash of X509 Extensions entries, in format `{ 'keyUsage' => { 'values' => %w( keyEncipherment digitalSignature), 'critical' => true } }`.",
         default: lazy { {} }
 
       property :subject_alt_name, Array,
-        description: "Array of Subject Alternative Name entries, in format DNS:example.com or IP:1.2.3.4.",
+        description: "Array of Subject Alternative Name entries, in format `DNS:example.com` or `IP:1.2.3.4`.",
         default: lazy { [] }
 
       property :key_file, String,
@@ -122,7 +122,7 @@ class Chef
 
       property :key_type, String,
         equal_to: %w{rsa ec},
-        description: "The desired type of the generated key (rsa or ec).",
+        description: "The desired type of the generated key.",
         default: "rsa"
 
       property :key_length, Integer,
@@ -131,18 +131,18 @@ class Chef
         default: 2048
 
       property :key_curve, String,
-        description: "The desired curve of the generated key (if key_type is equal to 'ec'). Run openssl ecparam -list_curves to see available options.",
+        description: "The desired curve of the generated key (if key_type is equal to 'ec'). Run `openssl ecparam -list_curves` to see available options.",
         equal_to: %w{secp384r1 secp521r1 prime256v1},
         default: "prime256v1"
 
       property :csr_file, String,
-        description: "The path to a X509 Certificate Request (CSR) on the filesystem. If the csr_file property is specified, the resource will attempt to source a CSR from this location. If no CSR file is found, the resource will generate a Self-Signed Certificate and the certificate fields must be specified (common_name at last)."
+        description: "The path to a X509 Certificate Request (CSR) on the filesystem. If the `csr_file` property is specified, the resource will attempt to source a CSR from this location. If no CSR file is found, the resource will generate a Self-Signed Certificate and the certificate fields must be specified (common_name at last)."
 
       property :ca_cert_file, String,
-        description: "The path to the CA X509 Certificate on the filesystem. If the ca_cert_file property is specified, the ca_key_file property must also be specified, the certificate will be signed with them."
+        description: "The path to the CA X509 Certificate on the filesystem. If the `ca_cert_file` property is specified, the `ca_key_file` property must also be specified, the certificate will be signed with them."
 
       property :ca_key_file, String,
-        description: "The path to the CA private key on the filesystem. If the ca_key_file property is specified, the 'ca_cert_file' property must also be specified, the certificate will be signed with them."
+        description: "The path to the CA private key on the filesystem. If the `ca_key_file` property is specified, the `ca_cert_file` property must also be specified, the certificate will be signed with them."
 
       property :ca_key_pass, String,
         description: "The passphrase for CA private key's passphrase."
diff --git a/lib/chef/resource/openssl_x509_crl.rb b/lib/chef/resource/openssl_x509_crl.rb
index 7bc96fa4da..6e7f905084 100644
--- a/lib/chef/resource/openssl_x509_crl.rb
+++ b/lib/chef/resource/openssl_x509_crl.rb
@@ -31,15 +31,24 @@ class Chef
       description "Use the **openssl_x509_crl** resource to generate PEM-formatted x509 certificate revocation list (CRL) files."
       introduced "14.4"
       examples <<~DOC
-        Generate a CRL file given a cert file and key file
+      **Create a certificate revocation file**
 
-        ```ruby
-        openssl_x509_crl '/etc/ssl_files/my_ca2.crl' do
-          ca_cert_file '/etc/ssl_files/my_ca2.crt'
-          ca_key_file '/etc/ssl_files/my_ca2.key'
-          expire 1
-        end
-        ```
+      ```ruby
+      openssl_x509_crl '/etc/ssl_test/my_ca.crl' do
+        ca_cert_file '/etc/ssl_test/my_ca.crt'
+        ca_key_file '/etc/ssl_test/my_ca.key'
+      end
+      ```
+
+      **Create a certificate revocation file for a particular serial**
+
+      ```ruby
+      openssl_x509_crl '/etc/ssl_test/my_ca.crl' do
+        ca_cert_file '/etc/ssl_test/my_ca.crt'
+        ca_key_file '/etc/ssl_test/my_ca.key'
+        serial_to_revoke C7BCB6602A2E4251EF4E2827A228CB52BC0CEA2F
+      end
+      ```
       DOC
 
       property :path, String,
@@ -62,11 +71,11 @@ class Chef
         default: 1
 
       property :ca_cert_file, String,
-        description: "The path to the CA X509 Certificate on the filesystem. If the ca_cert_file property is specified, the ca_key_file property must also be specified, the CRL will be signed with them.",
+        description: "The path to the CA X509 Certificate on the filesystem. If the `ca_cert_file` property is specified, the `ca_key_file` property must also be specified, the CRL will be signed with them.",
         required: true
 
       property :ca_key_file, String,
-        description: "The path to the CA private key on the filesystem. If the ca_key_file property is specified, the ca_cert_file property must also be specified, the CRL will be signed with them.",
+        description: "The path to the CA private key on the filesystem. If the `ca_key_file` property is specified, the `ca_cert_file` property must also be specified, the CRL will be signed with them.",
         required: true
 
       property :ca_key_pass, String,
diff --git a/lib/chef/resource/openssl_x509_request.rb b/lib/chef/resource/openssl_x509_request.rb
index 8ebf6fe8eb..760c1c970d 100644
--- a/lib/chef/resource/openssl_x509_request.rb
+++ b/lib/chef/resource/openssl_x509_request.rb
@@ -31,7 +31,7 @@ class Chef
       description "Use the **openssl_x509_request** resource to generate PEM-formatted x509 certificates requests. If no existing key is specified, the resource will automatically generate a passwordless key with the certificate."
       introduced "14.4"
       examples <<~DOC
-        Generate new ec key and csr file
+        **Generate new ec key and csr file**
 
         ```ruby
         openssl_x509_request '/etc/ssl_files/my_ec_request.csr' do
@@ -42,7 +42,7 @@ class Chef
         end
         ```
 
-        Generate a new csr file from an existing ec key
+        **Generate a new csr file from an existing ec key**
 
         ```ruby
         openssl_x509_request '/etc/ssl_files/my_ec_request2.csr' do
@@ -54,7 +54,7 @@ class Chef
         end
         ```
 
-        Generate new rsa key and csr file
+        **Generate new rsa key and csr file**
 
         ```ruby
         openssl_x509_request '/etc/ssl_files/my_rsa_request.csr' do
@@ -80,46 +80,44 @@ class Chef
         description: "The permission mode applied to all files created by the resource."
 
       property :country, String,
-        description: "Value for the C certificate field."
+        description: "Value for the `C` certificate field."
 
       property :state, String,
-        description: "Value for the ST certificate field."
+        description: "Value for the `ST` certificate field."
 
       property :city, String,
-        description: "Value for the L certificate field."
+        description: "Value for the `L` certificate field."
 
       property :org, String,
-        description: "Value for the O certificate field."
+        description: "Value for the `O` certificate field."
 
       property :org_unit, String,
-        description: "Value for the OU certificate field."
+        description: "Value for the `OU` certificate field."
 
       property :common_name, String,
         required: true,
-        description: "Value for the CN certificate field."
+        description: "Value for the `CN` certificate field."
 
       property :email, String,
-        description: "Value for the email certificate field."
+        description: "Value for the `email` certificate field."
 
       property :key_file, String,
-        description: "The path to a certificate key file on the filesystem. If the key_file property is specified, the resource will attempt to source a key from this location. If no key file is found, the resource will generate a new key file at this location. If the key_file property is not specified, the resource will generate a key file in the same directory as the generated certificate, with the same name as the generated certificate."
+        description: "The path to a certificate key file on the filesystem. If the `key_file` property is specified, the resource will attempt to source a key from this location. If no key file is found, the resource will generate a new key file at this location. If the `key_file` property is not specified, the resource will generate a key file in the same directory as the generated certificate, with the same name as the generated certificate."
 
       property :key_pass, String,
         description: "The passphrase for an existing key's passphrase."
 
       property :key_type, String,
         equal_to: %w{rsa ec}, default: "ec",
-        description: "The desired type of the generated key (rsa or ec)."
+        description: "The desired type of the generated key."
 
       property :key_length, Integer,
         equal_to: [1024, 2048, 4096, 8192], default: 2048,
-        description: "The desired bit length of the generated key (if key_type is equal to 'rsa')."
+        description: "The desired bit length of the generated key (if key_type is equal to `rsa`)."
 
       property :key_curve, String,
         equal_to: %w{secp384r1 secp521r1 prime256v1}, default: "prime256v1",
-        description: "The desired curve of the generated key (if key_type is equal to 'ec'). Run openssl ecparam -list_curves to see available options."
-
-      default_action :create
+        description: "The desired curve of the generated key (if key_type is equal to `ec`). Run `openssl ecparam -list_curves` to see available options."
 
       action :create do
         description "Generate a certificate request."
diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb
index d1a2791d3c..8939ad506c 100644
--- a/lib/chef/resource/osx_profile.rb
+++ b/lib/chef/resource/osx_profile.rb
@@ -30,8 +30,72 @@ class Chef
       provides :osx_profile
       provides :osx_config_profile
 
-      description "Use the **osx_profile** resource to manage configuration profiles (.mobileconfig files) on the macOS platform. The osx_profile resource installs profiles by using the uuidgen library to generate a unique ProfileUUID, and then using the profiles command to install the profile on the system."
+      description "Use the **osx_profile** resource to manage configuration profiles (`.mobileconfig` files) on the macOS platform. The **osx_profile** resource installs profiles by using the uuidgen library to generate a unique `ProfileUUID`, and then using the `profiles` command to install the profile on the system."
       introduced "12.7"
+      examples <<~DOC
+      **Install a profile from a cookbook file**
+
+      ```ruby
+      osx_profile 'com.company.screensaver.mobileconfig'
+      ```
+
+      **Install profile from a hash**
+
+      ```ruby
+      profile_hash = {
+        'PayloadIdentifier' => 'com.company.screensaver',
+        'PayloadRemovalDisallowed' => false,
+        'PayloadScope' => 'System',
+        'PayloadType' => 'Configuration',
+        'PayloadUUID' => '1781fbec-3325-565f-9022-8aa28135c3cc',
+        'PayloadOrganization' => 'Chef',
+        'PayloadVersion' => 1,
+        'PayloadDisplayName' => 'Screensaver Settings',
+        'PayloadContent'=> [
+          {
+            'PayloadType' => 'com.apple.ManagedClient.preferences',
+            'PayloadVersion' => 1,
+            'PayloadIdentifier' => 'com.company.screensaver',
+            'PayloadUUID' => '73fc30e0-1e57-0131-c32d-000c2944c108',
+            'PayloadEnabled' => true,
+            'PayloadDisplayName' => 'com.apple.screensaver',
+            'PayloadContent' => {
+              'com.apple.screensaver' => {
+                'Forced' => [
+                  {
+                    'mcx_preference_settings' => {
+                      'idleTime' => 0,
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        ]
+      }
+
+      osx_profile 'Install screensaver profile' do
+        profile profile_hash
+      end
+      ```
+
+      **Remove profile using identifier in resource name**
+
+      ```ruby
+      osx_profile 'com.company.screensaver' do
+        action :remove
+      end
+      ```
+
+      **Remove profile by identifier and user friendly resource name**
+
+      ```ruby
+      osx_profile 'Remove screensaver profile' do
+        identifier 'com.company.screensaver'
+        action :remove
+      end
+      ```
+      DOC
 
       property :profile_name, String,
         description: "Use to specify the name of the profile, if different from the name of the resource block.",
@@ -41,7 +105,7 @@ class Chef
         description: "Use to specify a profile. This may be the name of a profile contained in a cookbook or a Hash that contains the contents of the profile."
 
       property :identifier, String,
-        description: "Use to specify the identifier for the profile, such as com.company.screensaver."
+        description: "Use to specify the identifier for the profile, such as `com.company.screensaver`."
 
       # this is not a property it is necessary for the tempfile this resource uses to work (FIXME: this is terrible)
       #
diff --git a/lib/chef/resource/powershell_package_source.rb b/lib/chef/resource/powershell_package_source.rb
index 051b6d4239..a10140f79e 100644
--- a/lib/chef/resource/powershell_package_source.rb
+++ b/lib/chef/resource/powershell_package_source.rb
@@ -43,17 +43,17 @@ class Chef
       property :provider_name, String,
         equal_to: %w{ Programs msi NuGet msu PowerShellGet psl chocolatey },
         validation_message: "The following providers are supported: 'Programs', 'msi', 'NuGet', 'msu', 'PowerShellGet', 'psl' or 'chocolatey'",
-        description: "The package management provider for the source. It supports the following providers: 'Programs', 'msi', 'NuGet', 'msu', 'PowerShellGet', 'psl' and 'chocolatey'.",
+        description: "The package management provider for the source.",
         default: "NuGet"
 
       property :publish_location, String,
-        description: "The url where modules will be published to for this source. Only valid if the provider is 'PowerShellGet'."
+        description: "The url where modules will be published to for this source. Only valid if the provider is `PowerShellGet`."
 
       property :script_source_location, String,
-        description: "The url where scripts are located for this source. Only valid if the provider is 'PowerShellGet'."
+        description: "The url where scripts are located for this source. Only valid if the provider is `PowerShellGet`."
 
       property :script_publish_location, String,
-        description: "The location where scripts will be published to for this source. Only valid if the provider is 'PowerShellGet'."
+        description: "The location where scripts will be published to for this source. Only valid if the provider is `PowerShellGet`."
 
       load_current_value do
         cmd = load_resource_state_script(source_name)