Merge pull request #6696 from chef/yard

Add descriptions and yard @since comments to all resources

69 files changed, 227 insertions, 3 deletions

diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 8397f84c71..c077922a20 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -21,6 +21,7 @@ require "chef/provider/package/apt"
 
 class Chef
   class Resource
+    # Use the apt_package resource to manage packages on Debian and Ubuntu platforms.
     class AptPackage < Chef::Resource::Package
       resource_name :apt_package
       provides :package, os: "linux", platform_family: "debian"
diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 603766d76b..87c5a5a016 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # The apt_preference resource allows for the creation of APT preference files. Preference files are used to control
+    # which package versions and sources are prioritized during installation.
+    #
+    # @since 13.3
     class AptPreference < Chef::Resource
       resource_name :apt_preference
       provides :apt_preference
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 8b69435246..5da0b4e37b 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update
+    # APT package cache immediately.
+    #
+    # @since 12.9
     class AptRepository < Chef::Resource
       resource_name :apt_repository
       provides :apt_repository
diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index 67ca7fbfea..0349614ad2 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -20,6 +20,9 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the apt_update resource to manage APT repository updates on Debian and Ubuntu platforms.
+    #
+    # @since 12.7
     class AptUpdate < Chef::Resource
       resource_name :apt_update
       provides :apt_update
diff --git a/lib/chef/resource/bash.rb b/lib/chef/resource/bash.rb
index 1238eedc42..ebc4a7790b 100644
--- a/lib/chef/resource/bash.rb
+++ b/lib/chef/resource/bash.rb
@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the bash resource to execute scripts using the Bash interpreter. This resource may also use any of the actions
+    # and properties that are available to the execute resource. Commands that are executed with this resource are (by
+    # their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if
+    # and only_if to guard this resource for idempotence.
     class Bash < Chef::Resource::Script
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/batch.rb b/lib/chef/resource/batch.rb
index 10e96839fb..b3c7b17cef 100644
--- a/lib/chef/resource/batch.rb
+++ b/lib/chef/resource/batch.rb
@@ -20,6 +20,11 @@ require "chef/resource/windows_script"
 
 class Chef
   class Resource
+    # Use the batch resource to execute a batch script using the cmd.exe interpreter on Windows. The batch resource
+    # creates and executes a temporary file (similar to how the script resource behaves), rather than running the
+    # command inline. Commands that are executed with this resource are (by their nature) not idempotent, as they are
+    # typically unique to the environment in which they are run. Use not_if and only_if to guard this resource for
+    # idempotence.
     class Batch < Chef::Resource::WindowsScript
 
       provides :batch, os: "windows"
diff --git a/lib/chef/resource/bff_package.rb b/lib/chef/resource/bff_package.rb
index b14591876a..d91777cb74 100644
--- a/lib/chef/resource/bff_package.rb
+++ b/lib/chef/resource/bff_package.rb
@@ -21,6 +21,10 @@ require "chef/provider/package/aix"
 
 class Chef
   class Resource
+    # 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.
+    #
+    # @since 12.0
     class BffPackage < Chef::Resource::Package
     end
   end
diff --git a/lib/chef/resource/breakpoint.rb b/lib/chef/resource/breakpoint.rb
index 81cfd89e5e..5d2c5555be 100644
--- a/lib/chef/resource/breakpoint.rb
+++ b/lib/chef/resource/breakpoint.rb
@@ -20,6 +20,12 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the breakpoint resource to add breakpoints to recipes. Run the chef-shell in chef-client mode, and then use
+    # those breakpoints to debug recipes. Breakpoints are ignored by the chef-client during an actual chef-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.
+    #
+    # @since 12.0
     class Breakpoint < Chef::Resource
       provides :breakpoint
       resource_name :breakpoint
diff --git a/lib/chef/resource/cab_package.rb b/lib/chef/resource/cab_package.rb
index fcf3f02b86..8f3b3038c4 100644
--- a/lib/chef/resource/cab_package.rb
+++ b/lib/chef/resource/cab_package.rb
@@ -21,6 +21,9 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages.
+    #
+    # @since 12.15
     class CabPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 3a2d90e852..b6bbd0e209 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -21,6 +21,18 @@ require "chef/resource/gem_package"
 
 class Chef
   class Resource
