Merge pull request #6994 from chef/cleanup

Add more resource descriptions and convert resources to use properties

17 files changed, 85 insertions, 142 deletions

diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 485210090d..4738d0cbbe 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -26,8 +26,13 @@ class Chef
 
       description "Use the apt_package resource to manage packages on Debian and Ubuntu platforms."
 
-      property :default_release, String, desired_state: false
-      property :overwrite_config_files, [TrueClass, FalseClass], default: false
+      property :default_release, String,
+               description: "The default release. For example: stable.",
+               desired_state: false
+
+      property :overwrite_config_files, [TrueClass, FalseClass],
+               description: "Overwrite existing config files with those in the package if prompted by apt.",
+               default: false
 
     end
   end
diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 442d85a78a..42e2c66aef 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -30,10 +30,21 @@ class Chef
                   " sources are prioritized during installation."
       introduced "13.3"
 
-      property :package_name, String, name_property: true, regex: [/^([a-z]|[A-Z]|[0-9]|_|-|\.|\*|\+)+$/]
-      property :glob, String
-      property :pin, String, required: true
-      property :pin_priority, [String, Integer], required: true
+      property :package_name, String,
+               name_property: true,
+               description: "The name of the package.",
+               regex: [/^([a-z]|[A-Z]|[0-9]|_|-|\.|\*|\+)+$/]
+
+      property :glob, String,
+               description: "Pin by glob() expression or with regular expressions surrounded by /."
+
+      property :pin, String,
+               description: "The package version or repository to pin.",
+               required: true
+
+      property :pin_priority, [String, Integer],
+               description: "Sets the Pin-Priority for a package.",
+               required: true
 
       default_action :add
       allowed_actions :add, :remove
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 8977444692..7998006398 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -30,6 +30,9 @@ class Chef
                default: false
 
       action :install do
+
+        description "Install build essential packages"
+
         case node["platform_family"]
         when "debian"
           declare_resource(:package,  %w{ autoconf binutils-doc bison build-essential flex gettext ncurses-dev })
diff --git a/lib/chef/resource/openssl_rsa_private_key.rb b/lib/chef/resource/openssl_rsa_private_key.rb
index 352d802175..88e110d63b 100644
--- a/lib/chef/resource/openssl_rsa_private_key.rb
+++ b/lib/chef/resource/openssl_rsa_private_key.rb
@@ -40,7 +40,7 @@ class Chef
 
       property :key_length, Integer,
                equal_to: [1024, 2048, 4096, 8192],
-               validation_message: "key_length must be 1024, 2048, 4096, or 8192.",
+               validation_message: "key_length (bits) must be 1024, 2048, 4096, or 8192.",
                description: "The desired bit length of the generated key.",
                default: 2048
 
diff --git a/lib/chef/resource/powershell_package.rb b/lib/chef/resource/powershell_package.rb
index f5ff99fff8..184b63f950 100644
--- a/lib/chef/resource/powershell_package.rb
+++ b/lib/chef/resource/powershell_package.rb
@@ -20,15 +20,16 @@ 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
     class PowershellPackage < Chef::Resource::Package
       include Chef::Mixin::Uris
 
       resource_name :powershell_package
       provides :powershell_package
 
+      description "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"
       introduced "12.16"
 
       allowed_actions :install, :remove
diff --git a/lib/chef/resource/python.rb b/lib/chef/resource/python.rb
index 8c9e74217a..f6c259b858 100644
--- a/lib/chef/resource/python.rb
+++ b/lib/chef/resource/python.rb
@@ -20,16 +20,17 @@ 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
         @interpreter = "python"
       end
 
+      description "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."
     end
   end
 end
diff --git a/lib/chef/resource/reboot.rb b/lib/chef/resource/reboot.rb
index 9879c05395..bc649bee09 100644
--- a/lib/chef/resource/reboot.rb
+++ b/lib/chef/resource/reboot.rb
@@ -20,16 +20,15 @@ require "chef/resource"
 
 class Chef
   class Resource
-    # Use the reboot resource to reboot a node, a necessary step with some
-    # installations on certain platforms. This resource is supported for use on
-    # the Microsoft Windows, macOS, and Linux platforms.
-    #
-    # In using this resource via notifications, it's important to *only* use
-    # immediate notifications. Delayed notifications produce unintuitive and
-    # probably undesired results.
     class Reboot < Chef::Resource
       resource_name :reboot
 
