Merge pull request #9926 from chef/docs

Improve auto-generated docs

8 files changed, 74 insertions, 12 deletions

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 8612ac45f3..29cfb55036 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1372,6 +1372,7 @@ Chef Infra Client's Data Collection subsystem is used to report node changes dur
 A new `copy_properties_from` method for custom resources allows you copy properties from your custom resource into other resources you are calling, so you can avoid unnecessarily repeating code.
 
 To inherit all the properties of another resource:
+
 ```ruby
 resource_name :my_resource
 
@@ -1386,6 +1387,7 @@ end
 ```
 
 To selectively inherit certain properties from a resource:
+
 ```ruby
 resource_name :my_resource
 
diff --git a/docs/dev/design_documents/resource_load_and_converge_methods.md b/docs/dev/design_documents/resource_load_and_converge_methods.md
index b7046d1892..00b074578b 100644
--- a/docs/dev/design_documents/resource_load_and_converge_methods.md
+++ b/docs/dev/design_documents/resource_load_and_converge_methods.md
@@ -30,7 +30,6 @@ When the resource writer defines `load_current_value` on the resource class, it
 2. Copy all non-desired-state values from the desired resource into the new instance.
 3. Call `load_current_value` on the new instance.
 
-
 ```ruby
 class File < Chef::Resource
   property :path, name_attribute: true
diff --git a/docs/dev/how_to/bumping_the_major_version.md b/docs/dev/how_to/bumping_the_major_version.md
index 17332bf765..ff93f5bcf6 100644
--- a/docs/dev/how_to/bumping_the_major_version.md
+++ b/docs/dev/how_to/bumping_the_major_version.md
@@ -8,7 +8,7 @@ Chef consumes Ohai from GitHub as both a runtime dependency and a testing depend
 
 ### Create a new stable branch of Ohai
 
-On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b 15-stable`. You’ll then want to edit the Expeditor config.yml file to update the branch configs like this:
+On your local machine fork the current master branch to a new stable branch. For example: `git checkout -b 15-stable`. You'll then want to edit the Expeditor config.yml file to update the branch configs like this:
 
 https://github.com/chef/ohai/commit/ad208165619425dd7886b2de3f168b49ded25146
 
@@ -29,9 +29,9 @@ On your local machine fork the current master branch to a new stable branch. For
 
 ### Create a branch to fixup your new stable branch for release
 
-Once you’ve forked to a new stable branch such as `chef-15` you’ll want to create a new branch so you can build a PR, which will get this branch ready for release:
+Once you've forked to a new stable branch such as `chef-15` you'll want to create a new branch so you can build a PR, which will get this branch ready for release:
 
-- In ./expeditor/config.yml add the version_constraint for the new branch, update the version_constraint for master to match the new major version, and remove all the update_dep.sh subscriptions which don’t work against stable branches.
+- In ./expeditor/config.yml add the version_constraint for the new branch, update the version_constraint for master to match the new major version, and remove all the update_dep.sh subscriptions which don't work against stable branches.
 - In readme.md update the buildkite badge to point to the new stable branch image and link instead of pointing to master.
 - In kitchen-tests/Gemfile update the Ohai branch to point to the new Ohai stable
 - In kitchen-tests/kitchen.yml update chef_version to be your new stable version and not current. Ex: 15
diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb
index 71a9ffde38..c3b34395f6 100644
--- a/lib/chef/resource/homebrew_package.rb
+++ b/lib/chef/resource/homebrew_package.rb
@@ -29,8 +29,37 @@ class Chef
       provides :homebrew_package
       provides :package, os: "darwin"
 
-      description "Use the **homebrew_package** resource to manage packages for the macOS platform."
+      description "Use the **homebrew_package** resource to manage packages for the macOS platform. Note: Starting with #{Chef::Dist::PRODUCT} 16 the homebrew resource now accepts an array of packages for isntalling multiple packages at once."
       introduced "12.0"
+      examples <<~DOC
+      **Install a package**:
+
+      ```ruby
+      homebrew_package 'git'
+      ```
+
+      **Install multiple packages at once**:
+
+      ```ruby
+      homebrew_package %w(git fish ruby)
+      ```
+
+      **Specify the Homebrew user with a UUID**
+
+      ```ruby
+      homebrew_package 'git' do
+        homebrew_user 1001
+      end
+      ```
+
+      **Specify the Homebrew user with a string**:
+
+      ```ruby
+      homebrew_package 'vim' do
+        homebrew_user 'user1'
+      end
+      ```
+      DOC
 
       property :homebrew_user, [ String, Integer ],
         description: "The name or uid of the Homebrew owner to be used by #{Chef::Dist::PRODUCT} when executing a command."
diff --git a/lib/chef/resource/kernel_module.rb b/lib/chef/resource/kernel_module.rb
index c3b3dba9d5..87a1d79d24 100644
--- a/lib/chef/resource/kernel_module.rb
+++ b/lib/chef/resource/kernel_module.rb
@@ -19,11 +19,14 @@ class Chef
       introduced "14.3"
       examples <<~DOC
         Install and load a kernel module, and ensure it loads on reboot.
+
         ```ruby
         kernel_module 'loop'
         ```
+
         Install and load a kernel with a specific set of options, and ensure it loads on reboot. Consult kernel module
         documentation for specific options that are supported.
+
         ```ruby
         kernel_module 'loop' do
           options [
@@ -32,31 +35,41 @@ class Chef
           ]
         end
         ```
+
         Load a kernel module.
+
         ```ruby
         kernel_module 'loop' do
           action :load
         end
         ```
-        Unload a kernel module and remove module config, so it doesn’t load on reboot.
+
+        Unload a kernel module and remove module config, so it doesn't load on reboot.
+
         ```ruby
         kernel_module 'loop' do
           action :uninstall
         end
         ```
+
         Unload kernel module.
+
         ```ruby
         kernel_module 'loop' do
           action :unload
         end
         ```
+
         Blacklist a module from loading.
+
         ```ruby
         kernel_module 'loop' do
           action :blacklist
         end
         ```
+
         Disable a kernel module.
+
         ```ruby
         kernel_module 'loop' do
           action :disable
