Add additional property descriptions using those on the docs site

Slowly backporting stuff from the docs site into Chef so we can auto-generate our docs

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

5 files changed, 305 insertions, 109 deletions

diff --git a/lib/chef/resource/package.rb b/lib/chef/resource/package.rb
index 8362dde47e..bbad5f7696 100644
--- a/lib/chef/resource/package.rb
+++ b/lib/chef/resource/package.rb
@@ -41,14 +41,32 @@ class Chef
         super
       end
 
-      property :package_name, [ String, Array ], identity: true
-
-      property :version, [ String, Array ]
-      property :options, [ String, Array ], coerce: proc { |x| x.is_a?(String) ? x.shellsplit : x }
-      property :response_file, String, desired_state: false
-      property :response_file_variables, Hash, default: lazy { {} }, desired_state: false
-      property :source, String, desired_state: false
-      property :timeout, [ String, Integer ], desired_state: false
+      property :package_name, [ String, Array ],
+               description: "The name of the package. Defaults to the name of the resourse block unless specified.",
+               identity: true
+
+      property :version, [ String, Array ],
+               description: "The version of a package to be installed or upgraded."
+
+      property :options, [ String, Array ],
+               description: "One (or more) additional command options that are passed to the command.",
+               coerce: proc { |x| x.is_a?(String) ? x.shellsplit : x }
+
+      property :response_file, String,
+               description: "",
+               desired_state: false
+
+      property :response_file_variables, Hash,
+               description: "",
+               default: lazy { {} }, desired_state: false
+
+      property :source, String,
+               description: "The direct path to a the package on the host.",
+               desired_state: false
+
+      property :timeout, [ String, Integer ],
+               description: "The amount of time (in seconds) to wait before timing out.",
+               desired_state: false
 
     end
   end
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index 3dea434a33..9af20f8af0 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -31,41 +31,87 @@ class Chef
       allowed_actions :create, :delete, :run, :end, :enable, :disable, :change
       default_action :create
 
