Move more documentation into the codedocs_updates

Get closer to generating resources from the codebase.

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

9 files changed, 120 insertions, 29 deletions

diff --git a/lib/chef/provider/cron.rb b/lib/chef/provider/cron.rb
index 694f7ba4b8..29ecd4dd2a 100644
--- a/lib/chef/provider/cron.rb
+++ b/lib/chef/provider/cron.rb
@@ -92,7 +92,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Create an entry in a cron table file (crontab). If an entry already exists (but does not match), update that entry to match." do
         crontab = ""
         newcron = ""
         cron_found = false
@@ -149,7 +149,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Delete an entry from a cron table file (crontab)." do
         if @cron_exists
           crontab = ""
           cron_found = false
diff --git a/lib/chef/provider/directory.rb b/lib/chef/provider/directory.rb
index 6a20556ccd..3e4107980c 100644
--- a/lib/chef/provider/directory.rb
+++ b/lib/chef/provider/directory.rb
@@ -121,7 +121,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Create a directory. If a directory already exists (but does not match), update that directory to match." do
         unless ::File.exist?(new_resource.path)
           converge_by("create new directory #{new_resource.path}") do
             if new_resource.recursive == true
@@ -137,7 +137,7 @@ class Chef
         load_resource_attributes_from_file(new_resource) unless Chef::Config[:why_run]
       end
 
-      action :delete do
+      action :delete, description: "Delete a directory." do
         if ::File.exist?(new_resource.path)
           converge_by("delete existing directory #{new_resource.path}") do
             if new_resource.recursive == true
diff --git a/lib/chef/provider/ifconfig.rb b/lib/chef/provider/ifconfig.rb
index 69d95b260c..63aa126c2e 100644
--- a/lib/chef/provider/ifconfig.rb
+++ b/lib/chef/provider/ifconfig.rb
@@ -168,7 +168,7 @@ class Chef
         end
       end
 
-      action :add do
+      action :add, description: "Run ifconfig to configure a network interface and (on some platforms) write a configuration file for that network interface." do
         # check to see if load_current_resource found interface in ifconfig
         unless current_resource.inet_addr
           unless new_resource.device == loopback_device
@@ -183,7 +183,7 @@ class Chef
         generate_config
       end
 
-      action :enable do
+      action :enable, description: "Run ifconfig to enable a network interface." do
         # check to see if load_current_resource found ifconfig
         # enables, but does not manage config files
         return if current_resource.inet_addr
@@ -196,7 +196,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Run ifconfig to disable a network interface and (on some platforms) delete that network interface’s configuration file." do
         # check to see if load_current_resource found the interface
         if current_resource.device
           command = delete_command
@@ -210,7 +210,7 @@ class Chef
         delete_config
       end
 
-      action :disable do
+      action :disable, description: "Run ifconfig to disable a network interface." do
         # check to see if load_current_resource found the interface
         # disables, but leaves config files in place.
         if current_resource.device
diff --git a/lib/chef/provider/package.rb b/lib/chef/provider/package.rb
index 82d7ed00cf..a1cb4ff1b4 100644
--- a/lib/chef/provider/package.rb
+++ b/lib/chef/provider/package.rb
@@ -107,7 +107,7 @@ class Chef
         end
       end
 
-      action :install do
+      action :install, description: "Install a package. If a version is specified, install the specified version of the package." do
         unless target_version_array.any?
           logger.debug("#{new_resource} is already installed - nothing to do")
           return
@@ -136,7 +136,7 @@ class Chef
 
       private :install_description
 
-      action :upgrade do
+      action :upgrade, description: "Install a package and/or ensure that a package is the latest version." do
         unless target_version_array.any?
           logger.debug("#{new_resource} no versions to upgrade - nothing to do")
           return
@@ -167,7 +167,7 @@ class Chef
 
       private :upgrade_description
 
-      action :remove do
+      action :remove, description: "Remove a package." do
         if removing_package?
           description = new_resource.version ? "version #{new_resource.version} of " : ""
           converge_by("remove #{description}package #{current_resource.package_name}") do
@@ -202,7 +202,7 @@ class Chef
         end
       end
 
-      action :purge do
+      action :purge, description: "Purge a package. This action typically removes the configuration files as well as the package." do
         if removing_package?
           description = new_resource.version ? "version #{new_resource.version} of" : ""
           converge_by("purge #{description} package #{current_resource.package_name}") do
diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 331d411373..448ebce4e5 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -43,7 +43,7 @@ class Chef
       **Install multiple packages at once**:
 
       ```ruby
-      apt_package %(package1 package2 package3)
+      apt_package %w(package1 package2 package3)
       ```
 
       **Install without using recommend packages as a dependency**:
@@ -55,7 +55,7 @@ class Chef
       ```
       DOC
 
-      description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
+      description "Use the **apt_package** resource to manage packages on Debian, Ubuntu, and other platforms that use the APT package system."
 
       property :default_release, String,
         description: "The default release. For example: `stable`.",
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index e0568e586a..f7f221c025 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :chocolatey_package
 
-      description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [Chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list."
+      description "Use the **chocolatey_package** resource to manage packages using the Chocolatey package manager on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list. Warning: The **chocolatey_package** resource must be specified as `chocolatey_package` and cannot be shortened to `package` in a recipe."
       introduced "12.7"
       examples <<~DOC
         **Install a Chocolatey package**:
@@ -73,9 +73,9 @@ class Chef
         coerce: proc { |x| [x].flatten }
 
       # In the choco if we have the feature useEnhancedExitCodes turned on, then choco will provide enhanced exit codes(2: no results).
-      # Choco exit codes https://chocolatey.org/docs/commandsinfo#exit-codes
+      # Choco exit codes https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes
       property :returns, [Integer, Array],
-        description: "The exit code(s) returned a chocolatey package that indicate success.",
+        description: "The exit code(s) returned by the `choco` command that indicate a successful action. See [Chocolatey Exit Codes](https://docs.chocolatey.org/en-us/choco/commands/info#exit-codes) for a complete list of exit codes used by Chocolatey.",
         default: [ 0, 2 ], desired_state: false,
         introduced: "12.18"
     end
diff --git a/lib/chef/resource/cron/cron.rb b/lib/chef/resource/cron/cron.rb
index 31d6efcfde..1565cf9025 100644
--- a/lib/chef/resource/cron/cron.rb
+++ b/lib/chef/resource/cron/cron.rb
@@ -20,6 +20,7 @@
 require_relative "../../resource"
 require_relative "../helpers/cron_validations"
 require_relative "../../provider/cron" # do not remove. we actually need this below
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -30,7 +31,81 @@ class Chef
 
       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. Warning: The cron resource should only be used to modify an entry in a crontab file. The `cron_d` resource directly manages `cron.d` files. This resource ships in #{ChefUtils::Dist::Infra::PRODUCT} 14.4 or later and can also be found in the [cron](https://github.com/chef-cookbooks/cron) cookbook) for previous #{ChefUtils::Dist::Infra::PRODUCT} releases."
+
+      examples <<~'DOC'
+      **Run a program at a specified interval**
+
+      ```ruby
+      cron 'noop' do
+        hour '5'
+        minute '0'
+        command '/bin/true'
+      end
+      ```
+
+      **Run an entry if a folder exists**
+
+      ```ruby
+      cron 'ganglia_tomcat_thread_max' do
+        command "/usr/bin/gmetric
+          -n 'tomcat threads max'
+          -t uint32
+          -v '/usr/local/bin/tomcat-stat --thread-max'"
+        only_if { ::File.exist?('/home/jboss') }
+      end
+      ```
+
+      **Run every Saturday, 8:00 AM**
+
+      The following example shows a schedule that will run every hour at 8:00 each Saturday morning, and will then send an email to “admin@example.com” after each run.
+
+      ```ruby
+      cron 'name_of_cron_entry' do
+        minute '0'
+        hour '8'
+        weekday '6'
+        mailto 'admin@example.com'
+        action :create
+      end
+      ```
+
+      **Run once a week**
+
+      ```ruby
+      cron 'cookbooks_report' do
+        minute '0'
+        hour '0'
+        weekday '1'
+        user 'chefio'
+        mailto 'sysadmin@example.com'
+        home '/srv/supermarket/shared/system'
+        command %W{
+          cd /srv/supermarket/current &&
+          env RUBYLIB="/srv/supermarket/current/lib"
+          RAILS_ASSET_ID=`git rev-parse HEAD` RAILS_ENV="#{rails_env}"
+          bundle exec rake cookbooks_report
+        }.join(' ')
+        action :create
+      end
+      ```
+
+      **Run only in November**
+
+      The following example shows a schedule that will run at 8:00 PM, every weekday (Monday through Friday), but only in November:
+
+      ```ruby
+      cron 'name_of_cron_entry' do
+        minute '0'
+        hour '20'
+        day '*'
+        month '11'
+        weekday '1-5'
+        action :create
+      end
+      ```
+      DOC
+
 
       state_attrs :minute, :hour, :day, :month, :weekday, :user
 
diff --git a/lib/chef/resource/cron/cron_d.rb b/lib/chef/resource/cron/cron_d.rb
index 2806f55415..dffe46bcec 100644
--- a/lib/chef/resource/cron/cron_d.rb
+++ b/lib/chef/resource/cron/cron_d.rb
@@ -18,6 +18,7 @@
 require_relative "../../resource"
 require_relative "../helpers/cron_validations"
 require "shellwords" unless defined?(Shellwords)
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -29,7 +30,7 @@ class Chef
       provides :cron_d
 
       introduced "14.4"
-      description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
+      description "Use the **cron_d** resource to manage cron job files in the `/etc/cron.d` directory. Warning: #{ChefUtils::Dist::Infra::PRODUCT} also ships with the **cron** resource for managing the monolithic `/etc/crontab` file on platforms that lack cron.d support. See the [cron resource](/resources/cron/) for information on using that resource."
       examples <<~DOC
         **Run a program on the fifth hour of the day**
 
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index b1154a1f08..224e59204b 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -149,7 +149,6 @@ class Chef
       DOC
 
       allowed_actions :create, :delete, :run, :end, :enable, :disable, :change
-      default_action :create
 
       property :task_name, String, regex: [%r{\A[^/\:\*\?\<\>\|]+\z}],
         description: "An optional property to set the task name if it differs from the resource block's name. Example: `Task Name` or `/Task Name`",
@@ -182,10 +181,19 @@ class Chef
         default: false
 
       property :frequency_modifier, [Integer, String],
-        default: 1
+        default: 1,
+        description: <<~DOCS
+          * For frequency `:minute` valid values are 1 to 1439
+          * For frequency `:hourly` valid values are 1 to 23
+          * For frequency `:daily` valid values are 1 to 365
+          * For frequency `:weekly` valid values are 1 to 52
+          * For frequency `:monthly` valid values are `('FIRST', 'SECOND', 'THIRD', 'FOURTH', 'LAST')` OR `1-12`.
+            * e.g. If user want to run the task on `second week of the month` use `frequency_modifier` value as `SECOND`. Multiple values for weeks of the month should be comma separated e.g. `"FIRST, THIRD, LAST"`.
+            * To run task every (n) months use values 1 to 12.
+        DOCS
 
       property :frequency, Symbol, equal_to: %i{minute hourly daily weekly monthly once on_logon onstart on_idle none},
-        description: "The frequency with which to run the task."
+        description: "The frequency with which to run the task. Note: This property is required in Chef Infra Client 14.1 or later. Note: The `:once` value requires the `start_time` property to be set."
 
       property :start_day, String,
         description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.",
@@ -195,7 +203,14 @@ class Chef
         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."
+        description:  <<~DOCS
+        The day(s) on which the task runs.
+          * Use this property when setting `frequency` to `:monthly` or `:weekly`.
+          * Valid values with frequency `:weekly` are `MON`-`SUN` or `*`.
+          * Valid values with frequency `:monthly` are `1-31`, `MON`-`SUN`, and `LASTDAY`.
+          * Use `MON`-`SUN` or `LASTDAY` if you are setting `frequency_modifier` as "FIRST, SECOND, THIRD etc." else use 1-31.
+          * Multiple days should be comma separated. e.g `1, 2, 3` or `MON, WED, FRI`.
+        DOCS
 
       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`."
