chef 16.0.257-universal-mingw32 → 16.0.275-universal-mingw32

data/lib/chef/resource/chocolatey_config.rb

@@ -21,10 +21,11 @@ class Chef
 
       provides :chocolatey_config
 
-      description "Use the chocolatey_config resource to add or remove Chocolatey configuration keys."
+      description "Use the **chocolatey_config** resource to add or remove Chocolatey configuration keys."
       introduced "14.3"
       examples <<~DOC
-        Set the Chocolatey cacheLocation config
+        **Set the Chocolatey cacheLocation config**:
+
         ```ruby
         chocolatey_config 'Set cacheLocation config' do
           config_key 'cacheLocation'
@@ -32,7 +33,8 @@ class Chef
         end
         ```
 
-        Unset a Chocolatey config
+        **Unset a Chocolatey config**:
+
         ```ruby
         chocolatey_config 'BogusConfig' do
           action :unset

data/lib/chef/resource/chocolatey_feature.rb

@@ -20,17 +20,19 @@ class Chef
       unified_mode true
       provides :chocolatey_feature
 
-      description "Use the chocolatey_feature resource to enable and disable Chocolatey features."
+      description "Use the **chocolatey_feature** resource to enable and disable Chocolatey features."
       introduced "15.1"
       examples <<~DOC
-        Enable the checksumFiles Chocolatey feature
+        **Enable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :enable
         end
         ```
 
-        Disable the checksumFiles Chocolatey feature
+        **Disable the checksumFiles Chocolatey feature**
+
         ```ruby
         chocolatey_feature 'checksumFiles' do
           action :disable

data/lib/chef/resource/chocolatey_package.rb

@@ -25,17 +25,19 @@ class Chef
 
       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. 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."
       introduced "12.7"
       examples <<~DOC
-        Install a Chocolatey package
+        **Install a Chocolatey package**:
+
         ```ruby
         chocolatey_package 'name of package' do
           action :install
         end
         ```
 
-        Install a package with options with Chocolatey's ``--checksum`` option
+        **Install a package with options with Chocolatey's `--checksum` option**:
+
         ```ruby
         chocolatey_package 'name of package' do
           options '--checksum 1234567890'

data/lib/chef/resource/chocolatey_source.rb

@@ -20,10 +20,11 @@ class Chef
       unified_mode true
       provides :chocolatey_source
 
-      description "Use the chocolatey_source resource to add, remove, enable, or disable Chocolatey sources."
+      description "Use the **chocolatey_source** resource to add, remove, enable, or disable Chocolatey sources."
       introduced "14.3"
       examples <<~DOC
-        Add a Chocolatey source
+        **Add a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           source 'http://example.com/something'
@@ -31,7 +32,8 @@ class Chef
         end
         ```
 
-        Remove a Chocolatey source
+        **Remove a Chocolatey source**
+
         ```ruby
         chocolatey_source 'MySource' do
           action :remove

data/lib/chef/resource/cookbook_file.rb

@@ -31,7 +31,7 @@ class Chef
 
       provides :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::Dist::PRODUCT}. 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::Dist::PRODUCT} 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::Dist::SERVER_PRODUCT}. A file is not transferred when the checksums match. Only files that require an update are transferred from the #{Chef::Dist::SERVER_PRODUCT} 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::Dist::PRODUCT}. 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::Dist::PRODUCT} 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::Dist::SERVER_PRODUCT}. A file is not transferred when the checksums match. Only files that require an update are transferred from the #{Chef::Dist::SERVER_PRODUCT} to a node."
 
       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.",
@@ -39,7 +39,8 @@ class Chef
 
       property :cookbook, String,
         description: "The cookbook in which a file is located (if it is not located in the current cookbook).",
-        desired_state: false
+        desired_state: false,
+        default_description: "The current cookbook name"
 
       default_action :create
     end

data/lib/chef/resource/cron.rb

@@ -27,7 +27,7 @@ class Chef
       unified_mode true
       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
 
@@ -41,25 +41,25 @@ class Chef
       end
 
       property :minute, [Integer, String],
-        description: "The minute at which the cron entry should run (0 - 59).",
+        description: "The minute at which the cron entry should run (`0 - 59`).",
         default: "*", callbacks: {
           "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
         }
 
       property :hour, [Integer, String],
-        description: "The hour at which the cron entry is to run (0 - 23).",
+        description: "The hour at which the cron entry is to run (`0 - 23`).",
         default: "*", callbacks: {
           "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
         }
 
       property :day, [Integer, String],
-        description: "The day of month at which the cron entry should run (1 - 31).",
+        description: "The day of month at which the cron entry should run (`1 - 31`).",
         default: "*", callbacks: {
           "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
         }
 
       property :month, [Integer, String],