-      property :task_name, String, regex: [/\A[^\/\:\*\?\<\>\|]+\z/], name_property: true
-      property :command, String
-      property :cwd, String
-      property :user, String, default: "SYSTEM"
-      property :password, String
-      property :run_level, equal_to: [:highest, :limited], default: :limited
-      property :force, [TrueClass, FalseClass], default: false
-      property :interactive_enabled, [TrueClass, FalseClass], default: false
-      property :frequency_modifier, [Integer, String], default: 1
-      property :frequency, equal_to: [:minute,
-                                      :hourly,
-                                      :daily,
-                                      :weekly,
-                                      :monthly,
-                                      :once,
-                                      :on_logon,
-                                      :onstart,
-                                      :on_idle,
-                                      :none]
-      property :start_day, String
-      property :start_time, String
-      property :day, [String, Integer]
-      property :months, String
-      property :idle_time, Integer
-      property :random_delay, [String, Integer]
-      property :execution_time_limit, [String, Integer], default: "PT72H" # 72 hours in ISO8601 duration format
-      property :minutes_duration, [String, Integer]
-      property :minutes_interval, [String, Integer]
-      property :priority, Integer, description: "Use to set Priority Levels range from 0 to 10.", default: 7,
-               callbacks: { "should be in range of 0 to 10" => proc { |v| v >= 0 && v <= 10 } }
-      property :disallow_start_if_on_batteries, [TrueClass, FalseClass], default: false,
-               introduced: "14.4",
+      property :task_name, String, regex: [/\A[^\/\:\*\?\<\>\|]+\z/],
+               description: "The task name, such as 'Task Name' or '/Task Name'",
+               name_property: true
+
+      property :command, String,
+               description: ""
+
+      property :cwd, String,
+               description: "The directory the task will be run from."
+
+      property :user, String,
+               description: "The user to run the task as.",
+               default: "SYSTEM"
+
+      property :password, String,
+               description: "The user’s password. The user property must be set if using this property."
+
+      property :run_level, Symbol, equal_to: [:highest, :limited],
+               description: "Run with ':limited' or ':highest' privileges.",
+               default: :limited
+
+      property :force, [TrueClass, FalseClass],
+               description: "When used with create, will update the task.",
+               default: false
+
+      property :interactive_enabled, [TrueClass, FalseClass],
+               description: "", default: false
+
+      property :frequency_modifier, [Integer, String],
+               default: 1
+
+      property :frequency, Symbol, equal_to: [:minute,
+                                              :hourly,
+                                              :daily,
+                                              :weekly,
+                                              :monthly,
+                                              :once,
+                                              :on_logon,
+                                              :onstart,
+                                              :on_idle,
+                                              :none],
+               description: "The frequency with which to run the task."
+
+      property :start_day, String,
+               description: "Specifies the first date on which the task runs in MM/DD/YYYY format."
+
+      property :start_time, String,
+               description: "Specifies the start time to run the task, in HH:mm format."
+
+      property :day, [String, Integer],
+               description: "The day(s) on which the task runs."
+
+      property :months, String,
+               description: "The Months of the year on which the task runs, such as: 'JAN, FEB' or '\*'. Multiple months should be comma delimited. e.g. 'Jan, Feb, Mar, Dec'."
+
+      property :idle_time, Integer,
+               description: "For :on_idle frequency, the time (in minutes) without user activity that must pass to trigger the task, from 1 - 999."
+
+      property :random_delay, [String, Integer],
+               description: ""
+
+      property :execution_time_limit, [String, Integer],
+               description: "The maximum time (in seconds) the task will run.",
+               default: "PT72H" # 72 hours in ISO8601 duration format
+
+      property :minutes_duration, [String, Integer],
+               description: ""
+
+      property :minutes_interval, [String, Integer],
+               description: ""
+
+      property :priority, Integer,
+               description: "Use to set Priority Levels range from 0 to 10.",
+               default: 7, callbacks: { "should be in range of 0 to 10" => proc { |v| v >= 0 && v <= 10 } }
+
+      property :disallow_start_if_on_batteries, [TrueClass, FalseClass],
+               introduced: "14.4", default: false,
                description: "Disallow start of the task if the system is running on battery power."
-      property :stop_if_going_on_batteries, [TrueClass, FalseClass], default: false,
-               introduced: "14.4",
+
+      property :stop_if_going_on_batteries, [TrueClass, FalseClass],
+               introduced: "14.4", default: false,
                description: "Scheduled task option when system is switching on battery."
 
       attr_accessor :exists, :task, :command_arguments
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 8d88f12ed0..ba7fb53ad1 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -32,54 +32,142 @@ class Chef
 
       # http://linux.die.net/man/5/yum.conf as well as
       # http://dnf.readthedocs.io/en/latest/conf_ref.html
