Merge pull request #7195 from chef/cleanup

Add descriptions to more resources

12 files changed, 75 insertions, 68 deletions

diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index e546a54225..0169fb73c2 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -25,9 +25,7 @@ class Chef
       resource_name :apt_preference
       provides(:apt_preference) { true }
 
-      description "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."
+      description "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."
       introduced "13.3"
 
       property :package_name, String,
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 236e9477e0..0ed38e61d3 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -24,8 +24,7 @@ class Chef
       resource_name :apt_repository
       provides(:apt_repository) { true }
 
-      description "Use the apt_repository resource to specify additional APT repositories."\
-                  " Adding a new repository will update APT package cache immediately."
+      description "Use the apt_repository resource to specify additional APT repositories. Adding a new repository will update the APT package cache immediately."
       introduced "12.9"
 
       # There's a pile of [ String, nil, FalseClass ] types in these properties.
@@ -35,22 +34,50 @@ class Chef
       # to allow that so don't refactor this however tempting it is
       property :repo_name, String,
                regex: [/^[^\/]+$/],
+               description: "The name of the repository to configure, if it differs from the name of the resource block. The value of this setting must not contain spaces.",
                validation_message: "repo_name property cannot contain a forward slash '/'",
                name_property: true
 
-      property :uri, String
-      property :distribution, [ String, nil, FalseClass ], default: lazy { node["lsb"]["codename"] }
-      property :components, Array, default: lazy { [] }
-      property :arch, [String, nil, FalseClass]
-      property :trusted, [TrueClass, FalseClass], default: false
-      # whether or not to add the repository as a source repo, too
-      property :deb_src, [TrueClass, FalseClass], default: false
-      property :keyserver, [String, nil, FalseClass], default: "keyserver.ubuntu.com"
-      property :key, [String, Array, nil, FalseClass], default: lazy { [] }, coerce: proc { |x| x ? Array(x) : x }
-      property :key_proxy, [String, nil, FalseClass]
-
-      property :cookbook, [String, nil, FalseClass], desired_state: false
-      property :cache_rebuild, [TrueClass, FalseClass], default: true, desired_state: false
+      property :uri, String,
+               description: "The base of the Debian distribution."
+
+      property :distribution, [ String, nil, FalseClass ],
+               description: "Usually a distribution’s codename, such as trusty, xenial or bionic. Default value: the codename of the node’s distro.",
+               default: lazy { node["lsb"]["codename"] }
+
+      property :components, Array,
+               description: "Package groupings, such as ‘main’ and ‘stable’.",
+               default: lazy { [] }
+
+      property :arch, [String, nil, FalseClass],
+               description: "Constrain packages to a particular CPU architecture such as 'i386' or 'amd64'."
+
+      property :trusted, [TrueClass, FalseClass],
+               description: "Determines whether you should treat all packages from this repository as authenticated regardless of signature.",
+               default: false
+
+      property :deb_src, [TrueClass, FalseClass],
+               description: "Determines whether or not to add the repository as a source repo as well.",
+               default: false
+
+      property :keyserver, [String, nil, FalseClass],
+               description: "The GPG keyserver where the key for the repo should be retrieved.",
+               default: "keyserver.ubuntu.com"
+
+      property :key, [String, Array, nil, FalseClass],
+               description: "If a keyserver is provided, this is assumed to be the fingerprint; otherwise it can be either the URI of GPG key for the repo, or a cookbook_file.",
+               default: lazy { [] }, coerce: proc { |x| x ? Array(x) : x }
+
+      property :key_proxy, [String, nil, FalseClass],
+               description: "If set, a specified proxy is passed to GPG via http-proxy=."
+
+      property :cookbook, [String, nil, FalseClass],
+               description: "If key should be a cookbook_file, specify a cookbook where the key is located for files/default. Default value is nil, so it will use the cookbook where the resource is used.",
+               desired_state: false
+
+      property :cache_rebuild, [TrueClass, FalseClass],
+               description: "Determines whether to rebuild the APT package cache.",
+               default: true, desired_state: false
 
       default_action :add
       allowed_actions :add, :remove
diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index a302ff252b..04a9407813 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -29,7 +29,9 @@ class Chef
 
       # allow bare apt_update with no name
       property :name, String, default: ""
-      property :frequency, Integer, default: 86_400
+      property :frequency, Integer,
+                description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the :periodic action is specified.",
+                default: 86_400
 
       default_action :periodic
       allowed_actions :update, :periodic
diff --git a/lib/chef/resource/bash.rb b/lib/chef/resource/bash.rb
index 03fdd0e396..22a84f4134 100644
--- a/lib/chef/resource/bash.rb
+++ b/lib/chef/resource/bash.rb
@@ -22,12 +22,7 @@ require "chef/provider/script"
 class Chef
   class Resource
     class Bash < Chef::Resource::Script
-      description "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."
+      description "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."
 
       def initialize(name, run_context = nil)
         super
diff --git a/lib/chef/resource/batch.rb b/lib/chef/resource/batch.rb
index 4e6d67aa2d..e3bff8145c 100644
--- a/lib/chef/resource/batch.rb
+++ b/lib/chef/resource/batch.rb
@@ -23,13 +23,7 @@ class Chef
     class Batch < Chef::Resource::WindowsScript
       provides :batch
 