+    # Use the chef_gem resource to install a gem only for the instance of Ruby that is dedicated to the chef-client.
+    # When a gem is installed from a local file, it must be added to the node using the remote_file or cookbook_file
+    # resources.
+    #
+    # The chef_gem resource works with all of the same properties and options as the gem_package resource, but does not
+    # accept the gem_binary property because it always uses the CurrentGemEnvironment under which the chef-client is
+    # running. In addition to performing actions similar to the gem_package resource, the chef_gem resource does the
+    # following:
+    #  - Runs its actions immediately, before convergence, allowing a gem to be used in a recipe immediately after it is
+    #    installed
+    #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
+    #    immediately after it is installed
     class ChefGem < Chef::Resource::Package::GemPackage
       resource_name :chef_gem
 
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 77bdcb197a..58bcab8b39 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -20,6 +20,9 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform.
+    #
+    # @since 12.7
     class ChocolateyPackage < Chef::Resource::Package
 
       resource_name :chocolatey_package
@@ -31,7 +34,6 @@ class Chef
       property :options, String
 
       property :package_name, [String, Array], coerce: proc { |x| [x].flatten }
-
       property :version, [String, Array], coerce: proc { |x| [x].flatten }
       property :returns, [Integer, Array], default: [ 0 ], desired_state: false
     end
diff --git a/lib/chef/resource/cookbook_file.rb b/lib/chef/resource/cookbook_file.rb
index f58ad786fc..8c3de119e9 100644
--- a/lib/chef/resource/cookbook_file.rb
+++ b/lib/chef/resource/cookbook_file.rb
@@ -24,6 +24,15 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the cookbook_file resource to transfer files from a sub-directory of COOKBOOK_NAME/files/ to a specified path
+    # located on a host that is running the chef-client. The file is selected according to file specificity, which allows
+    # different source files to be used based on the hostname, host platform (operating system, distro, or as appropriate),
+    # or platform version. Files that are located in the COOKBOOK_NAME/files/default sub-directory may be used on any
+    # platform.
+    #
+    # During a chef-client run, the checksum for each local file is calculated and then compared against the checksum for
+    # the same file as it currently exists in the cookbook on the Chef server. A file is not transferred when the checksums
+    # match. Only files that require an update are transferred from the Chef server to a node.
     class CookbookFile < Chef::Resource::File
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/cron.rb b/lib/chef/resource/cron.rb
index a76d454bf0..2b70be7bb8 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -21,6 +21,8 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the cron resource to manage cron entries for time-based job scheduling. Properties for a schedule will default
+    # to * if not provided. The cron resource requires access to a crontab program, typically cron.
     class Cron < Chef::Resource
 
       identity_attr :command
diff --git a/lib/chef/resource/csh.rb b/lib/chef/resource/csh.rb
index 4e7c22b660..ef302af6c0 100644
--- a/lib/chef/resource/csh.rb
+++ b/lib/chef/resource/csh.rb
@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the csh resource to execute scripts using the csh interpreter. This resource may also use any of the actions
+    # and properties that are available to the execute resource. Commands that are executed with this resource are (by
+    # their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if
+    # and only_if to guard this resource for idempotence.
     class Csh < Chef::Resource::Script
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/dnf_package.rb b/lib/chef/resource/dnf_package.rb
index 05ed895e70..0e09d90d43 100644
--- a/lib/chef/resource/dnf_package.rb
+++ b/lib/chef/resource/dnf_package.rb
@@ -21,6 +21,11 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the dnf_package resource to install, upgrade, and remove packages with DNF for Fedora platforms. The dnf_package
+    # resource is able to resolve provides data for packages much like DNF can do when it is run from the command line.
+    # This allows a variety of options for installing packages, like minimum versions, virtual provides, and library names.
+    #
+    # @since 12.18
     class DnfPackage < Chef::Resource::Package
       extend Chef::Mixin::Which
       extend Chef::Mixin::ShellOut
diff --git a/lib/chef/resource/dpkg_package.rb b/lib/chef/resource/dpkg_package.rb
index 9ff3239884..c73fc506ad 100644
--- a/lib/chef/resource/dpkg_package.rb
+++ b/lib/chef/resource/dpkg_package.rb
@@ -20,6 +20,8 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # 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.
     class DpkgPackage < Chef::Resource::Package
       resource_name :dpkg_package
       provides :dpkg_package, os: "linux"
diff --git a/lib/chef/resource/dsc_resource.rb b/lib/chef/resource/dsc_resource.rb
index d3b579e428..0840b9bca1 100644
--- a/lib/chef/resource/dsc_resource.rb
+++ b/lib/chef/resource/dsc_resource.rb
@@ -19,6 +19,11 @@ require "chef/dsl/powershell"
 
 class Chef
   class Resource
+    # The dsc_resource resource allows any DSC resource to be used in a Chef recipe, as well as any custom resources
+    # that have been added to your Windows PowerShell environment. Microsoft frequently adds new resources to the DSC
+    # resource collection.
+    #
+    # @since 12.2
     class DscResource < Chef::Resource
       provides :dsc_resource, os: "windows"
 
