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

data/lib/chef/resource/windows_font.rb

@@ -24,8 +24,17 @@ class Chef
 
       provides(:windows_font) { true }
 
-      description "Use the windows_font resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
+      description "Use the **windows_font** resource to install font files on Windows. By default, the font is sourced from the cookbook using the resource, but a URI source can be specified as well."
       introduced "14.0"
+      examples <<~DOC
+      **Install a font from a https source**:
+
+      ```ruby
+      windows_font 'Custom.otf' do
+        source "https://example.com/Custom.otf"
+      end
+      ```
+      DOC
 
       property :font_name, String,
         description: "An optional property to set the name of the font to install if it differs from the resource block's name.",

data/lib/chef/resource/windows_package.rb

@@ -30,8 +30,68 @@ class Chef
       provides(:windows_package) { true }
       provides :package, os: "windows"
 
-      description "Use the windows_package resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
+      description "Use the **windows_package** resource to manage packages on the Microsoft Windows platform. The windows_package resource supports these installer formats:\n\n Microsoft Installer Package (MSI)\n Nullsoft Scriptable Install System (NSIS)\n Inno Setup (inno)\n Wise\n InstallShield\n Custom installers such as installing a non-.msi file that embeds an .msi-based installer\n"
       introduced "11.12"
+      examples <<~DOC
+      **Install a package**:
+
+      ```ruby
+      windows_package '7zip' do
+        action :install
+        source 'C:\\7z920.msi'
+      end
+      ```
+
+      **Specify a URL for the source attribute**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+      end
+      ```
+
+      **Specify path and checksum**:
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        checksum '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+      end
+      ```
+
+      **Modify remote_file resource attributes**:
+
+      The windows_package resource may specify a package at a remote location using the remote_file_attributes property. This uses the remote_file resource to download the contents at the specified URL and passes in a Hash that modifies the properties of the remote_file resource.
+
+      ```ruby
+      windows_package '7zip' do
+        source 'http://www.7-zip.org/a/7z938-x64.msi'
+        remote_file_attributes ({
+          :path => 'C:\\7zip.msi',
+          :checksum => '7c8e873991c82ad9cfc123415254ea6101e9a645e12977dcd518979e50fdedf3'
+        })
+      end
+      ```
+
+      **Download a nsis (Nullsoft) package resource**:
+
+      ```ruby
+      windows_package 'Mercurial 3.6.1 (64-bit)' do
+        source 'http://mercurial.selenic.com/release/windows/Mercurial-3.6.1-x64.exe'
+        checksum 'febd29578cb6736163d232708b834a2ddd119aa40abc536b2c313fc5e1b5831d'
+      end
+      ```
+
+      **Download a custom package**:
+
+      ```ruby
+      windows_package 'Microsoft Visual C++ 2005 Redistributable' do
+        source 'https://download.microsoft.com/download/6/B/B/6BB661D6-A8AE-4819-B79F-236472F6070C/vcredist_x86.exe'
+        installer_type :custom
+        options '/Q'
+      end
+      ```
+      DOC
 
       allowed_actions :install, :remove
 
@@ -75,11 +135,11 @@ class Chef
           end
         end),
         default_description: "The resource block's name", # this property is basically a name_property but not really so we need to spell it out
-        description: "The path to a package in the local file system. The location of the package may be at a URL. \n"
+        description: "The path to a package in the local file system. The location of the package may be at a URL."
 
       property :checksum, String,
         desired_state: false, coerce: (proc { |c| c.downcase }),
-        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the source property."
+        description: "The SHA-256 checksum of the file. Use to prevent a file from being re-downloaded. When the local file matches the checksum, #{Chef::Dist::PRODUCT} does not download it. Use when a URL is specified by the `source` property."
 
       property :remote_file_attributes, Hash,
         desired_state: false,

data/lib/chef/resource/windows_pagefile.rb

@@ -22,8 +22,36 @@ class Chef
     class WindowsPagefile < Chef::Resource
       provides(:windows_pagefile) { true }
 