diff --git a/lib/chef/resource/plist.rb b/lib/chef/resource/plist.rb
index 944eea18e9..06811ea8b6 100644
--- a/lib/chef/resource/plist.rb
+++ b/lib/chef/resource/plist.rb
@@ -28,14 +28,33 @@ class Chef
 
       description "Use the **plist** resource to set config values in plist files on macOS systems."
       introduced "16.0"
+      examples <<~DOC
+        **Show hidden files in finder**:
+
+        ```ruby
+        plist 'show hidden files' do
+          path '/Users/vagrant/Library/Preferences/com.apple.finder.plist'
+          entry 'AppleShowAllFiles'
+          value true
+        end
+        ```
+      DOC
+
+      property :path, String, name_property: true,
+        description: "The path on disk to the plist file."
 
-      property :path, String, name_property: true
       property :entry, String
       property :value, [TrueClass, FalseClass, String, Integer, Float, Hash]
       property :encoding, String, default: "binary"
-      property :owner, String, default: "root"
-      property :group, String, default: "wheel"
-      property :mode, [String, Integer]
+
+      property :owner, String, default: "root",
+        description: "The owner of the plist file."
+
+      property :group, String, default: "wheel",
+        description: "The group of the plist file."
+
+      property :mode, [String, Integer],
+        description: "The file mode of the plist file. Ex: '644'"
 
       PLISTBUDDY_EXECUTABLE = "/usr/libexec/PlistBuddy".freeze
       DEFAULTS_EXECUTABLE = "/usr/bin/defaults".freeze
diff --git a/lib/chef/resource/template.rb b/lib/chef/resource/template.rb
index 1ac99b3d13..0ffa2194d8 100644
--- a/lib/chef/resource/template.rb
+++ b/lib/chef/resource/template.rb
@@ -69,7 +69,7 @@ class Chef
 
       property :local, [ TrueClass, FalseClass ],
         default: false, desired_state: false,
-        description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook’s /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node."
+        description: "Load a template from a local path. By default, the #{Chef::Dist::CLIENT} loads templates from a cookbook's /templates directory. When this property is set to true, use the source property to specify the path to a template on the local node."
 
       # Declares a helper method to be defined in the template context when
       # rendering.
diff --git a/tasks/docs.rb b/tasks/docs.rb
index ef77cd03a9..c53b4aa58e 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -184,7 +184,7 @@ namespace :docs_site do
       properties = {}
 
       # these package properties support passing arrays for the package name
-      properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package}.include?(name)
+      properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package homebrew_package}.include?(name)
 
       properties["common_resource_functionality_resources_common_windows_security"] = true if name == "remote_directory"