-      property :baseurl, [String, Array]
-      property :clean_headers, [TrueClass, FalseClass], default: false # deprecated
-      property :clean_metadata, [TrueClass, FalseClass], default: true
-      property :cost, String, regex: /^\d+$/
-      property :description, String, default: "Yum Repository"
-      property :enabled, [TrueClass, FalseClass], default: true
-      property :enablegroups, [TrueClass, FalseClass]
-      property :exclude, String
-      property :failovermethod, String, equal_to: %w{priority roundrobin}
-      property :fastestmirror_enabled, [TrueClass, FalseClass]
-      property :gpgcheck, [TrueClass, FalseClass], default: true
-      property :gpgkey, [String, Array]
-      property :http_caching, String, equal_to: %w{packages all none}
-      property :include_config, String
-      property :includepkgs, String
-      property :keepalive, [TrueClass, FalseClass]
-      property :make_cache, [TrueClass, FalseClass], default: true
-      property :max_retries, [String, Integer]
-      property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/]
-      property :metalink, String
-      property :mirror_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/]
-      property :mirrorexpire, String
-      property :mirrorlist_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/]
-      property :mirrorlist, String
-      property :mode, default: "0644"
-      property :options, Hash
-      property :password, String
-      property :priority, String, regex: /^(\d?[1-9]|[0-9][0-9])$/
-      property :proxy_password, String
-      property :proxy_username, String
-      property :proxy, String
-      property :repo_gpgcheck, [TrueClass, FalseClass]
-      property :report_instanceid, [TrueClass, FalseClass]
-
-      property :repositoryid, String,
-               regex: [/^[^\/]+$/],
+      property :baseurl, [String, Array],
+               description: "URL to the directory where the Yum repository's 'repodata' directory lives. Can be an http://, https:// or a ftp:// URL. You can specify multiple URLs in one baseurl statement."
+
+      property :clean_headers, [TrueClass, FalseClass],
+               description: "Specifies whether you want to purge the package data files that are downloaded from a Yum repository and held in a cache directory.",
+               deprecated: true,
+               default: false # deprecated
+
+      property :clean_metadata, [TrueClass, FalseClass],
+               description: "Specifies whether you want to purge all of the packages downloaded from a Yum repository and held in a cache directory.",
+               default: true
+
+      property :cost, String, regex: /^\d+$/,
+               description: "Relative cost of accessing this repository. Useful for weighing one repo's packages as greater/less than any other."
+
+      property :description, String,
+               description: "Descriptive name for the repository channel and maps to the 'name' parameter in a repository .conf.",
+               default: "Yum Repository"
+
+      property :enabled, [TrueClass, FalseClass],
+               description: "Specifies whether or not Yum should use this repository.",
+               default: true
+
+      property :enablegroups, [TrueClass, FalseClass],
+               description: "Specifies whether Yum will allow the use of package groups for this repository."
+
+      property :exclude, String,
+               description: "List of packages to exclude from updates or installs. This should be a space separated list. Shell globs using wildcards (eg. * and ?) are allowed."
+
+      property :failovermethod, String,
+               description: "Method to determine how to switch to a new server if the current one fails, which can either be ``roundrobin`` or ``priority``. ``roundrobin`` randomly selects a URL out of the list of URLs to start with and proceeds through each of them as it encounters a failure contacting the host. ``priority`` starts from the first ``baseurl`` listed and reads through them sequentially.",
+               equal_to: %w{priority roundrobin}
+
+      property :fastestmirror_enabled, [TrueClass, FalseClass],
+               description: "Specifies whether to use the fastest mirror from a repository configuration when more than one mirror is listed in that configuration."
+
+      property :gpgcheck, [TrueClass, FalseClass],
+               description: "Specifies whether or not Yum should perform a GPG signature check on the packages received from a repository.",
+               default: true
+
+      property :gpgkey, [String, Array],
+               description: "URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed."
+
+      property :http_caching, String, equal_to: %w{packages all none},
+               description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)"
+
+      property :include_config, String,
+               description: "An external configuration file using the format 'url://to/some/location'."
+
+      property :includepkgs, String,
+               description: "Inverse of exclude property. This is a list of packages you want to use from a repository. If this option lists only one package then that is all Yum will ever see from the repository."
+
+      property :keepalive, [TrueClass, FalseClass],
+               description: "Determines whether or not HTTP/1.1 ``keep-alive`` should be used with this repository."
+
+      property :make_cache, [TrueClass, FalseClass],
+               description: "Determines whether package files downloaded by Yum stay in cache directories. By using cached data, you can carry out certain operations without a network connection.",
+               default: true
+
+      property :max_retries, [String, Integer],
+               description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to '0' makes Yum try forever."
+
+      property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/],
+               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word ``never``, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file."
+
+      property :metalink, String,
+               description: "Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl."
+
+      property :mirror_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/],
+               description: "Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option."
+
+      property :mirrorlist_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/],
+               description: "Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist."
+
+      property :mirrorlist, String,
+               description: "URL to a file containing a list of baseurls. This can be used instead of or with the baseurl option. Substitution variables, described below, can be used with this option."
+
+      property :mode, [String, Integer],
+               description: "Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to '600', normal users will not be able to use Yum search, Yum info, etc.",
+               default: "0644"
+
+      property :options, Hash,
+               description: "Specifies the repository options."
+
+      property :password, String,
+               description: "Password to use with the username for basic authentication."
+
+      property :priority, String, regex: /^(\d?[1-9]|[0-9][0-9])$/,
+               description: "Assigns a priority to a repository where the priority value is between '1' and '99' inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority."
+
+      property :proxy_password, String,
+               description: "Password for this proxy."
+
+      property :proxy_username, String,
+               description: "Username to use for proxy."
+
+      property :proxy, String,
+               description: "URL to the proxy server that Yum should use."
+
+      property :repo_gpgcheck, [TrueClass, FalseClass],
+               description: "Determines whether or not Yum should perform a GPG signature check on the repodata from this repository."
+
+      property :report_instanceid, [TrueClass, FalseClass],
+               description: "Determines whether to report the instance ID when using Amazon Linux AMIs and repositories."
+
+      property :repositoryid, String, regex: [/^[^\/]+$/],
+               description: "Specifies a unique name for each repository, one word. Defaults to name attribute.",
                validation_message: "repositoryid property cannot contain a forward slash '/'",
                name_property: true
 
