Add more description fields, style fixes, add missing requires

Make sure to require chef/resource everywhere. It would work without it but only because some other resource had already required it.

Put the type on the same line as the property, which we discussed in slack

Put introduced after description which makes differing simpler

Convert some yard into description fields

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

20 files changed, 59 insertions, 58 deletions

diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 881f932b30..1885471cb8 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -22,7 +22,12 @@ class Chef
       resource_name :build_essential
       provides :build_essential
 
-      property :compile_time, [true, false], default: false
+      description "Use the build_essential resource to install packages required for compiling C software from source"
+      introduced "14.0"
+
+      property :compile_time, [true, false],
+               description: "Install build essential packages at compile time.",
+               default: false
 
       action :install do
         case node["platform_family"]
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 16986c09a3..dfc7ee2ff0 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -9,28 +9,23 @@ class Chef
       description "Sets the systems hostname, ensures that reboot will preserve the hostname, and re-runs the ohai plugin so the hostname will be available in subsequent cookbooks."
       introduced "14.0"
 
-      property :hostname,
-               String,
+      property :hostname, String,
                description: "The hostname if different than the resource's name",
                name_property: true
 
-      property :compile_time,
-               [ TrueClass, FalseClass ],
+      property :compile_time, [ TrueClass, FalseClass ],
                description: "Should the resource run at compile time or not.",
                default: true
 
-      property :ipaddress,
-               String,
+      property :ipaddress, String,
                description: "The ip address to use when configuring the hosts file",
                default: lazy { node["ipaddress"] }
 
-      property :aliases,
-               [ Array, nil ],
+      property :aliases, [ Array, nil ],
                description: "An array of hostname aliases to use when configuring the hosts file",
                default: nil
 
-      property :windows_reboot,
-               [ TrueClass, FalseClass ],
+      property :windows_reboot, [ TrueClass, FalseClass ],
                description: "Should Windows nodes be rebooted upon changing the name so it can take effect",
                default: true
 
diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index c0066c84b5..08badc4c84 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -25,12 +25,11 @@ class Chef
       provides :mac_os_x_userdefaults
       provides :macos_userdefaults
 
-      introduced "14.0"
-
       description "Use the macos_userdefaults resource to manage the macOS user defaults"\
                   " system. The properties to the resource are passed to the defaults command"\
                   " and the parameters follow convention of the macOS command. See the defaults(1)"\
                   " man page for details on how the tool works."
+      introduced "14.0"
 
       property :domain,
                String,
diff --git a/lib/chef/resource/macosx_service.rb b/lib/chef/resource/macosx_service.rb
index a12add2109..9a88e3bbfc 100644
--- a/lib/chef/resource/macosx_service.rb
+++ b/lib/chef/resource/macosx_service.rb
@@ -25,6 +25,8 @@ class Chef
       provides :macosx_service, os: "darwin"
       provides :service, os: "darwin"
 
+      description "Use the macosx_service resource to manage services on the macOS platform."
+
       identity_attr :service_name
 
       state_attrs :enabled, :running
diff --git a/lib/chef/resource/macports_package.rb b/lib/chef/resource/macports_package.rb
index e787529f48..254d7e7c5f 100644
--- a/lib/chef/resource/macports_package.rb
+++ b/lib/chef/resource/macports_package.rb
@@ -20,9 +20,10 @@ 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
+
+      description "Use the macports_package resource to manage packages for the macOS platform."
     end
   end
 end
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index 6d4014b110..c8752ba038 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -21,13 +21,14 @@ 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
       resource_name :mdadm
 
+      description "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."
+
       default_action :create
       allowed_actions :create, :assemble, :stop
 
diff --git a/lib/chef/resource/ohai.rb b/lib/chef/resource/ohai.rb
index f2534413ea..b506d511ba 100644
--- a/lib/chef/resource/ohai.rb
+++ b/lib/chef/resource/ohai.rb
@@ -19,12 +19,14 @@
 
 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
 
+      description "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."
+
       property :ohai_name, name_property: true
       property :plugin, [String]
 
diff --git a/lib/chef/resource/ohai_hint.rb b/lib/chef/resource/ohai_hint.rb
index 26b76806d7..90755300ca 100644
--- a/lib/chef/resource/ohai_hint.rb
+++ b/lib/chef/resource/ohai_hint.rb
@@ -21,17 +21,15 @@ class Chef
       resource_name :ohai_hint
       provides :ohai_hint
 