+      description "Use the reboot resource to reboot a node, a necessary step with some"\
+                  " installations on certain platforms. This resource is supported for use on"\
+                  " the Microsoft Windows, macOS, and Linux platforms.\n"\
+                  "In using this resource via notifications, it's important to *only* use"\
+                  " immediate notifications. Delayed notifications produce unintuitive and"\
+                  " probably undesired results."
       introduced "12.0"
 
       allowed_actions :request_reboot, :reboot_now, :cancel
diff --git a/lib/chef/resource/remote_directory.rb b/lib/chef/resource/remote_directory.rb
index b165606c79..677f358cc2 100644
--- a/lib/chef/resource/remote_directory.rb
+++ b/lib/chef/resource/remote_directory.rb
@@ -23,12 +23,14 @@ 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
 
+      description "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."
+
       identity_attr :path
 
       state_attrs :files_owner, :files_group, :files_mode
diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb
index a320fd8b47..7aaff890ef 100644
--- a/lib/chef/resource/remote_file.rb
+++ b/lib/chef/resource/remote_file.rb
@@ -25,11 +25,12 @@ 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
 
+      description "Use the remote_file resource to transfer a file from a remote location"\
+                  " using file specificity. This resource is similar to the file resource."
+
       def initialize(name, run_context = nil)
         super
         @source = []
diff --git a/lib/chef/resource/ruby.rb b/lib/chef/resource/ruby.rb
index 300405f89e..b5f36bb0e9 100644
--- a/lib/chef/resource/ruby.rb
+++ b/lib/chef/resource/ruby.rb
@@ -21,11 +21,13 @@ 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
+      description "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."
+
       def initialize(name, run_context = nil)
         super
         @interpreter = "ruby"
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index a3cb9e56e5..911e6203d8 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -22,10 +22,12 @@ 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
+      description "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."
+
       default_action :run
       allowed_actions :create, :run
 
diff --git a/lib/chef/resource/scm.rb b/lib/chef/resource/scm.rb
index 178dcca640..8bc55a7974 100644
--- a/lib/chef/resource/scm.rb
+++ b/lib/chef/resource/scm.rb
@@ -21,20 +21,11 @@ require "chef/resource"
 class Chef
   class Resource
     class Scm < Chef::Resource
-      state_attrs :revision
-
       default_action :sync
       allowed_actions :checkout, :export, :sync, :diff, :log
 
       def initialize(name, run_context = nil)
         super
-        @enable_submodules = false
-        @enable_checkout = true
-        @remote = "origin"
-        @ssh_wrapper = nil
-        @depth = nil
-        @checkout_branch = "deploy"
-        @environment = nil
       end
 
       property :destination, String, name_property: true, identity: true
@@ -44,6 +35,15 @@ class Chef
       property :group, [String, Integer]
       property :svn_username, String
       property :svn_password, String, sensitive: true, desired_state: false
+      # Capistrano and git-deploy use ``shallow clone''
+      property :depth, Integer
+      property :enable_submodules, [TrueClass, FalseClass], default: false
+      property :enable_checkout, [TrueClass, FalseClass], default: true
+      property :remote, String, default: "origin"
+      property :ssh_wrapper, String
+      property :timeout, Integer
+      property :checkout_branch, String, default: "deploy"
+      property :environment, [Hash, nil], default: nil
 
       def svn_arguments(arg = nil)
         @svn_arguments, arg = nil, nil if arg == false
@@ -62,71 +62,6 @@ class Chef
           :kind_of => String)
       end
 
-      # Capistrano and git-deploy use ``shallow clone''
-      def depth(arg = nil)
-        set_or_return(
-          :depth,
-          arg,
-          :kind_of => Integer
-        )
-      end
-
-      def enable_submodules(arg = nil)
-        set_or_return(
-          :enable_submodules,
-          arg,
-          :kind_of => [TrueClass, FalseClass]
-        )
-      end
-
-      def enable_checkout(arg = nil)
-        set_or_return(
-          :enable_checkout,
-          arg,
-          :kind_of => [TrueClass, FalseClass]
-        )
-      end
-
-      def remote(arg = nil)
-        set_or_return(
-          :remote,
-          arg,
-          :kind_of => String
-        )
-      end
-
-      def ssh_wrapper(arg = nil)
-        set_or_return(
-          :ssh_wrapper,
-          arg,
-          :kind_of => String
-        )
-      end
-
-      def timeout(arg = nil)
-        set_or_return(
-          :timeout,
-          arg,
-          :kind_of => Integer
-        )
-      end
-
-      def checkout_branch(arg = nil)
-        set_or_return(
-          :checkout_branch,
-          arg,
-          :kind_of => String
-        )
-      end
-
-      def environment(arg = nil)
-        set_or_return(
-          :environment,
-          arg,
-          :kind_of => [ Hash ]
-        )
-      end
-
       alias :env :environment
     end
   end