-      property :skip_if_unavailable, [TrueClass, FalseClass]
-      property :source, String
-      property :sslcacert, String
-      property :sslclientcert, String
-      property :sslclientkey, String
-      property :sslverify, [TrueClass, FalseClass]
-      property :throttle, [String, Integer]
-      property :timeout, String, regex: /^\d+$/
-      property :username, String
+      property :skip_if_unavailable, [TrueClass, FalseClass],
+               description: ""
+
+      property :source, String,
+               description: "Use a custom template source instead of the default one."
+
+      property :sslcacert, String,
+               description: "Path to the directory containing the databases of the certificate authorities Yum should use to verify SSL certificates."
+
+      property :sslclientcert, String,
+               description: "Path to the SSL client certificate Yum should use to connect to repos/remote sites."
+
+      property :sslclientkey, String,
+               description: "Path to the SSL client key Yum should use to connect to repos/remote sites."
+
+      property :sslverify, [TrueClass, FalseClass],
+               description: "Determines whether Yum will verify SSL certificates/hosts."
+
+      property :throttle, [String, Integer],
+               description: "Enable bandwidth throttling for downloads."
+
+      property :timeout, String, regex: /^\d+$/,
+               description: "Number of seconds to wait for a connection before timing out. Defaults to 30 seconds. This may be too short of a time for extremely overloaded sites."
+
+      property :username, String,
+               description: "Username to use for basic authentication to a repository."
 
       default_action :create
       allowed_actions :create, :remove, :makecache, :add, :delete
@@ -87,6 +175,7 @@ class Chef
       # provide compatibility with the yum cookbook < 3.0 properties
       alias_method :url, :baseurl
       alias_method :keyurl, :gpgkey
+      alias_method :mirrorexpire, :mirror_expire
     end
   end
 end
diff --git a/lib/chef/resource/zypper_package.rb b/lib/chef/resource/zypper_package.rb
index 23b8779f25..920a803b14 100644
--- a/lib/chef/resource/zypper_package.rb
+++ b/lib/chef/resource/zypper_package.rb
@@ -28,8 +28,13 @@ class Chef
       description "Use the zypper_package resource to install, upgrade, and remove"\
                   " packages with Zypper for the SUSE Enterprise and OpenSUSE platforms."
 