-      description "A resource to pass hint data to Ohai to aid in configuration detection."
+      description "Use the ohai_hint resource to pass hint data to Ohai to aid in configuration detection."
       introduced "14.0"
 
-      property :hint_name,
-               String,
-               description: "The name of hints file if different from the resource name",
+      property :hint_name, String,
+               description: "The name of hints file if different from the resource name.",
                name_property: true
 
-      property :content,
-               Hash,
-               description: "Values to include in the hint file"
+      property :content, Hash,
+               description: "Values to include in the hint file."
 
       property :compile_time,
                [TrueClass, FalseClass],
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 729d5a585a..d08e9783fa 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -27,12 +27,12 @@ class Chef
       provides :openssl_rsa_private_key
       provides :openssl_rsa_key # legacy cookbook resource name
 
-      introduced "14.0"
       description "Use the openssl_rsa_private_key resource to generate RSA private key files."\
                   " If a valid RSA key file can be opened at the specified location, no new file"\
                   " will be created. If the RSA key file cannot be opened, either because it does"\
                   " not exist or because the password to the RSA key file does not match the"\
                   " password in the recipe, it will be overwritten."
+      introduced "14.0"
 
       property :path, String,
                description: "The path to write the file to it's different than the resource name.",
diff --git a/lib/chef/resource/osx_profile.rb b/lib/chef/resource/osx_profile.rb
index 56eca90a7e..a2f880d38d 100644
--- a/lib/chef/resource/osx_profile.rb
+++ b/lib/chef/resource/osx_profile.rb
@@ -20,20 +20,19 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # 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.
     class OsxProfile < Chef::Resource
       provides :osx_profile, os: "darwin"
       provides :osx_config_profile, os: "darwin"
 
       identity_attr :profile_name
 
-      description "12.7"
+      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"
 
       default_action :install
-
       allowed_actions :install, :remove
 
       property :profile_name, String, name_property: true
diff --git a/lib/chef/resource/rhsm_errata.rb b/lib/chef/resource/rhsm_errata.rb
index 56779909f5..ca3e71648f 100644
--- a/lib/chef/resource/rhsm_errata.rb
+++ b/lib/chef/resource/rhsm_errata.rb
@@ -27,8 +27,7 @@ class Chef
                   " to mitigate a single vulnerability must be installed on your hosts."
       introduced "14.0"
 
-      property :errata_id,
-               String,
+      property :errata_id, String,
                description: "An optional property for specifying the errata ID if not using the resource's name.",
                name_property: true
 
diff --git a/lib/chef/resource/rhsm_errata_level.rb b/lib/chef/resource/rhsm_errata_level.rb
index 3aa289ac2e..bab4d6ef26 100644
--- a/lib/chef/resource/rhsm_errata_level.rb
+++ b/lib/chef/resource/rhsm_errata_level.rb
@@ -28,8 +28,7 @@ class Chef
                   " security level are installed."
       introduced "14.0"
 
-      property :errata_level,
-               String,
+      property :errata_level, String,
                coerce: proc { |x| x.downcase },
                equal_to: %w{critical moderate important low},
                description: "The errata level of packages to install.",
diff --git a/lib/chef/resource/rhsm_register.rb b/lib/chef/resource/rhsm_register.rb
index 47fe67d1cf..fe2c6a2391 100644
--- a/lib/chef/resource/rhsm_register.rb
+++ b/lib/chef/resource/rhsm_register.rb
@@ -27,29 +27,23 @@ class Chef
                   " or a local Red Hat Satellite server."
       introduced "14.0"
 
-      property :activation_key,
-               [String, Array],
+      property :activation_key, [String, Array],
                coerce: proc { |x| Array(x) },
                description: "A String or array of the activation keys to use when registering. You must also specify the organization property if using activation_key."
 
-      property :satellite_host,
-               String,
+      property :satellite_host, String,
                description: "The FQDN of the Satellite host to register with. If not specified, the host will be registered with Red Hat's public RHSM service."
 
-      property :organization,
-               String,
+      property :organization, String,
                description: "The organization to use when registering, required when using an activation key"
 
-      property :environment,
-               String,
+      property :environment, String,
                description: "The environment to use when registering, required when using username and password"
 