diff --git a/lib/chef/resource/script.rb b/lib/chef/resource/script.rb
index 7cadb843e5..d3562ee6f5 100644
--- a/lib/chef/resource/script.rb
+++ b/lib/chef/resource/script.rb
@@ -21,15 +21,16 @@ require "chef/resource/execute"
 
 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
       resource_name :script
 
       identity_attr :name
 
+      description "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."
+
       def initialize(name, run_context = nil)
         super
         @command = nil
diff --git a/lib/chef/resource/subversion.rb b/lib/chef/resource/subversion.rb
index 59f7cd73fd..b093ad3097 100644
--- a/lib/chef/resource/subversion.rb
+++ b/lib/chef/resource/subversion.rb
@@ -31,7 +31,6 @@ class Chef
         super
         @svn_arguments = "--no-auth-cache"
         @svn_info_args = "--no-auth-cache"
-        @svn_binary = nil
       end
 
       # Override exception to strip password if any, so it won't appear in logs and different Chef notifications
@@ -39,9 +38,7 @@ class Chef
         "#{self} (#{defined_at}) had an error: #{e.class.name}: #{svn_password ? e.message.gsub(svn_password, "[hidden_password]") : e.message}"
       end
 
-      def svn_binary(arg = nil)
-        set_or_return(:svn_binary, arg, :kind_of => [String])
-      end
+      property :svn_binary, String
     end
   end
 end
diff --git a/lib/chef/resource/template.rb b/lib/chef/resource/template.rb
index 59e8a76937..5fc29ec1c6 100644
--- a/lib/chef/resource/template.rb
+++ b/lib/chef/resource/template.rb
@@ -44,9 +44,6 @@ class Chef
       def initialize(name, run_context = nil)
         super
         @source = "#{::File.basename(name)}.erb"
-        @cookbook = nil
-        @local = false
-        @variables = Hash.new
         @inline_helper_blocks = {}
         @inline_helper_modules = []
         @helper_modules = []
@@ -60,29 +57,9 @@ class Chef
         )
       end
 
-      def variables(args = nil)
-        set_or_return(
-          :variables,
-          args,
-          :kind_of => [ Hash ]
-        )
-      end
-
-      def cookbook(args = nil)
-        set_or_return(
-          :cookbook,
-          args,
-          :kind_of => [ String ]
-        )
-      end
-
-      def local(args = nil)
-        set_or_return(
-          :local,
-          args,
-          :kind_of => [ TrueClass, FalseClass ]
-        )
-      end
+      property :variables, Hash, default: lazy { Hash.new }
+      property :cookbook, String
+      property :local, [ TrueClass, FalseClass ], default: false
 
       # Declares a helper method to be defined in the template context when
       # rendering.
diff --git a/lib/chef/resource/windows_env.rb b/lib/chef/resource/windows_env.rb
index 5cb3c2aca6..3f1c13ecef 100644
--- a/lib/chef/resource/windows_env.rb
+++ b/lib/chef/resource/windows_env.rb
@@ -24,7 +24,7 @@ class Chef
     class WindowsEnv < Chef::Resource
       resource_name :windows_env
       provides :windows_env
-      provides :env
+      provides :env # backwards compat with the pre-Chef 14 resource name
 
       description "Use the env resource to manage environment keys in Microsoft Windows."\
                   " After an environment key is set, Microsoft Windows must be restarted"\
diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb
index f066e3f0ad..905cacc477 100644
--- a/lib/chef/resource/yum_package.rb
+++ b/lib/chef/resource/yum_package.rb
@@ -24,6 +24,12 @@ class Chef
       resource_name :yum_package
       provides :package, platform_family: %w{rhel fedora amazon}
 
+      description "Use the yum_package resource to install, upgrade, and remove packages with Yum"\
+                  " for the Red Hat and CentOS platforms. The yum_package resource is able to resolve"\
+                  " provides data for packages much like Yum 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."
+
       # XXX: the coercions here are due to the provider promiscuously updating the properties on the
       # new_resource which causes immutable modification exceptions when passed an immutable node array.
       #