diff --git a/lib/chef/resource/dsc_script.rb b/lib/chef/resource/dsc_script.rb
index 7682c7e778..cea52e422b 100644
--- a/lib/chef/resource/dsc_script.rb
+++ b/lib/chef/resource/dsc_script.rb
@@ -21,6 +21,11 @@ require "chef/dsl/powershell"
 
 class Chef
   class Resource
+    # Many DSC resources are comparable to built-in Chef resources. For example, both DSC and Chef have file, package,
+    # and service resources. The dsc_script resource is most useful for those DSC resources that do not have a direct
+    # comparison to a resource in Chef, such as the Archive resource, a custom DSC resource, an existing DSC script
+    # that performs an important task, and so on. Use the dsc_script resource to embed the code that defines a DSC
+    # configuration directly within a Chef recipe.
     class DscScript < Chef::Resource
       include Chef::DSL::Powershell
 
diff --git a/lib/chef/resource/env.rb b/lib/chef/resource/env.rb
index 7071be4b91..12133f4368 100644
--- a/lib/chef/resource/env.rb
+++ b/lib/chef/resource/env.rb
@@ -19,6 +19,8 @@
 
 class Chef
   class Resource
+    # Use the 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.
     class Env < Chef::Resource
       resource_name :env
       provides :env, os: "windows"
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index ba1b8ae6e3..de927ec06e 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -22,6 +22,9 @@ require "chef/provider/execute"
 
 class Chef
   class Resource
+    # Use the execute resource to execute a single command. Commands that are executed with this resource are (by their
+    # nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if
+    # to guard this resource for idempotence.
     class Execute < Chef::Resource
 
       identity_attr :command
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index 0540385646..43d9c57150 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -25,6 +25,7 @@ require "pathname"
 
 class Chef
   class Resource
+    # Use the file resource to manage files directly on a node.
     class File < Chef::Resource
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/freebsd_package.rb b/lib/chef/resource/freebsd_package.rb
index eedddf28e7..caaba29129 100644
--- a/lib/chef/resource/freebsd_package.rb
+++ b/lib/chef/resource/freebsd_package.rb
@@ -26,6 +26,7 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the freebsd_package resource to manage packages for the FreeBSD platform.
     class FreebsdPackage < Chef::Resource::Package
       include Chef::Mixin::ShellOut
 
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index fc162a6033..8e3a426035 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -20,6 +20,8 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the gem_package resource to manage gem packages that are only included in recipes. When a package is installed
+    # from a local file, it must be added to the node using the remote_file or cookbook_file resources.
     class GemPackage < Chef::Resource::Package
       resource_name :gem_package
 
diff --git a/lib/chef/resource/git.rb b/lib/chef/resource/git.rb
index 4799b54d3d..ac4f027552 100644
--- a/lib/chef/resource/git.rb
+++ b/lib/chef/resource/git.rb
@@ -20,6 +20,8 @@ require "chef/resource/scm"
 
 class Chef
   class Resource
+    # Use the git resource to manage source control resources that exist in a git repository. git version 1.6.5 (or higher)
+    # is required to use all of the functionality in the git resource.
     class Git < Chef::Resource::Scm
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/group.rb b/lib/chef/resource/group.rb
index d3a4a1ce89..69a3827a5c 100644
--- a/lib/chef/resource/group.rb
+++ b/lib/chef/resource/group.rb
@@ -19,6 +19,7 @@
 
 class Chef
   class Resource
+    # Use the group resource to manage a local group.
     class Group < Chef::Resource
 
       identity_attr :group_name
diff --git a/lib/chef/resource/homebrew_package.rb b/lib/chef/resource/homebrew_package.rb
index c2d0a65c5b..6174a31079 100644
--- a/lib/chef/resource/homebrew_package.rb
+++ b/lib/chef/resource/homebrew_package.rb
@@ -23,6 +23,9 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the homebrew_package resource to manage packages for the macOS platform.
+    #
+    # @since 12.0
     class HomebrewPackage < Chef::Resource::Package
       resource_name :homebrew_package
       provides :package, os: "darwin"
diff --git a/lib/chef/resource/http_request.rb b/lib/chef/resource/http_request.rb
index 9fac3562f3..9d8fce9b22 100644
--- a/lib/chef/resource/http_request.rb
+++ b/lib/chef/resource/http_request.rb
@@ -22,6 +22,8 @@ require "chef/provider/http_request"
 
 class Chef
   class Resource
+    # Use the http_request resource to send an HTTP request (GET, PUT, POST, DELETE, HEAD, or OPTIONS) with an arbitrary
+    # message. This resource is often useful when custom callbacks are necessary.
     class HttpRequest < Chef::Resource
 
       identity_attr :url
