chef 16.1.16 → 16.18.30

data/lib/chef/resource/launchd.rb

@@ -68,7 +68,7 @@ class Chef
       # check.  According to `man 5 launchd.plist`:
       #   StartCalendarInterval <dictionary of integers or array of dictionaries of integers>
       #     ... Missing arguments are considered to be wildcard.
-      # What the man page doesn't state, but what was observed (OSX 10.11.5, launchctrl v3.4.0)
+      # What the man page doesn't state, but what was observed (OSX 10.11.5, launchctl v3.4.0)
       # Is that keys that are specified, but invalid, will also be treated as a wildcard
       # this means that an entry like:
       #   { "Hour"=>0, "Weekday"=>"6-7"}
@@ -131,35 +131,35 @@ class Chef
         description: "If a job dies, all remaining processes with the same process ID may be kept running. Set to true to kill all remaining processes."
 
       property :debug, [ TrueClass, FalseClass ],
-        description: "Sets the log mask to LOG_DEBUG for this job."
+        description: "Sets the log mask to `LOG_DEBUG` for this job."
 
       property :disabled, [ TrueClass, FalseClass ], default: false,
-               description: "Hints to launchctl to not submit this job to launchd."
+               description: "Hints to `launchctl` to not submit this job to launchd."
 
       property :enable_globbing, [ TrueClass, FalseClass ],
         description: "Update program arguments before invocation."
 
       property :enable_transactions, [ TrueClass, FalseClass ],
-        description: "Track in-progress transactions; if none, then send the SIGKILL signal."
+        description: "Track in-progress transactions; if none, then send the `SIGKILL` signal."
 
       property :environment_variables, Hash,
         description: "Additional environment variables to set before running a job."
 
       property :exit_timeout, Integer,
-        description: "The amount of time (in seconds) launchd waits before sending a SIGKILL signal."
+        description: "The amount of time (in seconds) launchd waits before sending a `SIGKILL` signal."
 
       property :hard_resource_limits, Hash,
         description: "A Hash of resource limits to be imposed on a job."
 
       property :inetd_compatibility, Hash,
-        description: "Specifies if a daemon expects to be run as if it were launched from inetd. Set to wait => true to pass standard input, output, and error file descriptors. Set to wait => false to call the accept system call on behalf of the job, and then pass standard input, output, and error file descriptors."
+        description: "Specifies if a daemon expects to be run as if it were launched from inetd. Set to `wait => true` to pass standard input, output, and error file descriptors. Set to `wait => false` to call the accept system call on behalf of the job, and then pass standard input, output, and error file descriptors."
 
       property :init_groups, [ TrueClass, FalseClass ],
-        description: "Specify if initgroups is called before running a job."
+        description: "Specify if `initgroups` is called before running a job."
 
       property :keep_alive, [ TrueClass, FalseClass, Hash ],
         introduced: "12.14",
-        description: "Keep a job running continuously (true) or allow demand and conditions on the node to determine if the job keeps running (false)."
+        description: "Keep a job running continuously (true) or allow demand and conditions on the node to determine if the job keeps running (`false`)."
 
       property :launch_events, [ Hash ],
         introduced: "15.1",
@@ -187,13 +187,14 @@ class Chef
         description: "Specify services to be registered with the bootstrap subsystem."
 
       property :nice, Integer,
-        description: "The program scheduling priority value in the range -20 to 20."
+        description: "The program scheduling priority value in the range -20 to 19.",
+        callbacks: { "should be a Integer between -20 and 19" => proc { |v| v >= -20 && v <= 19 } }
 
       property :on_demand, [ TrueClass, FalseClass ],
-        description: "Keep a job alive. Only applies to macOS version 10.4 (and earlier); use keep_alive instead for newer versions."
+        description: "Keep a job alive. Only applies to macOS version 10.4 (and earlier); use `keep_alive` instead for newer versions."
 
       property :process_type, String,
-        description: "The intended purpose of the job: Adaptive, Background, Interactive, or Standard."
+        description: "The intended purpose of the job: `Adaptive`, `Background`, `Interactive`, or `Standard`."
 
       property :program, String,
         description: "The first argument of execvp, typically the file name associated with the file to be executed. This value must be specified if program_arguments is not specified, and vice-versa."