-      description "Use the windows_pagefile resource to configure pagefile settings on Windows."
+      description "Use the **windows_pagefile** resource to configure pagefile settings on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Set the system to manage pagefiles**:
+
+      ```ruby
+      windows_pagefile 'Enable automatic management of pagefiles' do
+        automatic_managed true
+      end
+      ```
+
+      **Delete a pagefile**:
+
+      ```ruby
+      windows_pagefile 'Delete the pagefile' do
+        path 'C:\pagefile.sys'
+        action :delete
+      end
+      ```
+
+      **Create a pagefile with an initial and maximum size**:
+
+      ```ruby
+      windows_pagefile 'create the pagefile' do
+        path 'C:\pagefile.sys'
+        initial_size 100
+        maximum_size 200
+      end
+      ```
+      DOC
 
       property :path, String,
         coerce: proc { |x| x.tr("/", '\\') },
@@ -34,7 +62,7 @@ class Chef
         description: "Configures whether the system manages the pagefile size."
 
       property :automatic_managed, [TrueClass, FalseClass],
-        description: "Enable automatic management of pagefile initial and maximum size. Setting this to true ignores 'initial_size' and 'maximum_size' properties.",
+        description: "Enable automatic management of pagefile initial and maximum size. Setting this to true ignores `initial_size` and `maximum_size` properties.",
         default: false
 
       property :initial_size, Integer,

data/lib/chef/resource/windows_path.rb

@@ -23,8 +23,25 @@ class Chef
     class WindowsPath < Chef::Resource
       provides(:windows_path) { true }
 
-      description "Use the windows_path resource to manage the path environment variable on Microsoft Windows."
+      description "Use the **windows_path** resource to manage the path environment variable on Microsoft Windows."
       introduced "13.4"
+      examples <<~DOC
+      **Add Sysinternals to the system path**:
+
+      ```ruby
+      windows_path 'C:\\Sysinternals' do
+        action :add
+      end
+      ```
+
+      **Remove 7-Zip from the system path**:
+
+      ```ruby
+      windows_path 'C:\\7-Zip' do
+        action :remove
+      end
+      ```
+      DOC
 
       allowed_actions :add, :remove
       default_action :add

data/lib/chef/resource/windows_printer.rb

@@ -26,11 +26,31 @@ class Chef
 
       provides(:windows_printer) { true }
 
-      description "Use the windows_printer resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system."
+      description "Use the **windows_printer** resource to setup Windows printers. Note that this doesn't currently install a printer driver. You must already have the driver installed on the system."
       introduced "14.0"
+      examples <<~DOC
+      **Create a printer**:
+
+      ```ruby
+      windows_printer 'HP LaserJet 5th Floor' do
+        driver_name 'HP LaserJet 4100 Series PCL6'
+        ipv4_address '10.4.64.38'
+      end
+      ```
+
+      **Delete a printer**:
+
+      Note: this doesn't delete the associated printer port. See windows_printer_port above for how to delete the port.
+
+      ```ruby
+      windows_printer 'HP LaserJet 5th Floor' do
+        action :delete
+      end
+      ```
+      DOC
 
       property :device_id, String,
-        description: "An optional property to set the printer queue name if it differs from the resource block's name. Example: 'HP LJ 5200 in fifth floor copy room'.",
+        description: "An optional property to set the printer queue name if it differs from the resource block's name. Example: `HP LJ 5200 in fifth floor copy room`.",
         name_property: true
 
       property :comment, String,
@@ -45,7 +65,7 @@ class Chef
         required: true
 
       property :location, String,
-        description: "Printer location, such as 'Fifth floor copy room'."
+        description: "Printer location, such as `Fifth floor copy room`."
 
       property :shared, [TrueClass, FalseClass],
         description: "Determines whether or not the printer is shared.",
@@ -55,8 +75,8 @@ class Chef
         description: "The name used to identify the shared printer."
 
       property :ipv4_address, String,
-        description: "The IPv4 address of the printer, such as '10.4.64.23'",
-        validation_message: "The ipv4_address property must be in the IPv4 format of WWW.XXX.YYY.ZZZ",
+        description: "The IPv4 address of the printer, such as `10.4.64.23`",
+        validation_message: "The ipv4_address property must be in the IPv4 format of `WWW.XXX.YYY.ZZZ`",
         regex: Resolv::IPv4::Regex
 
       property :exists, [TrueClass, FalseClass],