-      description "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."
+      description "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."
 
       def initialize(name, run_context = nil)
         super(name, run_context, nil, "cmd.exe")
diff --git a/lib/chef/resource/bff_package.rb b/lib/chef/resource/bff_package.rb
index 62838cfd60..8750cb0b2b 100644
--- a/lib/chef/resource/bff_package.rb
+++ b/lib/chef/resource/bff_package.rb
@@ -24,10 +24,7 @@ class Chef
       resource_name :bff_package
       provides :bff_package
 
-      description "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."
+      description "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."
       introduced "12.0"
     end
   end
diff --git a/lib/chef/resource/breakpoint.rb b/lib/chef/resource/breakpoint.rb
index 1ccc4311b3..8af3edbe22 100644
--- a/lib/chef/resource/breakpoint.rb
+++ b/lib/chef/resource/breakpoint.rb
@@ -24,13 +24,7 @@ class Chef
       provides :breakpoint
       resource_name :breakpoint
 
-      description "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."
+      description "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."
       introduced "12.0"
 
       default_action :break
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 155de864f9..7c549fb236 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -22,7 +22,7 @@ class Chef
       resource_name :build_essential
       provides(:build_essential) { true }
 
-      description "Use the build_essential resource to install packages required for compiling C software from source"
+      description "Use the build_essential resource to install packages required for compiling C software from source."
       introduced "14.0"
 
       # this allows us to use build_essential without setting a name
diff --git a/lib/chef/resource/cab_package.rb b/lib/chef/resource/cab_package.rb
index 7c5da016c9..a90ddc6891 100644
--- a/lib/chef/resource/cab_package.rb
+++ b/lib/chef/resource/cab_package.rb
@@ -27,13 +27,13 @@ class Chef
       resource_name :cab_package
       provides :cab_package
 
-      description "Use the cab_package resource to install or remove Microsoft Windows"\
-                  " cabinet (.cab) packages."
+      description "Use the cab_package resource to install or remove Microsoft Windows cabinet (.cab) packages."
       introduced "12.15"
 
       allowed_actions :install, :remove
 
       property  :source, String,
+                description: "The local file path or URL for the CAB package.",
                 coerce: (proc do |s|
                   unless s.nil?
                     uri_scheme?(s) ? s : Chef::Util::PathHelper.canonical_path(s, false)
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index cf8e67d708..5f63f4b5b5 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -24,18 +24,26 @@ class Chef
       resource_name :chocolatey_package
       provides :chocolatey_package
 
-      description "Use the chocolatey_package resource to manage packages using Chocolatey"\
-                  " on the Microsoft Windows platform."
+      description "Use the chocolatey_package resource to manage packages using Chocolatey on the Microsoft Windows platform."
       introduced "12.7"
 
       allowed_actions :install, :upgrade, :remove, :purge, :reconfig
 
       # windows can't take Array options yet
-      property :options, String
+      property :options, String,
+                description: "One (or more) additional options that are passed to the command."
 
-      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
+      property :package_name, [String, Array],
+                description: "The name of the package. Default value: the name of the resource block See “Syntax” section above for more information.",
+                coerce: proc { |x| [x].flatten }
+
+      property :version, [String, Array],
+                description: "The version of a package to be installed or upgraded.",
+                coerce: proc { |x| [x].flatten }
+
+      property :returns, [Integer, Array],
+                description: "The exit code(s) returned a chocolatey package that indicate success.",
+                default: [ 0 ], desired_state: false
     end
   end
 end
diff --git a/lib/chef/resource/cookbook_file.rb b/lib/chef/resource/cookbook_file.rb
index 593cb5e137..0caa9d0553 100644
--- a/lib/chef/resource/cookbook_file.rb
+++ b/lib/chef/resource/cookbook_file.rb
@@ -29,20 +29,14 @@ class Chef
 
       resource_name :cookbook_file
 
-      description "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.\n\n"\
-                  "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."
+      description "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.\n\nDuring 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."
 
-      property :source, [ String, Array ], default: lazy { ::File.basename(name) }
-      property :cookbook, String
+      property :source, [ String, Array ],
+                description: "The name of the file in COOKBOOK_NAME/files/default or the path to a file located in COOKBOOK_NAME/files. The path must include the file name and its extension. This can be used to distribute specific files depending upon the platform used.",
+                default: lazy { ::File.basename(name) }
+
+      property :cookbook, String,
+                description: "The cookbook in which a file is located (if it is not located in the current cookbook)."
 
       default_action :create
     end
diff --git a/lib/chef/resource/cron.rb b/lib/chef/resource/cron.rb
index 3c11d83d9a..ea6d692709 100644
--- a/lib/chef/resource/cron.rb
+++ b/lib/chef/resource/cron.rb
@@ -26,9 +26,7 @@ class Chef
       resource_name :cron
       provides :cron
 
-      description "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."
+      description "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."
 
       state_attrs :minute, :hour, :day, :month, :weekday, :user