@@ -205,7 +206,7 @@ class Chef
         description: "An array of non-empty directories which, if any are modified, will cause a job to be started."
 
       property :root_directory, String,
-        description: "chroot to this directory, and then run the job."
+        description: "`chroot` to this directory, and then run the job."
 
       property :run_at_load, [ TrueClass, FalseClass ],
         description: "Launch a job once (at the time it is loaded)."
@@ -217,13 +218,13 @@ class Chef
         description: "A Hash of resource limits to be imposed on a job."
 
       property :standard_error_path, String,
-        description: "The file to which standard error (stderr) is sent."
+        description: "The file to which standard error (`stderr`) is sent."
 
       property :standard_in_path, String,
-        description: "The file to which standard input (stdin) is sent."
+        description: "The file to which standard input (`stdin`) is sent."
 
       property :standard_out_path, String,
-        description: "The file to which standard output (stdout) is sent."
+        description: "The file to which standard output (`stdout`) is sent."
 
       property :start_interval, Integer,
         description: "The frequency (in seconds) at which a job is started."
@@ -238,7 +239,7 @@ class Chef
         description: "The amount of time (in seconds) a job may be idle before it times out. If no value is specified, the default timeout value for launchd will be used."
 
       property :umask, Integer,
-        description: "A decimal value to pass to umask before running a job."
+        description: "A decimal value to pass to `umask` before running a job."
 
       property :username, String,
         description: "When launchd is run as the root user, the user to run the job as."
@@ -250,7 +251,7 @@ class Chef
         description: "An array of paths which, if any are modified, will cause a job to be started."
 
       property :working_directory, String,
-        description: "Chdir to this directory, and then run the job."
+        description: "`chdir` to this directory, and then run the job."
     end
   end
 end

data/lib/chef/resource/locale.rb

@@ -16,7 +16,7 @@
 #
 
 require_relative "../resource"
-require_relative "../dist"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 
 class Chef
   class Resource
@@ -71,7 +71,7 @@ class Chef
       #
       def lc_all(arg = nil)
         unless arg.nil?
-          Chef.deprecated(:locale_lc_all, "Changing LC_ALL can break #{Chef::Dist::PRODUCT}'s parsing of command output in unexpected ways.\n Use one of the more specific LC_ properties as needed.")
+          Chef.deprecated(:locale_lc_all, "Changing LC_ALL can break #{ChefUtils::Dist::Infra::PRODUCT}'s parsing of command output in unexpected ways.\n Use one of the more specific LC_ properties as needed.")
         end
       end
 
@@ -115,7 +115,7 @@ class Chef
 
           requirements.assert(:all_actions) do |a|
             # RHEL/CentOS type platforms don't have locale-gen
-            a.assertion { shell_out("locale-gen") }
+            a.assertion { which("locale-gen") }
             a.failure_message(Chef::Exceptions::ProviderNotFound, "The locale resource requires the locale-gen tool")
           end
         end
@@ -125,7 +125,7 @@ class Chef
         # @raise [Mixlib::ShellOut::ShellCommandFailed] not a supported language or locale
         #
         def generate_locales
-          shell_out!("locale-gen #{unavailable_locales.join(" ")}")
+          shell_out!("locale-gen #{unavailable_locales.join(" ")}", timeout: 1800)
         end
 
         # Sets the system locale for the current computer.

data/lib/chef/resource/lwrp_base.rb

@@ -63,17 +63,15 @@ class Chef
 
           Chef::Log.trace("Loaded contents of #{filename} into resource #{resource_name} (#{resource_class})")
 
-          LWRPBase.loaded_lwrps[filename] = true
-
           # wire up the default resource name after the class is parsed only if we haven't declared one.
           # (this ordering is important for MapCollision deprecation warnings)
           resource_class.provides resource_name.to_sym unless Chef::ResourceResolver.includes_handler?(resource_name.to_sym, self)
 
+          LWRPBase.loaded_lwrps[filename] = resource_class
+
           resource_class
         end
 
-        alias :attribute :property
-
         # Adds +action_names+ to the list of valid actions for this resource.
         # Does not include superclass's action list when appending.
         def actions(*action_names)
@@ -88,7 +86,7 @@ class Chef
 
         # @deprecated
         def valid_actions(*args)