data/lib/chef/resource/windows_printer_port.rb

@@ -26,8 +26,36 @@ class Chef
 
       provides(:windows_printer_port) { true }
 
-      description "Use the windows_printer_port resource to create and delete TCP/IPv4 printer ports on Windows."
+      description "Use the **windows_printer_port** resource to create and delete TCP/IPv4 printer ports on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Delete a printer port**
+
+      ```ruby
+      windows_printer_port '10.4.64.37' do
+        action :delete
+      end
+      ```
+
+      **Delete a port with a custom port_name**
+
+      ```ruby
+      windows_printer_port '10.4.64.38' do
+        port_name 'My awesome port'
+        action :delete
+      end
+      ```
+
+      **Create a port with more options**
+
+      ```ruby
+      windows_printer_port '10.4.64.39' do
+        port_name 'My awesome port'
+        snmp_enabled true
+        port_protocol 2
+      end
+      ```
+      DOC
 
       property :ipv4_address, String,
         name_property: true,

data/lib/chef/resource/windows_security_policy.rb

@@ -40,7 +40,7 @@ class Chef
                 EnableAdminAccount
                 EnableGuestAccount
                 }
-      description "Use the windows_security_policy resource to set a security policy on the Microsoft Windows platform."
+      description "Use the **windows_security_policy** resource to set a security policy on the Microsoft Windows platform."
       introduced "16.0"
 
       property :secoption, String, name_property: true, required: true, equal_to: policy_names,

data/lib/chef/resource/windows_service.rb

@@ -36,7 +36,7 @@ class Chef
       provides(:windows_service) { true }
       provides :service, os: "windows"
 
-      description "Use the windows_service resource to create, delete, or manage a service on the Microsoft Windows platform."
+      description "Use the **windows_service** resource to create, delete, or manage a service on the Microsoft Windows platform."
       introduced "12.0"
 
       allowed_actions :configure_startup, :create, :delete, :configure

data/lib/chef/resource/windows_share.rb

@@ -28,8 +28,28 @@ class Chef
     class WindowsShare < Chef::Resource
       provides :windows_share
 
-      description "Use the windows_share resource to create, modify and remove Windows shares."
+      description "Use the **windows_share** resource to create, modify and remove Windows shares."
       introduced "14.7"
+      examples <<~DOC
+      **Create a share**:
+
+      ```ruby
+      windows_share 'foo' do
+        action :create
+        path 'C:\\foo'
+        full_users ['DOMAIN_A\\some_user', 'DOMAIN_B\\some_other_user']
+        read_users ['DOMAIN_C\\Domain users']
+      end
+      ```
+
+      **Delete a share**:
+
+      ```ruby
+      windows_share 'foo' do
+        action :delete
+      end
+      ```
+      DOC
 
       # Specifies a name for the SMB share. The name may be composed of any valid file name characters, but must be less than 80 characters long. The names pipe and mailslot are reserved for use by the computer.
       property :share_name, String,

data/lib/chef/resource/windows_shortcut.rb

@@ -23,8 +23,19 @@ class Chef
     class WindowsShortcut < Chef::Resource
       provides(:windows_shortcut) { true }
 
-      description "Use the windows_shortcut resource to create shortcut files on Windows."
+      description "Use the **windows_shortcut** resource to create shortcut files on Windows."
       introduced "14.0"
+      examples <<~DOC
+      **Create a shortcut with a description**:
+
+      ```ruby
+      windows_shortcut 'C:\\shortcut_dir.lnk' do
+        target 'C:\\original_dir'
+        description 'Make a shortcut to C:\\original_dir'
+      end
+      ```
+
+      DOC
 
       property :shortcut_name, String,
         description: "An optional property to set the shortcut name if it differs from the resource block's name.",
@@ -43,7 +54,7 @@ class Chef
         description: "Working directory to use when the target is executed."
 
       property :iconlocation, String,
