Further improve docs generation

Fix some markdown generration in the rake task and general cleanup of content in the resources.

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

6 files changed, 57 insertions, 10 deletions

diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index 59d9773ed3..0fc4acd65f 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -97,7 +97,7 @@ class Chef
         desired_state: false
 
       property :sudo, [TrueClass, FalseClass],
-        description: "Set to true if the setting you wish to modify requires privileged access. This requires passwordless sudo for the '/usr/bin/defaults' command to be setup for the user running #{ChefUtils::Dist::Infra::PRODUCT}.",
+        description: "Set to true if the setting you wish to modify requires privileged access. This requires passwordless sudo for the `/usr/bin/defaults` command to be setup for the user running #{ChefUtils::Dist::Infra::PRODUCT}.",
         default: false,
         desired_state: false
 
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index b66b8bbfc4..4c595409e2 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -31,6 +31,52 @@ class Chef
                   " reboot. If the config file is required, it must be done by specifying a template with the correct array layout,"\
                   " and then by using the mount provider to create a file systems table (fstab) entry."
 
+      examples <<~DOC
+      **Create and assemble a RAID 0 array**
+
+      The mdadm command can be used to create RAID arrays. For example, a RAID 0 array named /dev/md0 with 10 devices would have a command similar to the following:
+
+      ```
+      mdadm --create /dev/md0 --level=0 --raid-devices=10 /dev/s01.../dev/s10
+      ```
+
+      where /dev/s01 .. /dev/s10 represents 10 devices (01, 02, 03, and so on). This same command, when expressed as a recipe using the mdadm resource, would be similar to:
+
+      ```ruby
+      mdadm '/dev/md0' do
+        devices [ '/dev/s01', ... '/dev/s10' ]
+        level 0
+        action :create
+      end
+      ```
+
+      (again, where /dev/s01 .. /dev/s10 represents devices /dev/s01, /dev/s02, /dev/s03, and so on).
+
+      **Create and assemble a RAID 1 array**
+
+      ```ruby
+      mdadm '/dev/md0' do
+        devices [ '/dev/sda', '/dev/sdb' ]
+        level 1
+        action [ :create, :assemble ]
+      end
+      ```
+
+      **Create and assemble a RAID 5 array**
+
+      The mdadm command can be used to create RAID arrays. For example, a RAID 5 array named /dev/sd0 with 4, and a superblock type of 0.90 would be similar to:
+
+      ```ruby
+      mdadm '/dev/sd0' do
+        devices [ '/dev/s1', '/dev/s2', '/dev/s3', '/dev/s4' ]
+        level 5
+        metadata '0.90'
+        chunk 32
+        action :create
+      end
+      ```
+      DOC
+
       default_action :create
       allowed_actions :create, :assemble, :stop
 
@@ -78,7 +124,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Create an array with per-device superblocks. If an array already exists (but does not match), update that array to match." do
         unless current_resource.exists
           converge_by("create RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --create #{new_resource.raid_device} --level #{new_resource.level}"
@@ -96,7 +142,7 @@ class Chef
         end
       end
 
-      action :assemble do
+      action :assemble, description: "Assemble a previously created array into an active array." do
         unless current_resource.exists
           converge_by("assemble RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --assemble #{new_resource.raid_device} #{new_resource.devices.join(" ")}"
@@ -109,7 +155,7 @@ class Chef
         end
       end
 
-      action :stop do
+      action :stop, description: "Stop an active array." do
         if current_resource.exists
           converge_by("stop RAID device #{new_resource.raid_device}") do
             command = "yes | mdadm --stop #{new_resource.raid_device}"
diff --git a/lib/chef/resource/mount.rb b/lib/chef/resource/mount.rb
index c23ba9bbee..e46abead13 100644
--- a/lib/chef/resource/mount.rb
+++ b/lib/chef/resource/mount.rb
@@ -34,6 +34,7 @@ class Chef
       property :supports, [Array, Hash],
         description: "Specify a Hash of supported mount features.",
         default: lazy { { remount: false } },
+        default_description: "{ remount: false }",
         coerce: proc { |x| x.is_a?(Array) ? x.each_with_object({}) { |i, m| m[i] = true } : x }
 
       property :password, String,
@@ -45,7 +46,7 @@ class Chef
                description: "The directory (or path) in which the device is to be mounted. Defaults to the name of the resource block if not provided."
 
       property :device, String, identity: true,
-               description: "Required for :umount and :remount actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted."
+               description: "Required for `:umount` and `:remount` actions (for the purpose of checking the mount command output for presence). The special block device or remote node, a label, or a uuid to be mounted."
 
       property :device_type, [String, Symbol],
         description: "The type of device: :device, :label, or :uuid",
diff --git a/lib/chef/resource/openssl_ec_private_key.rb b/lib/chef/resource/openssl_ec_private_key.rb
index 7625b5ea6e..844ee5a4c9 100644
--- a/lib/chef/resource/openssl_ec_private_key.rb
+++ b/lib/chef/resource/openssl_ec_private_key.rb
@@ -31,7 +31,7 @@ class Chef
       description "Use the **openssl_ec_private_key** resource to generate an elliptic curve (EC) private key file. If a valid EC key file can be opened at the specified location, no new file will be created. If the EC key file cannot be opened, either because it does not exist or because the password to the EC key file does not match the password in the recipe, then it will be overwritten."
       introduced "14.4"
       examples <<~DOC
-        Generate a new ec privatekey with prime256v1 key curve and default des3 cipher
+        **Generate a new ec privatekey with prime256v1 key curve and default des3 cipher**
 
         ```ruby
         openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
@@ -41,7 +41,7 @@ class Chef
         end
         ```
 
-        Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher
+        **Generate a new ec private key with prime256v1 key curve and aes-128-cbc cipher**
 
         ```ruby
         openssl_ec_private_key '/etc/ssl_files/eckey_prime256v1_des3.pem' do
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index e9e6ef24ca..ff41b6f797 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -43,7 +43,7 @@ class Chef
         Generate new 1024bit key with the aes-128-cbc cipher
 
         ```ruby
-        openssl_rsa_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
+        openssl_rsa_private_key '/etc/ssl_files/rsakey_aes128cbc.pem' do
           key_length 1024
           key_cipher 'aes-128-cbc'
           action :create
diff --git a/tasks/docs.rb b/tasks/docs.rb
index cba58cad4a..78e9c13b2c 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -236,9 +236,9 @@ namespace :docs_site do
 
         case preface
         when "Note:"
-          description << { "note" => element }
+          description << { "note" => [element] }
         when "Warning:"
-          description << { "warning" => element }
+          description << { "warning" => [element] }
         when nil
           description << element
         else