-          Chef::Log.warn("`valid_actions' is deprecated, please use allowed_actions `instead'!")
+          Chef::Log.warn("`valid_actions` is deprecated, please use `allowed_actions` instead!")
           allowed_actions(*args)
         end
 
@@ -103,6 +101,7 @@ class Chef
         protected
 
         attr_writer :loaded_lwrps
+
         def loaded_lwrps
           @loaded_lwrps ||= {}
         end

data/lib/chef/resource/macos_userdefaults.rb

@@ -16,6 +16,8 @@
 #
 
 require_relative "../resource"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
+autoload :Plist, "plist"
 
 class Chef
   class Resource
@@ -28,99 +30,210 @@ class Chef
 
       description "Use the **macos_userdefaults** resource to manage the macOS user defaults system. The properties of this resource are passed to the defaults command, and the parameters follow the convention of that command. See the defaults(1) man page for details on how the tool works."
       introduced "14.0"
+      examples <<~DOC
+        **Specify a global domain value**
+
+        ```ruby
+        macos_userdefaults 'Full keyboard access to all controls' do
+          key 'AppleKeyboardUIMode'
+          value 2
+        end
+        ```
+
+        **Setting a value on a specific domain**
+
+        ```ruby
+        macos_userdefaults 'Enable macOS firewall' do
+          domain '/Library/Preferences/com.apple.alf'
+          key 'globalstate'
+          value 1
+        end
+        ```
+
+        **Specifying the type of a key to skip automatic type detection**
+
+        ```ruby
+        macos_userdefaults 'Finder expanded save dialogs' do
+          key 'NSNavPanelExpandedStateForSaveMode'
+          value 'TRUE'
+          type 'bool'
+        end
+        ```
+      DOC
 
       property :domain, String,
         description: "The domain that the user defaults belong to.",
-        required: true
+        default: "NSGlobalDomain",
+        default_description: "NSGlobalDomain: the global domain.",
+        desired_state: false
 
       property :global, [TrueClass, FalseClass],
         description: "Determines whether or not the domain is global.",
-        default: false
+        deprecated: true,
+        default: false,
+        desired_state: false
 
       property :key, String,
-        description: "The preference key."
+        description: "The preference key.",
+        required: true
+
+      property :host, [String, Symbol],
+        description: "Set either :current or a hostname to set the user default at the host level.",
+        desired_state: false,
+        introduced: "16.3"
 
       property :value, [Integer, Float, String, TrueClass, FalseClass, Hash, Array],
-        description: "The value of the key.",
-        required: true
+        description: "The value of the key. Note: With the `type` property set to `bool`, `String` forms of Boolean true/false values that Apple accepts in the defaults command will be coerced: 0/1, 'TRUE'/'FALSE,' 'true'/false', 'YES'/'NO', or 'yes'/'no'.",
+        required: [:write],
+        coerce: proc { |v| v.is_a?(Hash) ? v.transform_keys(&:to_s) : v } # make sure keys are all strings for comparison
 
       property :type, String,
         description: "The value type of the preference key.",
-        default: ""
+        equal_to: %w{bool string int float array dict},
+        desired_state: false
 
       property :user, String,
-        description: "The system user that the default will be applied to."
+        description: "The system user that the default will be applied to.",
+        desired_state: false
 
       property :sudo, [TrueClass, FalseClass],
-        description: "Set to true if the setting you wish to modify requires privileged access.",
+        description: "Set to true if the setting you wish to modify requires privileged access. This requires passwordless sudo for the '/usr/bin/defaults' command to be setup for the user running #{ChefUtils::Dist::Infra::PRODUCT}.",
         default: false,
         desired_state: false
 
-      # @todo this should get refactored away: https://github.com/chef/chef/issues/7622
-      property :is_set, [TrueClass, FalseClass],
-        default: false,
-        desired_state: false,
-        skip_docs: true
+      load_current_value do |desired|
+        Chef::Log.debug "#load_current_value: shelling out \"#{defaults_export_cmd(desired).join(" ")}\" to determine state"
+        state = shell_out(defaults_export_cmd(desired), user: desired.user)
 