-      property :username,
-               String,
+      property :username, String,
                description: "The username to use when registering. Not applicable if using an activation key. If specified, password and environment are also required."
 
-      property :password,
-               String,
+      property :password, String,
                description: "The password to use when registering. Not applicable if using an activation key. If specified, username and environment are also required."
 
       property :auto_attach,
@@ -57,13 +51,11 @@ class Chef
                description: "If true, RHSM will attempt to automatically attach the host to applicable subscriptions. It is generally better to use an activation key with the subscriptions pre-defined.",
                default: false
 
-      property :install_katello_agent,
-               [TrueClass, FalseClass],
+      property :install_katello_agent, [TrueClass, FalseClass],
                description: "If true, the 'katello-agent' RPM will be installed.",
                default: true
 
-      property :force,
-               [TrueClass, FalseClass],
+      property :force, [TrueClass, FalseClass],
                description: "If true, the system will be registered even if it is already registered. Normally, any register operations will fail if the machine is has already registered.",
                default: false
 
diff --git a/lib/chef/resource/rhsm_repo.rb b/lib/chef/resource/rhsm_repo.rb
index aef4dd43d6..689874a774 100644
--- a/lib/chef/resource/rhsm_repo.rb
+++ b/lib/chef/resource/rhsm_repo.rb
@@ -26,8 +26,7 @@ class Chef
                   " repositories that are made available via attached subscriptions."
       introduced "14.0"
 
-      property :repo_name,
-               String,
+      property :repo_name, String,
                description: "An optional property for specifying the repository name if not using the resource's name.",
                name_property: true
 
diff --git a/lib/chef/resource/rhsm_subscription.rb b/lib/chef/resource/rhsm_subscription.rb
index 41dd398cd5..21ee539dda 100644
--- a/lib/chef/resource/rhsm_subscription.rb
+++ b/lib/chef/resource/rhsm_subscription.rb
@@ -27,8 +27,7 @@ class Chef
                   " does not attach all necessary subscriptions to your host."
       introduced "14.0"
 
-      property :pool_id,
-               String,
+      property :pool_id, String,
                description: "An optional property for specifying the Pool ID if not using the resource's name.",
                name_property: true
 
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index f5f0bd126d..b970a397aa 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -17,6 +17,8 @@
 # limitations under the License.
 #
 
+require "chef/resource"
+
 class Chef
   class Resource
     class WindowsEnv < Chef::Resource
diff --git a/lib/chef/resource/windows_feature.rb b/lib/chef/resource/windows_feature.rb
index 42f5524cc1..91c19dbc29 100644
--- a/lib/chef/resource/windows_feature.rb
+++ b/lib/chef/resource/windows_feature.rb
@@ -15,6 +15,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+require "chef/resource"
+
 class Chef
   class Resource
     class WindowsFeature < Chef::Resource
diff --git a/lib/chef/resource/windows_feature_dism.rb b/lib/chef/resource/windows_feature_dism.rb
index 6ffaf318d5..d6f23f49c5 100644
--- a/lib/chef/resource/windows_feature_dism.rb
+++ b/lib/chef/resource/windows_feature_dism.rb
@@ -16,6 +16,8 @@
 # limitations under the License.
 #
 
+require "chef/resource"
+
 class Chef
   class Resource
     class WindowsFeatureDism < Chef::Resource
diff --git a/lib/chef/resource/windows_feature_powershell.rb b/lib/chef/resource/windows_feature_powershell.rb
index 30f8f6da83..65fa3cc40b 100644
--- a/lib/chef/resource/windows_feature_powershell.rb
+++ b/lib/chef/resource/windows_feature_powershell.rb
@@ -16,6 +16,8 @@
 # limitations under the License.
 #
 
+require "chef/resource"
+
 class Chef
   class Resource
     class WindowsFeaturePowershell < Chef::Resource
diff --git a/lib/chef/resource/windows_pagefile.rb b/lib/chef/resource/windows_pagefile.rb
index 069e76107c..849f948a26 100644
--- a/lib/chef/resource/windows_pagefile.rb
+++ b/lib/chef/resource/windows_pagefile.rb
@@ -15,6 +15,8 @@
 # limitations under the License.
 #
 
+require "chef/resource"
+
 class Chef
   class Resource
     class WindowsPagefile < Chef::Resource