-        description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).",
+        description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
         default: "*", callbacks: {
           "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
         }
@@ -93,16 +93,16 @@ class Chef
         equal_to: Chef::Provider::Cron::SPECIAL_TIME_VALUES
 
       property :mailto, String,
-        description: "Set the MAILTO environment variable."
+        description: "Set the `MAILTO` environment variable."
 
       property :path, String,
-        description: "Set the PATH environment variable."
+        description: "Set the `PATH` environment variable."
 
       property :home, String,
-        description: "Set the HOME environment variable."
+        description: "Set the `HOME` environment variable."
 
       property :shell, String,
-        description: "Set the SHELL environment variable."
+        description: "Set the `SHELL` environment variable."
 
       property :command, String,
         description: "The command to be run, or the path to a file that contains the command to be run.",
@@ -113,19 +113,19 @@ class Chef
         default: "root"
 
       property :environment, Hash,
-        description: "A Hash of environment variables in the form of ({'ENV_VARIABLE' => 'VALUE'}).",
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
       TIMEOUT_REGEX = /\A\S+/.freeze
 
       property :time_out, Hash,
-        description: "A Hash of timeouts in the form of ({'OPTION' => 'VALUE'}).
+        description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
-        preserve-status (BOOL, default: 'false'),
-        foreground (BOOL, default: 'false'),
-        kill-after (in seconds),
-        signal (a name like 'HUP' or a number)",
+        `preserve-status` (BOOL, default: 'false'),
+        `foreground` (BOOL, default: 'false'),
+        `kill-after` (in seconds),
+        `signal` (a name like 'HUP' or a number)",
         default: lazy { {} },
         introduced: "15.7",
         coerce: proc { |h|

data/lib/chef/resource/cron_access.rb

@@ -28,21 +28,24 @@ class Chef
       provides(:cron_manage) # legacy name @todo in Chef 15 we should { true } this so it wins over the cookbook
 
       introduced "14.4"
-      description "Use the cron_access resource to manage the /etc/cron.allow and /etc/cron.deny files."
+      description "Use the **cron_access** resource to manage the /etc/cron.allow and /etc/cron.deny files. Note: This resource previously shipped in the `cron` cookbook as `cron_manage`, which it can still be used as for backwards compatibility with existing Chef Infra Client releases."
       examples <<~DOC
-        Add the mike user to cron.allow
+        **Add the mike user to cron.allow**
+
         ```ruby
         cron_access 'mike'
         ```
 
-        Add the mike user to cron.deny
+        **Add the mike user to cron.deny**
+
         ```ruby
         cron_access 'mike' do
           action :deny
         end
         ```
 
-        Specify the username with the user property
+        **Specify the username with the user property**
+
         ```ruby
         cron_access 'Deny the jenkins user access to cron for security purposes' do
           user 'jenkins'

data/lib/chef/resource/cron_d.rb

@@ -27,9 +27,10 @@ class Chef
       provides :cron_d
 
       introduced "14.4"
-      description "Use the cron_d resource to manage cron definitions in /etc/cron.d. 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. This is similar to the 'cron' resource, but it does not use the monolithic /etc/crontab file."
       examples <<~DOC
-        To run a program on the fifth hour of the day
+        **Run a program on the fifth hour of the day**
+
         ```ruby
         cron_d 'noop' do
           hour '5'
@@ -38,7 +39,8 @@ class Chef
         end
         ```
 
-        To run an entry if a folder exists
+        **Run an entry if a folder exists**
+
         ```ruby
         cron_d 'ganglia_tomcat_thread_max' do
           command "/usr/bin/gmetric
@@ -50,18 +52,21 @@ class Chef
         end
         ```
 
-        To run an entry every Saturday, 8:00 AM
+        **Run an entry every Saturday, 8:00 AM**
+
         ```ruby
         cron_d 'name_of_cron_entry' do
           minute '0'
           hour '8'
           weekday '6'
           mailto 'admin@example.com'
+          command "/bin/true"
           action :create
         end
         ```
 
-        To run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November
+        **Run an entry at 8:00 PM, every weekday (Monday through Friday), but only in November**
+
         ```ruby
         cron_d 'name_of_cron_entry' do
           minute '0'
@@ -69,88 +74,97 @@ class Chef
           day '*'
           month '11'
           weekday '1-5'
+          command "/bin/true"
           action :create
         end
         ```
+
+        **Remove a cron job by name**:
+
+        ```ruby
+        cron_d 'job_to_remove' do
+          action :delete
+        end
+        ```
       DOC
 
       property :cron_name, String,
         description: "An optional property to set the cron name if it differs from the resource block's name.",
         name_property: true
 
-      property :cookbook, String, desired_state: false
+      property :cookbook, String, desired_state: false, skip_docs: true
 
       property :predefined_value, String,
         description: "Schedule your cron job with one of the special predefined value instead of ** * pattern.",
         equal_to: %w{ @reboot @yearly @annually @monthly @weekly @daily @midnight @hourly }
 
       property :minute, [Integer, String],
-        description: "The minute at which the cron entry should run (0 - 59).",
+        description: "The minute at which the cron entry should run (`0 - 59`).",
         default: "*", callbacks: {
           "should be a valid minute spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 59) },
         }
 
       property :hour, [Integer, String],
-        description: "The hour at which the cron entry is to run (0 - 23).",
+        description: "The hour at which the cron entry is to run (`0 - 23`).",
         default: "*", callbacks: {
           "should be a valid hour spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 0, 23) },
         }
 
       property :day, [Integer, String],
-        description: "The day of month at which the cron entry should run (1 - 31).",
+        description: "The day of month at which the cron entry should run (`1 - 31`).",
         default: "*", callbacks: {
           "should be a valid day spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_numeric(spec, 1, 31) },
         }
 
       property :month, [Integer, String],
-        description: "The month in the year on which a cron entry is to run (1 - 12, jan-dec, or *).",
+        description: "The month in the year on which a cron entry is to run (`1 - 12`, `jan-dec`, or `*`).",
         default: "*", callbacks: {
           "should be a valid month spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_month(spec) },
         }
 
       property :weekday, [Integer, String],
-        description: "The day of the week on which this entry is to run (0-7, mon-sun, or *), where Sunday is both 0 and 7.",
+        description: "The day of the week on which this entry is to run (`0-7`, `mon-sun`, or `*`), where Sunday is both `0` and `7`.",
         default: "*", callbacks: {
           "should be a valid weekday spec" => ->(spec) { Chef::ResourceHelpers::CronValidations.validate_dow(spec) },
         }
 
       property :command, String,
         description: "The command to run.",
-        required: true
+        required: [:create]
 
       property :user, String,
         description: "The name of the user that runs the command.",
         default: "root"
 
       property :mailto, String,
-        description: "Set the MAILTO environment variable in the cron.d file."
+        description: "Set the `MAILTO` environment variable in the cron.d file."
 
       property :path, String,
-        description: "Set the PATH environment variable in the cron.d file."
+        description: "Set the `PATH` environment variable in the cron.d file."
 
       property :home, String,
-        description: "Set the HOME environment variable in the cron.d file."
+        description: "Set the `HOME` environment variable in the cron.d file."
 
       property :shell, String,
-        description: "Set the SHELL environment variable in the cron.d file."
+        description: "Set the `SHELL` environment variable in the cron.d file."
 
       property :comment, String,
         description: "A comment to place in the cron.d file."
 
       property :environment, Hash,
-        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of ``({'ENV_VARIABLE' => 'VALUE'})``.",
+        description: "A Hash containing additional arbitrary environment variables under which the cron job will be run in the form of `({'ENV_VARIABLE' => 'VALUE'})`.",
         default: lazy { {} }
 
       TIMEOUT_OPTS = %w{duration preserve-status foreground kill-after signal}.freeze
       TIMEOUT_REGEX = /\A\S+/.freeze
 
       property :time_out, Hash,
-        description: "A Hash of timeouts in the form of ({'OPTION' => 'VALUE'}).
+        description: "A Hash of timeouts in the form of `({'OPTION' => 'VALUE'})`.
         Accepted valid options are:
-        preserve-status (BOOL, default: 'false'),
-        foreground (BOOL, default: 'false'),
-        kill-after (in seconds),
-        signal (a name like 'HUP' or a number)",
+        `preserve-status` (BOOL, default: 'false'),
+        `foreground` (BOOL, default: 'false'),
+        `kill-after` (in seconds),
+        `signal` (a name like 'HUP' or a number)",
         default: lazy { {} },
         introduced: "15.7",
         coerce: proc { |h|
@@ -175,7 +189,7 @@ class Chef
         default: "0600"
 
       property :random_delay, Integer,
-        description: "Set the RANDOM_DELAY environment variable in the cron.d file."
+        description: "Set the `RANDOM_DELAY` environment variable in the cron.d file."
 
       # warn if someone passes the deprecated cookbook property
       def after_created

data/lib/chef/resource/csh.rb

@@ -26,7 +26,7 @@ class Chef
 
       provides :csh
 
-      description "Use the csh resource to execute scripts using the csh interpreter."\
+      description "Use the **csh** resource to execute scripts using the csh 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"\

data/lib/chef/resource/directory.rb

@@ -28,7 +28,7 @@ class Chef
 
       provides :directory
 
-      description "Use the directory resource to manage a directory, which is a hierarchy"\
+      description "Use the **directory** resource to manage a directory, which is a hierarchy"\
                   " of folders that comprises all of the information stored on a computer."\
                   " The root directory is the top-level, under which the rest of the directory"\
                   " is organized. The directory resource uses the name property to specify the"\

data/lib/chef/resource/dmg_package.rb

@@ -24,10 +24,11 @@ class Chef
 
       provides(:dmg_package) { true }
 
-      description "Use the dmg_package resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using OS X's hdidutil, copy the application (.app directory) to the specified destination (/Applications), and detach the image using hdiutil. The dmg file will be stored in the Chef::Config[:file_cache_path]."
+      description "Use the **dmg_package** resource to install a package from a .dmg file. The resource will retrieve the dmg file from a remote URL, mount it using macOS' `hdidutil`, copy the application (.app directory) to the specified destination (`/Applications`), and detach the image using `hdiutil`. The dmg file will be stored in the `Chef::Config[:file_cache_path]`."
       introduced "14.0"
       examples <<~DOC
-        Install Google Chrome via the DMG package
+        **Install Google Chrome via the DMG package**:
+
         ```ruby
         dmg_package 'Google Chrome' do
           dmg_name 'googlechrome'
@@ -37,7 +38,8 @@ class Chef
         end
         ```
 
-        Install Virtualbox from the .mpkg
+        **Install Virtualbox from the .mpkg**:
+
         ```ruby
         dmg_package 'Virtualbox' do
           source 'http://dlc.sun.com.edgesuite.net/virtualbox/4.0.8/VirtualBox-4.0.8-71778-OSX.dmg'
@@ -45,7 +47,8 @@ class Chef
         end
         ```
 
-        Install pgAdmin and automatically accept the EULA
+        **Install pgAdmin and automatically accept the EULA**:
+
         ```ruby
         dmg_package 'pgAdmin3' do
           source   'http://wwwmaster.postgresql.org/redir/198/h/pgadmin3/release/v1.12.3/osx/pgadmin3-1.12.3.dmg'
@@ -56,31 +59,31 @@ class Chef
       DOC
 
       property :app, String,
-        description: "The name of the application as it appears in the /Volumes directory if it differs from the resource block's name.",
+        description: "The name of the application as it appears in the `/Volumes` directory if it differs from the resource block's name.",
         name_property: true
 
       property :source, String,
-        description: "The remote URL that is used to download the .dmg file, if specified."
+        description: "The remote URL that is used to download the `.dmg` file, if specified."
 
       property :file, String,
-        description: "The full path to the .dmg file on the local system."
+        description: "The full path to the `.dmg` file on the local system."
 
       property :owner, [String, Integer],
         description: "The user that should own the package installation."
 
       property :destination, String,
-        description: "The directory to copy the .app into.",
+        description: "The directory to copy the `.app` into.",
         default: "/Applications"
 
       property :checksum, String,
-        description: "The sha256 checksum of the .dmg file to download."
+        description: "The sha256 checksum of the `.dmg` file to download."
 
       property :volumes_dir, String,
-        description: "The directory under /Volumes where the dmg is mounted if it differs from the name of the .dmg file.",
+        description: "The directory under `/Volumes` where the `dmg` is mounted if it differs from the name of the `.dmg` file.",
         default: lazy { app }, default_description: "The value passed for the application name."
 
       property :dmg_name, String,
-        description: "The name of the .dmg file if it differs from that of the app, or if the name has spaces.",
+        description: "The name of the `.dmg` file if it differs from that of the app, or if the name has spaces.",
         desired_state: false,
         default: lazy { app }, default_description: "The value passed for the application name."
 
@@ -90,18 +93,18 @@ class Chef
         default: "app", desired_state: false
 
       property :package_id, String,
-        description: "The package ID that is registered with pkgutil when a pkg or mpkg is installed."
+        description: "The package ID that is registered with `pkgutil` when a `pkg` or `mpkg` is installed."
 
       property :dmg_passphrase, String,
-        description: "Specify a passphrase to be used to decrypt the .dmg file during the mount process.",
+        description: "Specify a passphrase to be used to decrypt the `.dmg` file during the mount process.",
         desired_state: false
 
       property :accept_eula, [TrueClass, FalseClass],
-        description: "Specify whether to accept the EULA. Certain dmgs require acceptance of EULA before mounting.",
+        description: "Specify whether to accept the EULA. Certain dmg files require acceptance of EULA before mounting.",
         default: false, desired_state: false
 
       property :headers, Hash,
-        description: "Allows custom HTTP headers (like cookies) to be set on the remote_file resource.",
+        description: "Allows custom HTTP headers (like cookies) to be set on the `remote_file` resource.",
         desired_state: false
 
       property :allow_untrusted, [TrueClass, FalseClass],