Add descriptions to more resources

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

6 files changed, 68 insertions, 40 deletions

diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 236e9477e0..26223aa4a1 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 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..d54ffff1de 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -29,7 +29,8 @@ 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/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..f398165064 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