-      # coerce various ways of representing a boolean into either 0 (false) or 1 (true)
-      # which is what the defaults CLI expects. Why? Well defaults itself accepts a few
-      # different formats, but when you do a read command it all comes back as 1 or 0.
-      def coerce_booleans(val)
-        return 1 if [true, "TRUE", "1", "true", "YES", "yes"].include?(val)
-        return 0 if [false, "FALSE", "0", "false", "NO", "no"].include?(val)
+        if state.error? || state.stdout.empty?
+          Chef::Log.debug "#load_current_value: #{defaults_export_cmd(desired).join(" ")} returned stdout: #{state.stdout} and stderr: #{state.stderr}"
+          current_value_does_not_exist!
+        end
+
+        plist_data = ::Plist.parse_xml(state.stdout)
+
+        # handle the situation where the key doesn't exist in the domain
+        if plist_data.key?(desired.key)
+          key desired.key
+        else
+          current_value_does_not_exist!
+        end
 
-        val
+        value plist_data[desired.key]
       end
 
-      load_current_value do |desired|
-        value = coerce_booleans(desired.value)
-        cmd = "defaults read '#{desired.domain}' "
-        cmd << "'#{desired.key}' " if desired.key
-        cmd << " | grep -qx '#{value}'"
-
-        vc = if desired.user.nil?
-               shell_out(cmd)
-             else
-               shell_out(cmd, user: desired.user)
-             end
-
-        is_set !vc.error?
+      #
+      # The defaults command to export a domain
+      #
+      # @return [Array] defaults command
+      #
+      def defaults_export_cmd(resource)
+        state_cmd = ["/usr/bin/defaults"]
+
+        if resource.host == "current"
+          state_cmd.concat(["-currentHost"])
+        elsif resource.host # they specified a non-nil value, which is a hostname
+          state_cmd.concat(["-host", resource.host])
+        end
+
+        state_cmd.concat(["export", resource.domain, "-"])
+        state_cmd
       end
 
       action :write do
-        description "Write the setting to the specified domain"
-
-        unless current_resource.is_set
-          cmd = ["defaults write"]
-          cmd.unshift("sudo") if new_resource.sudo
-
-          cmd << if new_resource.global
-                   "NSGlobalDomain"
-                 else
-                   "'#{new_resource.domain}'"
-                 end
-
-          cmd << "'#{new_resource.key}'" if new_resource.key
-          value = new_resource.value
-          type = new_resource.type.empty? ? value_type(value) : new_resource.type
-          # creates a string of Key1 Value1 Key2 Value2...
-          value = value.map { |k, v| "\"#{k}\" \"#{v}\"" }.join(" ") if type == "dict"
-          if type == "array"
-            value = value.join("' '")
-            value = "'#{value}'"
-          end
-          cmd << "-#{type}" if type
-          cmd << value
+        description "Write the value to the specified domain/key."
 
-          # FIXME: this should use cmd directly as an array argument, but then the quoting
-          # of individual args above needs to be removed as well.
-          execute cmd.join(" ") do
-            user new_resource.user unless new_resource.user.nil?
-          end
+        converge_if_changed do
+          cmd = defaults_modify_cmd
+          Chef::Log.debug("Updating defaults value by shelling out: #{cmd.join(" ")}")
+
+          shell_out!(cmd, user: new_resource.user)
+        end
+      end
+
+      action :delete do
+        description "Delete a key from a domain."
+
+        # if it's not there there's nothing to remove
+        return unless current_resource
+
+        converge_by("delete domain:#{new_resource.domain} key:#{new_resource.key}") do
+
+          cmd = defaults_modify_cmd
+          Chef::Log.debug("Removing defaults key by shelling out: #{cmd.join(" ")}")
+
+          shell_out!(cmd, user: new_resource.user)
         end
       end
 
       action_class do