-        description: "Icon to use for the shortcut. Accepts the format of 'path, index', where index is the icon file to use. See https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx for details"
+        description: "Icon to use for the shortcut. Accepts the format of `path, index`, where index is the icon file to use. See Microsoft's [documentation](https://msdn.microsoft.com/en-us/library/3s9bx7at.aspx) for details"
 
       load_current_value do |desired|
         require "win32ole" if RUBY_PLATFORM =~ /mswin|mingw32|windows/

data/lib/chef/resource/windows_task.rb

@@ -24,14 +24,127 @@ class Chef
     class WindowsTask < Chef::Resource
       provides(:windows_task) { true }
 
-      description "Use the windows_task resource to create, delete or run a Windows scheduled task. Requires Windows Server 2008 or later due to API usage."
+      description "Use the **windows_task** resource to create, delete or run a Windows scheduled task."
       introduced "13.0"
+      examples <<~DOC
+      **Create a scheduled task to run every 15 minutes as the Administrator user**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        user 'Administrator'
+        password 'password'
+        command 'chef-client'
+        run_level :highest
+        frequency :minute
+        frequency_modifier 15
+      end
+      ```
+
+      **Create a scheduled task to run every 2 days**:
+
+      ``` ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :daily
+        frequency_modifier 2
+      end
+      ```
+
+      **Create a scheduled task to run on specific days of the week**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        day 'Mon, Thu'
+      end
+      ```
+
+      **Create a scheduled task to run only once**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :once
+        start_time "16:10"
+      end
+      ```
+
+      **Create a scheduled task to run on current day every 3 weeks and delay upto 1 min**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        frequency_modifier 3
+        random_delay '60'
+      end
+      ```
+
+      **Create a scheduled task to run weekly starting on Dec 28th 2018**:
+
+      ```ruby
+      windows_task 'chef-client 8' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        start_day '12/28/2018'
+      end
+      ```
+
+      **Create a scheduled task to run every Monday, Friday every 2 weeks**:
+
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :weekly
+        frequency_modifier 2
+        day 'Mon, Fri'
+      end
+      ```
+
+      **Create a scheduled task to run when computer is idle with idle duration 20 min**:
+      ```ruby
+      windows_task 'chef-client' do
+        command 'chef-client'
+        run_level :highest
+        frequency :on_idle
+        idle_time 20
+      end
+      ```
+
+      **Delete a task named "old task"**:
+      ```ruby
+      windows_task 'old task' do
+        action :delete
+      end
+      ```
+
+      **Enable a task named "chef-client"**:
+      ```ruby
+      windows_task 'chef-client' do
+        action :enable
+      end
+      ```
+
+      **Disable a task named "ProgramDataUpdater" with TaskPath "\\Microsoft\\Windows\\Application Experience\\ProgramDataUpdater"**
+      ```ruby
+      windows_task '\\Microsoft\\Windows\\Application Experience\\ProgramDataUpdater' do
+        action :disable
+      end
+      ```
+      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'",
+               description: "An optional property to set the task name if it differs from the resource block's name. Example: `Task Name` or `/Task Name`",
                name_property: true
 
       property :command, String,
@@ -46,10 +159,10 @@ class Chef
         default_description: "The localized SYSTEM user for the node."
 
       property :password, String,
-        description: "The user’s password. The user property must be set if using this property."
+        description: "The user's password. The user property must be set if using this property."
 
       property :run_level, Symbol, equal_to: %i{highest limited},
-               description: "Run with ':limited' or ':highest' privileges.",
+               description: "Run with `:limited` or `:highest` privileges.",
                default: :limited
 
       property :force, [TrueClass, FalseClass],
@@ -86,17 +199,18 @@ class Chef
         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'."
+        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."
+        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: "Delays the task up to a given time (in seconds)."
 
       property :execution_time_limit, [String, Integer],
-        description: "The maximum time (in seconds) the task will run.",
-        default: "PT72H" # 72 hours in ISO8601 duration format
+        description: "The maximum time the task will run. This field accepts either seconds or an ISO8601 duration value.",
+        default: "PT72H",
+        default_description: "PT72H (72 hours in ISO8601 duration format)"
 
       property :minutes_duration, [String, Integer],
         description: ""