@@ -961,7 +976,7 @@ class Chef
         end
       end
 
-      action :create do
+      action :create, description: "Creates a scheduled task, or updates an existing task if any property has changed." do
         set_command_and_arguments if new_resource.command
 
         if current_resource.exists
@@ -998,7 +1013,7 @@ class Chef
         end
       end
 
-      action :run do
+      action :run, description: "Runs a scheduled task." do
         if current_resource.exists
           logger.trace "#{new_resource} task exists"
           if current_resource.task.status == "running"
@@ -1013,7 +1028,7 @@ class Chef
         end
       end
 
-      action :delete do
+      action :delete, description: "Deletes a scheduled task." do
         if current_resource.exists
           logger.trace "#{new_resource} task exists"
           converge_by("delete scheduled task #{new_resource}") do
@@ -1026,7 +1041,7 @@ class Chef
         end
       end
 
-      action :end do
+      action :end, description: "Ends a scheduled task." do
         if current_resource.exists
           logger.trace "#{new_resource} task exists"
           if current_resource.task.status != "running"
@@ -1041,7 +1056,7 @@ class Chef
         end
       end
 
-      action :enable do
+      action :enable, description: "Enables a scheduled task." do
         if current_resource.exists
           logger.trace "#{new_resource} task exists"
           if current_resource.task.status == "not scheduled"
@@ -1058,7 +1073,7 @@ class Chef
         end
       end
 
-      action :disable do
+      action :disable, description: "Disables a scheduled task." do
         if current_resource.exists
           logger.info "#{new_resource} task exists"
           if %w{ready running}.include?(current_resource.task.status)