+        #
+        # The command used to write or delete delete values from domains
+        #
+        # @return [Array] Array representation of defaults command to run
+        #
+        def defaults_modify_cmd
+          cmd = ["/usr/bin/defaults"]
+
+          if new_resource.host == :current
+            cmd.concat(["-currentHost"])
+          elsif new_resource.host # they specified a non-nil value, which is a hostname
+            cmd.concat(["-host", new_resource.host])
+          end
+
+          cmd.concat([action.to_s, new_resource.domain, new_resource.key])
+          cmd.concat(processed_value) if action == :write
+          cmd.prepend("sudo") if new_resource.sudo
+          cmd
+        end
+
+        #
+        # convert the provided value into the format defaults expects
+        #
+        # @return [array] array of values starting with the type if applicable
+        #
+        def processed_value
+          type = new_resource.type || value_type(new_resource.value)
+
+          # when dict this creates an array of values ["Key1", "Value1", "Key2", "Value2" ...]
+          cmd_values = ["-#{type}"]
+
+          case type
+          when "dict"
+            cmd_values.concat(new_resource.value.flatten)
+          when "array"
+            cmd_values.concat(new_resource.value)
+          when "bool"
+            cmd_values.concat(bool_to_defaults_bool(new_resource.value))
+          else
+            cmd_values.concat([new_resource.value])
+          end
+
+          cmd_values
+        end
+
+        #
+        # defaults booleans on the CLI must be 'TRUE' or 'FALSE' so convert various inputs to that
+        #
+        # @param [String, Integer, Boolean] input <description>
+        #
+        # @return [String] TRUE or FALSE
+        #
+        def bool_to_defaults_bool(input)
+          return ["TRUE"] if [true, "TRUE", "1", "true", "YES", "yes"].include?(input)
+          return ["FALSE"] if [false, "FALSE", "0", "false", "NO", "no"].include?(input)
+
+          # make sure it's very clear bad input was given
+          raise ArgumentError, "#{input} cannot be converted to a boolean value for use with Apple's defaults command. Acceptable values are: 'TRUE', 'YES', 'true, 'yes', '0', true, 'FALSE', 'false', 'NO', 'no', '1', or false."
+        end
+
+        #
+        # convert ruby type to defaults type
+        #
+        # @param [Integer, Float, String, TrueClass, FalseClass, Hash, Array] value The value being set
+        #
+        # @return [string, nil] the type value used by defaults or nil if not applicable
+        #
         def value_type(value)
           case value
           when true, false
@@ -133,6 +246,8 @@ class Chef
             "dict"
           when Array
             "array"
+          when String
+            "string"
           end
         end
       end

data/lib/chef/resource/mdadm.rb

@@ -36,7 +36,7 @@ class Chef
 
       property :chunk, Integer,
         default: 16,
-        description: "The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the level property is set to 1)."
+        description: "The chunk size. This property should not be used for a RAID 1 mirrored pair (i.e. when the `level` property is set to `1`)."
 
       property :devices, Array,
         default: lazy { [] },
@@ -63,7 +63,7 @@ class Chef
         description: "An optional property to specify the name of the RAID device if it differs from the resource block's name."
 
       property :layout, String,
-        description: "The RAID5 parity algorithm. Possible values: left-asymmetric (or la), left-symmetric (or ls), right-asymmetric (or ra), or right-symmetric (or rs)."
+        description: "The RAID5 parity algorithm. Possible values: `left-asymmetric` (or `la`), `left-symmetric` (or ls), `right-asymmetric` (or `ra`), or `right-symmetric` (or `rs`)."
 
       action_class do
         def load_current_resource

data/lib/chef/resource/mount.rb

@@ -41,6 +41,7 @@ class Chef
         sensitive: true
 
       property :mount_point, String, name_property: true,
+               coerce: proc { |arg| (arg == "/" || arg.match?(":/$")) ? arg : arg.chomp("/") }, # Removed "/" from the end of str, because it was causing idempotency issue.
                description: "The directory (or path) in which the device is to be mounted. Defaults to the name of the resource block if not provided."
 
       property :device, String, identity: true,
@@ -50,7 +51,7 @@ class Chef
         description: "The type of device: :device, :label, or :uuid",
         coerce: proc { |arg| arg.is_a?(String) ? arg.to_sym : arg },
         default: :device,
-        equal_to: RUBY_PLATFORM =~ /solaris/i ? %i{ device } : %i{ device label uuid }
+        equal_to: RUBY_PLATFORM.match?(/solaris/i) ? %i{ device } : %i{ device label uuid }
 
       # @todo this should get refactored away: https://github.com/chef/chef/issues/7621
       property :mounted, [TrueClass, FalseClass], default: false, skip_docs: true
@@ -65,7 +66,7 @@ class Chef
 
       property :options, [Array, String, nil],
         description: "An array or comma separated list of options for the mount.",