diff --git a/lib/chef/resource/ips_package.rb b/lib/chef/resource/ips_package.rb
index 4d2c957e17..296919dc1c 100644
--- a/lib/chef/resource/ips_package.rb
+++ b/lib/chef/resource/ips_package.rb
@@ -21,6 +21,7 @@ require "chef/provider/package/ips"
 
 class Chef
   class Resource
+    # Use the ips_package resource to manage packages (using Image Packaging System (IPS)) on the Solaris 11 platform.
     class IpsPackage < ::Chef::Resource::Package
       resource_name :ips_package
       provides :package, os: "solaris2"
diff --git a/lib/chef/resource/ksh.rb b/lib/chef/resource/ksh.rb
index 3097156329..8024f0d6bd 100644
--- a/lib/chef/resource/ksh.rb
+++ b/lib/chef/resource/ksh.rb
@@ -20,6 +20,12 @@ require "chef/resource/script"
 
 class Chef
   class Resource
+    # Use the ksh resource to execute scripts using the Korn shell (ksh) interpreter. This resource may also use any
+    # f the actions and properties that are available to the execute resource. Commands that are executed with this
+    # resource are (by their nature) not idempotent, as they are typically unique to the environment in which they are
+    # run. Use not_if and only_if to guard this resource for idempotence.
+    #
+    # @since 12.6
     class Ksh < Chef::Resource::Script
 
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/launchd.rb b/lib/chef/resource/launchd.rb
index 3fba76e220..358d5462bc 100644
--- a/lib/chef/resource/launchd.rb
+++ b/lib/chef/resource/launchd.rb
@@ -21,6 +21,9 @@ require "chef/provider/launchd"
 
 class Chef
   class Resource
+    # Use the launchd resource to manage system-wide services (daemons) and per-user services (agents) on the macOS platform.
+    #
+    # @since 12.8
     class Launchd < Chef::Resource
       provides :launchd, os: "darwin"
 
diff --git a/lib/chef/resource/link.rb b/lib/chef/resource/link.rb
index 5717ec7bad..7a106b1703 100644
--- a/lib/chef/resource/link.rb
+++ b/lib/chef/resource/link.rb
@@ -22,6 +22,16 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the link resource to create symbolic or hard links.
+    #
+    # A symbolic link—sometimes referred to as a soft link—is a directory entry that associates a file name with a string
+    # that contains an absolute or relative path to a file on any file system. In other words, “a file that contains a path
+    # that points to another file.” A symbolic link creates a new file with a new inode that points to the inode location
+    # of the original file.
+    #
+    # A hard link is a directory entry that associates a file with another file in the same file system. In other words,
+    # “multiple directory entries to the same file.” A hard link creates a new file that points to the same inode as the
+    # original file.
     class Link < Chef::Resource
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/log.rb b/lib/chef/resource/log.rb
index 32d9629b73..b6da123526 100644
--- a/lib/chef/resource/log.rb
+++ b/lib/chef/resource/log.rb
@@ -21,7 +21,10 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # Sends a string to a log provider.
+    # Use the log resource to create log entries. The log resource behaves like any other resource: built into the resource
+    # collection during the compile phase, and then run during the execution phase. (To create a log entry that is not built
+    # into the resource collection, use Chef::Log instead of the log resource.)
+    #
     # Allows logging a :debug, :info, :warn, and :error levels
     # Defaults to :info level
     #
diff --git a/lib/chef/resource/macports_package.rb b/lib/chef/resource/macports_package.rb
index 3685334c17..e787529f48 100644
--- a/lib/chef/resource/macports_package.rb
+++ b/lib/chef/resource/macports_package.rb
@@ -20,6 +20,7 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the macports_package resource to manage packages for the macOS platform.
     class MacportsPackage < Chef::Resource::Package
       resource_name :macports_package
     end
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index df6e705f15..354582d1cf 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -21,6 +21,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the mdadm resource to manage RAID devices in a Linux environment using the mdadm utility. The mdadm resource
+    # will create and assemble an array, but it will not create the config file that is used to persist the array upon
+    # 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.
     class Mdadm < Chef::Resource
 
       identity_attr :raid_device
diff --git a/lib/chef/resource/mount.rb b/lib/chef/resource/mount.rb
index 9df2bbcdbc..1a1f8c0565 100644
--- a/lib/chef/resource/mount.rb
+++ b/lib/chef/resource/mount.rb
@@ -21,6 +21,7 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the mount resource to manage a mounted file system.
     class Mount < Chef::Resource
 
       identity_attr :device