-      property :gpg_check, [ TrueClass, FalseClass ], default: lazy { Chef::Config[:zypper_check_gpg] }
-      property :allow_downgrade, [ TrueClass, FalseClass ], default: false
+      property :gpg_check, [ TrueClass, FalseClass ],
+               description: "Verify the package's GPG signature",
+               default: lazy { Chef::Config[:zypper_check_gpg] }
+
+      property :allow_downgrade, [ TrueClass, FalseClass ],
+               description: "",
+               default: false
     end
   end
 end
diff --git a/lib/chef/resource/zypper_repository.rb b/lib/chef/resource/zypper_repository.rb
index 018f03e6b0..b3e1db6b83 100644
--- a/lib/chef/resource/zypper_repository.rb
+++ b/lib/chef/resource/zypper_repository.rb
@@ -25,33 +25,71 @@ class Chef
       provides(:zypper_repository) { true }
       provides(:zypper_repo) { true }
 
-      description "Use the zypper_repository resource to create 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."
+      description "Use the zypper_repository resource to create 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."
       introduced "13.3"
 
       property :repo_name, String,
                regex: [/^[^\/]+$/],
+               description: "Specifies the repository name, if it differs from the resource name.",
                validation_message: "repo_name property cannot contain a forward slash '/'",
                name_property: true
 
-      property :description, String
-      property :type, String, default: "NONE"
-      property :enabled, [TrueClass, FalseClass], default: true
-      property :autorefresh, [TrueClass, FalseClass], default: true
-      property :gpgcheck, [TrueClass, FalseClass], default: true
-      property :gpgkey, String
-      property :baseurl, String
-      property :mirrorlist, String
-      property :path, String
-      property :priority, Integer, default: 99
-      property :keeppackages, [TrueClass, FalseClass], default: false
-      property :mode, default: "0644"
-      property :refresh_cache, [TrueClass, FalseClass], default: true
-      property :source, String
-      property :cookbook, String
-      property :gpgautoimportkeys, [TrueClass, FalseClass], default: true
+      property :description, String,
+               description: "The description of the repository that will be shown by the 'zypper repos' command."
+
+      property :type, String,
+               description: "Specifies the repository type.",
+               default: "NONE"
+
+      property :enabled, [TrueClass, FalseClass],
+               description: "Determines whether or not the repository should be enabled.",
+               default: true
+
+      property :autorefresh, [TrueClass, FalseClass],
+               description: "Determines whether or not the repository should be refreshed automatically.",
+               default: true
+
+      property :gpgcheck, [TrueClass, FalseClass],
+               description: "Determines whether or not to perform a GPG signature check on the repository.",
+               default: true
+
+      property :gpgkey, String,
+               description: "The location of the repository key to be imported."
+
+      property :baseurl, String,
+               description: "The base URL for the Zypper repository, such as 'http://download.opensuse.org'."
+
+      property :mirrorlist, String,
+               description: "The URL of the mirror list that will be used."
+
+      property :path, String,
+               description: "The relative path from the repository's base URL."
+
+      property :priority, Integer,
+               description: "Determines the priority of the Zypper repository. ",
+               default: 99
+
+      property :keeppackages, [TrueClass, FalseClass],
+               description: "Determines whether or not packages should be saved.",
+               default: false
+
+      property :mode, [String, Integer],
+               description: "The file mode of the repository file.",
+               default: "0644"
+
+      property :refresh_cache, [TrueClass, FalseClass],
+               description: "Determines whether or not the package cache should be refreshed.",
+               default: true
+
+      property :source, String,
+               description: "The name of the template for the repository file. Only necessary if you're not using the built in template."
+
+      property :cookbook, String,
+               description: "The cookbook to source the repository template file from. Only necessary if you're not using the built in template."
+
+      property :gpgautoimportkeys, [TrueClass, FalseClass],
+               description: "Automatically import the specified key when setting up the repository.",
+               default: true
 
       default_action :create
       allowed_actions :create, :remove, :add, :refresh