-        coerce: proc { |arg| arg.is_a?(String) ? arg.split(",") : arg },
+        coerce: proc { |arg| mount_options(arg) }, # Please see #mount_options method.
         default: %w{defaults}
 
       property :dump, [Integer, FalseClass],
@@ -84,7 +85,7 @@ class Chef
         description: "Windows only: Use to specify the user name."
 
       property :domain, String,
-        description: "Windows only: Use to specify the domain in which the username and password are located."
+        description: "Windows only: Use to specify the domain in which the `username` and `password` are located."
 
       private
 
@@ -94,6 +95,11 @@ class Chef
         @fstype = nil
       end
 
+      # Returns array of string without leading and trailing whitespace.
+      def mount_options(options)
+        (options.is_a?(String) ? options.split(",") : options).collect(&:strip)
+      end
+
     end
   end
 end

data/lib/chef/resource/notify_group.rb

@@ -15,7 +15,6 @@
 #
 
 require_relative "../resource"
-require_relative "../dist"
 
 class Chef
   class Resource

data/lib/chef/resource/ohai.rb

@@ -19,7 +19,7 @@
 #
 
 require_relative "../resource"
-require_relative "../dist"
+require "chef-utils/dist" unless defined?(ChefUtils::Dist)
 require "ohai" unless defined?(Ohai::System)
 
 class Chef
@@ -29,10 +29,53 @@ class Chef
 
       provides :ohai
 
-      description "Use the **ohai** resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the #{Chef::Dist::CLIENT} run."
+      description "Use the **ohai** resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the #{ChefUtils::Dist::Infra::PRODUCT} run."
+
+      examples <<~DOC
+      Reload All Ohai Plugins
+
+      ```ruby
+      ohai 'reload' do
+        action :reload
+      end
+      ```
+
+      Reload A Single Ohai Plugin
+
+      ```ruby
+      ohai 'reload' do
+        plugin 'ipaddress'
+        action :reload
+      end
+      ```
+
+      Reload Ohai after a new user is created
+
+      ```ruby
+      ohai 'reload_passwd' do
+        action :nothing
+        plugin 'etc'
+      end
+
+      user 'daemon_user' do
+        home '/dev/null'
+        shell '/sbin/nologin'
+        system true
+        notifies :reload, 'ohai[reload_passwd]', :immediately
+      end
+
+      ruby_block 'just an example' do
+        block do
+          # These variables will now have the new values
+          puts node['etc']['passwd']['daemon_user']['uid']
+          puts node['etc']['passwd']['daemon_user']['gid']
+        end
+      end
+      ```
+      DOC
 
       property :plugin, String,
-        description: "The name of an Ohai plugin to be reloaded. If this property is not specified, #{Chef::Dist::PRODUCT} will reload all plugins."
+        description: "Specific Ohai attribute data to reload. This property behaves similar to specifying attributes when running Ohai on the command line and takes the attribute that you wish to reload instead of the actual plugin name. For instance, you can pass `ipaddress` to reload `node['ipaddress']` even though that data comes from the `Network` plugin. If this property is not specified, #{ChefUtils::Dist::Infra::PRODUCT} will reload all plugins."
 
       def load_current_resource
         true

data/lib/chef/resource/ohai_hint.rb

@@ -26,6 +26,39 @@ class Chef
 
       description "Use the **ohai_hint** resource to aid in configuration detection by passing hint data to Ohai."
       introduced "14.0"
+      examples <<~DOC
+      **Create a hint file**
+
+      ```ruby
+      ohai_hint 'example' do
+        content a: 'test_content'
+      end
+      ```
+
+      **Create a hint file with a name that does not match the resource name**
+
+      ```ruby
+      ohai_hint 'example' do
+        hint_name 'custom'
+      end
+      ```
+
+      **Create a hint file that is not loaded at compile time**
+
+      ```ruby
+      ohai_hint 'example' do
+        compile_time false
+      end
+      ```
+
+      **Delete a hint file**
+
+      ```ruby
+      ohai_hint 'example' do
+        action :delete
+      end
+      ```
+      DOC
 
       property :hint_name, String,
         description: "An optional property to set the hint name if it differs from the resource block's name.",