diff --git a/lib/chef/resource/msu_package.rb b/lib/chef/resource/msu_package.rb
index 93c8fbbe21..77eeed898f 100644
--- a/lib/chef/resource/msu_package.rb
+++ b/lib/chef/resource/msu_package.rb
@@ -21,6 +21,9 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the msu_package resource to install Microsoft Update(MSU) packages on Microsoft Windows machines.
+    #
+    # @since 12.17
     class MsuPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
diff --git a/lib/chef/resource/ohai.rb b/lib/chef/resource/ohai.rb
index 6fffecf16e..f2534413ea 100644
--- a/lib/chef/resource/ohai.rb
+++ b/lib/chef/resource/ohai.rb
@@ -19,6 +19,8 @@
 
 class Chef
   class Resource
+    # Use the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes
+    # (like a recipe that adds a user) to refer to those attributes later on during the chef-client run.
     class Ohai < Chef::Resource
       resource_name :ohai
       provides :ohai
diff --git a/lib/chef/resource/openbsd_package.rb b/lib/chef/resource/openbsd_package.rb
index d0f9fe877f..e5cdefe684 100644
--- a/lib/chef/resource/openbsd_package.rb
+++ b/lib/chef/resource/openbsd_package.rb
@@ -25,6 +25,9 @@ require "chef/mixin/shell_out"
 
 class Chef
   class Resource
+    # Use the openbsd_package resource to manage packages for the OpenBSD platform.
+    #
+    # @since 12.1
     class OpenbsdPackage < Chef::Resource::Package
       include Chef::Mixin::ShellOut
 
diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb
index 5647f203d2..60810fd5ad 100644
--- a/lib/chef/resource/package.rb
+++ b/lib/chef/resource/package.rb
@@ -21,6 +21,12 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the package resource to manage packages. When the package is installed from a local file (such as with RubyGems,
+    # dpkg, or RPM Package Manager), the file must be added to the node using the remote_file or cookbook_file resources.
+    #
+    # This resource is the base resource for several other resources used for package management on specific platforms.
+    # While it is possible to use each of these specific resources, it is recommended to use the package resource as often
+    # as possible.
     class Package < Chef::Resource
       resource_name :package
 
diff --git a/lib/chef/resource/pacman_package.rb b/lib/chef/resource/pacman_package.rb
index 66b39d164d..73d8afb0de 100644
--- a/lib/chef/resource/pacman_package.rb
+++ b/lib/chef/resource/pacman_package.rb
@@ -20,6 +20,7 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the pacman_package resource to manage packages (using pacman) on the Arch Linux platform.
     class PacmanPackage < Chef::Resource::Package
       resource_name :pacman_package
       provides :pacman_package, os: "linux"
diff --git a/lib/chef/resource/paludis_package.rb b/lib/chef/resource/paludis_package.rb
index 31c0f31b8c..6bc598e4ee 100644
--- a/lib/chef/resource/paludis_package.rb
+++ b/lib/chef/resource/paludis_package.rb
@@ -21,6 +21,9 @@ require "chef/provider/package/paludis"
 
 class Chef
   class Resource
+    # Use the paludis_package resource to manage packages for the Paludis platform.
+    #
+    # @since 12.1
     class PaludisPackage < Chef::Resource::Package
       resource_name :paludis_package
       provides :paludis_package, os: "linux"
diff --git a/lib/chef/resource/perl.rb b/lib/chef/resource/perl.rb
index 60af0e92da..c00246ac6b 100644
--- a/lib/chef/resource/perl.rb
+++ b/lib/chef/resource/perl.rb
@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the perl resource to execute scripts using the Perl interpreter. This resource may also use any of the actions
+    # and properties that are available to the execute resource. Commands that are executed with this resource are (by
+    # their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and
+    # only_if to guard this resource for idempotence.
     class Perl < Chef::Resource::Script
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/portage_package.rb b/lib/chef/resource/portage_package.rb
index ad66c7b42b..a2bc516711 100644
--- a/lib/chef/resource/portage_package.rb
+++ b/lib/chef/resource/portage_package.rb
@@ -20,6 +20,7 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the portage_package resource to manage packages for the Gentoo platform.
     class PortagePackage < Chef::Resource::Package
       resource_name :portage_package
       def initialize(name, run_context = nil)
diff --git a/lib/chef/resource/powershell_package.rb b/lib/chef/resource/powershell_package.rb
index 4d658d3cc5..05c59acf73 100644
--- a/lib/chef/resource/powershell_package.rb
+++ b/lib/chef/resource/powershell_package.rb
@@ -20,6 +20,11 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the powershell_package resource to install and manage packages via the Powershell Package Manager for the
+    # Microsoft Windows platform. The powershell_package resource requires administrative access, and a source must be
+    # configured in the Powershell Package Manager via the Register-PackageSource command
+    #
+    # @since 12.16
     class PowershellPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
diff --git a/lib/chef/resource/powershell_script.rb b/lib/chef/resource/powershell_script.rb
index b2bd6e718e..8ff58cfeab 100644
--- a/lib/chef/resource/powershell_script.rb
+++ b/lib/chef/resource/powershell_script.rb
@@ -19,6 +19,14 @@ require "chef/resource/windows_script"
 
 class Chef
   class Resource
+    # Use the powershell_script resource to execute a script using the Windows PowerShell interpreter, much like how the
+    # script and script-based resources—bash, csh, perl, python, and ruby—are used. The powershell_script is specific to
+    # the Microsoft Windows platform and the Windows PowerShell interpreter.
+    #
+    # The powershell_script resource creates and executes a temporary file (similar to how the script resource behaves),
+    # rather than running the command inline. Commands that are executed with this resource are (by their nature) not
+    # idempotent, as they are typically unique to the environment in which they are run. Use not_if and only_if to guard
+    # this resource for idempotence.
     class PowershellScript < Chef::Resource::WindowsScript
       provides :powershell_script, os: "windows"
 
diff --git a/lib/chef/resource/python.rb b/lib/chef/resource/python.rb
index bcad3d090b..8c9e74217a 100644
--- a/lib/chef/resource/python.rb
+++ b/lib/chef/resource/python.rb
@@ -20,6 +20,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the python resource to execute scripts using the Python interpreter. This resource may also use any of the actions
+    # and properties that are available to the execute resource. Commands that are executed with this resource are (by
+    # their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and
+    # only_if to guard this resource for idempotence.
     class Python < Chef::Resource::Script
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb
index bdaa755533..e93c7f53c5 100644
--- a/lib/chef/resource/reboot.rb
+++ b/lib/chef/resource/reboot.rb
@@ -28,7 +28,7 @@ class Chef
     # immediate notifications. Delayed notifications produce unintuitive and
     # probably undesired results.
     #
-    # @since 12.0.0
+    # @since 12.0
     class Reboot < Chef::Resource
       resource_name :reboot
 
diff --git a/lib/chef/resource/registry_key.rb b/lib/chef/resource/registry_key.rb
index 549897bb1d..565ff278ea 100644
--- a/lib/chef/resource/registry_key.rb
+++ b/lib/chef/resource/registry_key.rb
@@ -21,6 +21,7 @@ require "chef/digester"
 
 class Chef
   class Resource
+    # Use the registry_key resource to create and delete registry keys in Microsoft Windows.
     class RegistryKey < Chef::Resource
       identity_attr :key
       state_attrs :values
diff --git a/lib/chef/resource/remote_directory.rb b/lib/chef/resource/remote_directory.rb
index 6e2928f3eb..b165606c79 100644
--- a/lib/chef/resource/remote_directory.rb
+++ b/lib/chef/resource/remote_directory.rb
@@ -23,6 +23,9 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # Use the remote_directory resource to incrementally transfer a directory from a cookbook to a node. The director
+    # that is copied from the cookbook should be located under COOKBOOK_NAME/files/default/REMOTE_DIRECTORY. The
+    # remote_directory resource will obey file specificity.
     class RemoteDirectory < Chef::Resource::Directory
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb
index 25586af702..4db055a20d 100644
--- a/lib/chef/resource/remote_file.rb
+++ b/lib/chef/resource/remote_file.rb
@@ -25,6 +25,8 @@ require "chef/mixin/uris"
 
 class Chef
   class Resource
+    # Use the remote_file resource to transfer a file from a remote location using file specificity. This resource is
+    # similar to the file resource.
     class RemoteFile < Chef::Resource::File
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/route.rb b/lib/chef/resource/route.rb
index 9412d28dce..922535f885 100644
--- a/lib/chef/resource/route.rb
+++ b/lib/chef/resource/route.rb
@@ -21,6 +21,7 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the route resource to manage the system routing table in a Linux environment.
     class Route < Chef::Resource
       default_action :add
       allowed_actions :add, :delete
diff --git a/lib/chef/resource/rpm_package.rb b/lib/chef/resource/rpm_package.rb
index c93dfecaf5..3760412a77 100644
--- a/lib/chef/resource/rpm_package.rb
+++ b/lib/chef/resource/rpm_package.rb
@@ -21,6 +21,7 @@ require "chef/provider/package/rpm"
 
 class Chef
   class Resource
+    # Use the rpm_package resource to manage packages for the RPM Package Manager platform.
     class RpmPackage < Chef::Resource::Package
       resource_name :rpm_package
       provides :rpm_package, os: %w{linux aix}
diff --git a/lib/chef/resource/ruby.rb b/lib/chef/resource/ruby.rb
index 91805a1db6..300405f89e 100644
--- a/lib/chef/resource/ruby.rb
+++ b/lib/chef/resource/ruby.rb
@@ -21,6 +21,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the ruby resource to execute scripts using the Ruby interpreter. This resource may also use any of the actions
+    # and properties that are available to the execute resource. Commands that are executed with this resource are (by
+    # their nature) not idempotent, as they are typically unique to the environment in which they are run. Use not_if and
+    # only_if to guard this resource for idempotence.
     class Ruby < Chef::Resource::Script
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index 87a4cfb7c5..89b90ae70b 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -22,6 +22,9 @@ require "chef/provider/ruby_block"
 
 class Chef
   class Resource
+    # Use the ruby_block resource to execute Ruby code during a chef-client run. Ruby code in the ruby_block resource is
+    # evaluated with other resources during convergence, whereas Ruby code outside of a ruby_block resource is evaluated
+    # before other resources, as the recipe is compiled.
     class RubyBlock < Chef::Resource
       default_action :run
       allowed_actions :create, :run
diff --git a/lib/chef/resource/script.rb b/lib/chef/resource/script.rb
index 5039e2d8fe..a7191360ca 100644
--- a/lib/chef/resource/script.rb
+++ b/lib/chef/resource/script.rb
@@ -22,6 +22,10 @@ require "chef/provider/script"
 
 class Chef
   class Resource
+    # Use the script resource to execute scripts using a specified interpreter, such as Bash, csh, Perl, Python, or Ruby.
+    # This resource may also use any of the actions and properties that are available to the execute resource. Commands
+    # that are executed with this resource are (by their nature) not idempotent, as they are typically unique to the
+    # environment in which they are run. Use not_if and only_if to guard this resource for idempotence.
     class Script < Chef::Resource::Execute
       identity_attr :name
 
diff --git a/lib/chef/resource/service.rb b/lib/chef/resource/service.rb
index 83e44c9d30..dc23155b59 100644
--- a/lib/chef/resource/service.rb
+++ b/lib/chef/resource/service.rb
@@ -22,6 +22,7 @@ require "shellwords"
 
 class Chef
   class Resource
+    # Use the service resource to manage a service.
     class Service < Chef::Resource
       identity_attr :service_name
 
diff --git a/lib/chef/resource/smartos_package.rb b/lib/chef/resource/smartos_package.rb
index 87173ccfa9..9e79cace3f 100644
--- a/lib/chef/resource/smartos_package.rb
+++ b/lib/chef/resource/smartos_package.rb
@@ -21,6 +21,7 @@ require "chef/provider/package/smartos"
 
 class Chef
   class Resource
+    # Use the smartos_package resource to manage packages for the SmartOS platform.
     class SmartosPackage < Chef::Resource::Package
       resource_name :smartos_package
       provides :package, os: "solaris2", platform_family: "smartos"
diff --git a/lib/chef/resource/solaris_package.rb b/lib/chef/resource/solaris_package.rb
index d0f8c144af..24215bb456 100644
--- a/lib/chef/resource/solaris_package.rb
+++ b/lib/chef/resource/solaris_package.rb
@@ -22,6 +22,7 @@ require "chef/provider/package/solaris"
 
 class Chef
   class Resource
+    # The solaris_package resource is used to manage packages for the Solaris platform.
     class SolarisPackage < Chef::Resource::Package
       resource_name :solaris_package
       provides :package, os: "solaris2", platform_family: "nexentacore"
diff --git a/lib/chef/resource/subversion.rb b/lib/chef/resource/subversion.rb
index 9966614eeb..473a48cefd 100644
--- a/lib/chef/resource/subversion.rb
+++ b/lib/chef/resource/subversion.rb
@@ -21,6 +21,7 @@ require "chef/resource/scm"
 
 class Chef
   class Resource
+    # Use the subversion resource to manage source control resources that exist in a Subversion repository.
     class Subversion < Chef::Resource::Scm
       allowed_actions :force_export
 
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index 66c4e6f594..b08b26efa7 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -21,6 +21,9 @@ require "iniparse"
 
 class Chef
   class Resource
+    # Use the systemd_unit resource to create, manage, and run systemd units.
+    #
+    # @since 12.11
     class SystemdUnit < Chef::Resource
       resource_name :systemd_unit
 
diff --git a/lib/chef/resource/template.rb b/lib/chef/resource/template.rb
index 896aa71340..4b5b82effb 100644
--- a/lib/chef/resource/template.rb
+++ b/lib/chef/resource/template.rb
@@ -24,6 +24,15 @@ require "chef/mixin/securable"
 
 class Chef
   class Resource
+    # A cookbook template is an Embedded Ruby (ERB) template that is used to dynamically generate static text files.
+    # Templates may contain Ruby expressions and statements, and are a great way to manage configuration files. Use the
+    # template resource to add cookbook templates to recipes; place the corresponding Embedded Ruby (ERB) template file
+    # in a cookbook’s /templates directory.
+    #
+    # Use the template resource to manage the contents of a file using an Embedded Ruby (ERB) template by transferring
+    # files from a sub-directory of COOKBOOK_NAME/templates/ to a specified path located on a host that is running the
+    # chef-client. This resource includes actions and properties from the file resource. Template files managed by the
+    # template resource follow the same file specificity rules as the remote_file and file resources.
     class Template < Chef::Resource::File
       include Chef::Mixin::Securable
 
diff --git a/lib/chef/resource/user.rb b/lib/chef/resource/user.rb
index 380671113a..39d8159d4f 100644
--- a/lib/chef/resource/user.rb
+++ b/lib/chef/resource/user.rb
@@ -20,6 +20,7 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the user resource to add users, update existing users, remove users, and to lock/unlock user passwords.
     class User < Chef::Resource
       resource_name :user_resource_abstract_base_class # this prevents magickal class name DSL wiring
       identity_attr :username
diff --git a/lib/chef/resource/windows_package.rb b/lib/chef/resource/windows_package.rb
index e37bad4b0a..d373e1f19c 100644
--- a/lib/chef/resource/windows_package.rb
+++ b/lib/chef/resource/windows_package.rb
@@ -23,6 +23,8 @@ require "chef/win32/error" if RUBY_PLATFORM =~ /mswin|mingw|windows/
 
 class Chef
   class Resource
+    # Use the windows_package resource to manage Microsoft Installer Package (MSI) packages for the Microsoft Windows
+    # platform.
     class WindowsPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
diff --git a/lib/chef/resource/windows_path.rb b/lib/chef/resource/windows_path.rb
index 5472a7e4fd..9274415755 100644
--- a/lib/chef/resource/windows_path.rb
+++ b/lib/chef/resource/windows_path.rb
@@ -20,6 +20,9 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the windows_path resource to manage the path environment variable on Microsoft Windows.
+    #
+    # @since 13.4
     class WindowsPath < Chef::Resource
 
       provides :windows_path, os: "windows"
diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb
index 405f7f6dbe..1c7c61320f 100644
--- a/lib/chef/resource/windows_service.rb
+++ b/lib/chef/resource/windows_service.rb
@@ -20,6 +20,9 @@ require "chef/resource/service"
 
 class Chef
   class Resource
+    # Use the windows_service resource to manage a service on the Microsoft Windows platform.
+    #
+    # @since 12.0
     class WindowsService < Chef::Resource::Service
 
       # Until #1773 is resolved, you need to manually specify the windows_service resource
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index 344ce50b64..f61a119b5a 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -20,6 +20,9 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # Use the windows_task resource to create, delete or run a Windows scheduled task. Requires Windows Server 2008
+    # or later due to API usage.
+    # @since 13.0
     class WindowsTask < Chef::Resource
 
       resource_name :windows_task
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 012a74908a..231315e662 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -20,6 +20,10 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # 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.
+    #
+    # @since 12.14
     class YumRepository < Chef::Resource
       resource_name :yum_repository
       provides :yum_repository
diff --git a/lib/chef/resource/zypper_package.rb b/lib/chef/resource/zypper_package.rb
index 20b1a9f25f..f412d59988 100644
--- a/lib/chef/resource/zypper_package.rb
+++ b/lib/chef/resource/zypper_package.rb
@@ -20,6 +20,8 @@ require "chef/resource/package"
 
 class Chef
   class Resource
+    # Use the zypper_package resource to install, upgrade, and remove packages with Zypper for the SUSE Enterprise and
+    # OpenSUSE platforms.
     class ZypperPackage < Chef::Resource::Package
       resource_name :zypper_package
       provides :package, platform_family: "suse"
diff --git a/lib/chef/resource/zypper_repository.rb b/lib/chef/resource/zypper_repository.rb
index 88b6fd9336..c0ec111c25 100644
--- a/lib/chef/resource/zypper_repository.rb
+++ b/lib/chef/resource/zypper_repository.rb
@@ -20,6 +20,11 @@ require "chef/resource"
 
 class Chef
   class Resource
+    # The zypper_repository resource allows for the creation of 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.
+    #
+    # @since 13.3
     class ZypperRepository < Chef::Resource
       resource_name :zypper_repository
       provides :zypper_repo