Merge pull request #7808 from chef/resource_descriptions

Improve resource descriptions for resource documentation automation

24 files changed, 41 insertions, 34 deletions

diff --git a/lib/chef/resource/apt_update.rb b/lib/chef/resource/apt_update.rb
index 04a9407813..680806bc26 100644
--- a/lib/chef/resource/apt_update.rb
+++ b/lib/chef/resource/apt_update.rb
@@ -29,6 +29,7 @@ class Chef
 
       # allow bare apt_update with no name
       property :name, String, default: ""
+
       property :frequency, Integer,
                 description: "Determines how frequently (in seconds) APT repository updates are made. Use this property when the :periodic action is specified.",
                 default: 86_400
diff --git a/lib/chef/resource/build_essential.rb b/lib/chef/resource/build_essential.rb
index 99722b14ed..d9d75fb83b 100644
--- a/lib/chef/resource/build_essential.rb
+++ b/lib/chef/resource/build_essential.rb
@@ -30,7 +30,7 @@ class Chef
 
       property :compile_time, [TrueClass, FalseClass],
                description: "Install the build essential packages at compile time.",
-               default: false
+               default: false, desired_state: false
 
       action :install do
 
diff --git a/lib/chef/resource/cab_package.rb b/lib/chef/resource/cab_package.rb
index a90ddc6891..501a0dfa26 100644
--- a/lib/chef/resource/cab_package.rb
+++ b/lib/chef/resource/cab_package.rb
@@ -39,7 +39,7 @@ class Chef
                     uri_scheme?(s) ? s : Chef::Util::PathHelper.canonical_path(s, false)
                   end
                 end),
-                default: lazy { |r| r.package_name }
+                default: lazy { |r| r.package_name }, default_description: "The package name."
     end
   end
 end
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 0a1b2ef736..6758a0c753 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -36,7 +36,7 @@ class Chef
     class ChefGem < Chef::Resource::Package::GemPackage
       resource_name :chef_gem
 
-      property :gem_binary, default: "#{RbConfig::CONFIG['bindir']}/gem",
+      property :gem_binary, default: "#{RbConfig::CONFIG['bindir']}/gem", default_description: "Chef's built-in gem binary.",
                             description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by the chef-client will be installed.",
                             callbacks: {
                  "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG['bindir']}/gem" },
diff --git a/lib/chef/resource/cookbook_file.rb b/lib/chef/resource/cookbook_file.rb
index 0caa9d0553..c96e794469 100644
--- a/lib/chef/resource/cookbook_file.rb
+++ b/lib/chef/resource/cookbook_file.rb
@@ -36,7 +36,8 @@ class Chef
                 default: lazy { ::File.basename(name) }
 
       property :cookbook, String,
-                description: "The cookbook in which a file is located (if it is not located in the current cookbook)."
+                description: "The cookbook in which a file is located (if it is not located in the current cookbook).",
+                desired_state: false
 
       default_action :create
     end
diff --git a/lib/chef/resource/cron_d.rb b/lib/chef/resource/cron_d.rb
index 304a1ad388..a42e3e0246 100644
--- a/lib/chef/resource/cron_d.rb
+++ b/lib/chef/resource/cron_d.rb
@@ -90,7 +90,7 @@ class Chef
                description: "Set the name of the cron job. If this isn't specified we'll use the resource name.",
                name_property: true
 
-      property :cookbook, String
+      property :cookbook, String, desired_state: false
 
       property :predefined_value, String,
                description: 'Schedule your cron job with one of the special predefined value instead of ** * pattern. This correspond to "@reboot", "@yearly", "@annually", "@monthly", "@weekly", "@daily", "@midnight" or "@hourly".',
diff --git a/lib/chef/resource/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 17645e519b..cd2f0b5c3a 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -48,12 +48,12 @@ class Chef
 
       property :volumes_dir, String,
                description: "The Directory under /Volumes where the dmg is mounted as not all dmgs are mounted into a /Volumes location matching the name of the dmg.",
-               default: lazy { |r| r.app }
+               default: lazy { |r| r.app }, default_description: "The value passed for the application name."
 
       property :dmg_name, String,
                description: "The name of the dmg if it is not the same as app, or if the name has spaces.",
                desired_state: false,
-               default: lazy { |r| r.app }
+               default: lazy { |r| r.app }, default_description: "The value passed for the application name."
 
       property :type, String,
                description: "The type of package.",
diff --git a/lib/chef/resource/execute.rb b/lib/chef/resource/execute.rb
index 1becbf50a7..e74d0c1439 100644
--- a/lib/chef/resource/execute.rb
+++ b/lib/chef/resource/execute.rb
@@ -62,7 +62,7 @@ class Chef
                description: "Prevent a command from creating a file when that file already exists."
 
       property :cwd, String,
-               description: "Set the current working directory before running a command."
+               description: "The current working directory from which the command will be run."
 
       property :environment, Hash,
                description: "Specify a Hash of environment variables to be set."
@@ -100,7 +100,7 @@ class Chef
       # lazy used to set default value of sensitive to true if password is set
       property :sensitive, [ TrueClass, FalseClass ],
                description: "Ensure that sensitive resource data is not logged by the chef-client.",
-               default: lazy { |r| r.password ? true : false }
+               default: lazy { |r| r.password ? true : false }, default_description: "True if the password property is set. False otherwise."
 
       property :elevated, [ TrueClass, FalseClass ], default: false,
                description: "Determines whether the script will run with elevated permissions to circumvent User Access Control (UAC) interactively blocking the process.\nThis will cause the process to be run under a batch login instead of an interactive login. The user running Chef needs the “Replace a process level token” and “Adjust Memory Quotas for a process” permissions. The user that is running the command needs the “Log on as a batch job” permission.\nBecause this requires a login, the user and password properties are required.",
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index cac20f2356..8db15fc661 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -66,7 +66,7 @@ class Chef
       property :content, [ String, nil ], desired_state: false,
                description: "A string that is written to the file. The contents of this property replace any previous content when this property has something other than the default value. The default behavior will not modify content."
 
-      property :diff, [ String, nil ], desired_state: false
+      property :diff, [ String, nil ], desired_state: false, skip_docs: true
 
       property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false,
                description: "How the chef-client handles certain situations when the target file turns out not to be a file. For example, when a target file is actually a symlink. Set to true for the chef-client delete the non-file target and replace it with the specified file. Set to false for the chef-client to raise an error."
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 30446fbead..37106efd74 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -32,7 +32,7 @@ class Chef
 
       property :compile_time, [ TrueClass, FalseClass ],
                description: "Determines whether or not the resource shoul be run at compile time.",
-               default: true
+               default: true, desired_state: false
 
       property :ipaddress, String,
                description: "The IP address to use when configuring the hosts file.",
diff --git a/lib/chef/resource/locale.rb b/lib/chef/resource/locale.rb
index 443e682c47..ca6ea510c0 100644
--- a/lib/chef/resource/locale.rb
+++ b/lib/chef/resource/locale.rb
@@ -28,6 +28,7 @@ class Chef
       property :lang, String,
                default: "en_US.utf8",
                description: "Sets the default system language."
+
       property :lc_all, String,
                default: "en_US.utf8",
                description: "Sets the fallback system language."
diff --git a/lib/chef/resource/mdadm.rb b/lib/chef/resource/mdadm.rb
index 3fc5b7c338..ee0284ec37 100644
--- a/lib/chef/resource/mdadm.rb
+++ b/lib/chef/resource/mdadm.rb
@@ -40,9 +40,10 @@ class Chef
                default: lazy { [] },
                description: "The devices to be part of a RAID array."
 
+      # @todo this should get refactored away
       property :exists, [ TrueClass, FalseClass ],
                default: false,
-               description: "Indicates whether the RAID array exists."
+               skip_docs: true
 
       property :level, Integer,
                default: 1,
diff --git a/lib/chef/resource/mount.rb b/lib/chef/resource/mount.rb
index 71e23c8cdb..4c20a62cf8 100644
--- a/lib/chef/resource/mount.rb
+++ b/lib/chef/resource/mount.rb
@@ -50,7 +50,7 @@ class Chef
                equal_to: RUBY_PLATFORM =~ /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
+      property :mounted, [TrueClass, FalseClass], default: false, skip_docs: true
 
       property :fsck_device, String,
                description: "Solaris only: The fsck device.",
diff --git a/lib/chef/resource/powershell_package.rb b/lib/chef/resource/powershell_package.rb
index 60aabb9fd0..28dabc82b0 100644
--- a/lib/chef/resource/powershell_package.rb
+++ b/lib/chef/resource/powershell_package.rb
@@ -45,7 +45,7 @@ class Chef
 
       property :skip_publisher_check, [true, false],
                description: "Skip validating module author.",
-               default: false, introduced: "14.3"
+               default: false, introduced: "14.3", desired_state: false
 
     end
   end
diff --git a/lib/chef/resource/remote_directory.rb b/lib/chef/resource/remote_directory.rb
index f03b13ef02..b9f701ee6d 100644
--- a/lib/chef/resource/remote_directory.rb
+++ b/lib/chef/resource/remote_directory.rb
@@ -56,8 +56,8 @@ class Chef
       property :source, String, default: lazy { ::File.basename(path) }
       property :files_backup, [ Integer, FalseClass ], default: 5, desired_state: false
       property :purge, [ TrueClass, FalseClass ], default: false, desired_state: false
-      property :overwrite, [ TrueClass, FalseClass ], default: true
-      property :cookbook, String
+      property :overwrite, [ TrueClass, FalseClass ], default: true, desired_state: false
+      property :cookbook, String, desired_state: false
 
       def files_group(arg = nil)
         set_or_return(
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index c417a4d26c..5b70ffa22d 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -37,7 +37,7 @@ class Chef
       # acording to the sudo man pages sudo will ignore files in an include dir that have a `.` or `~`
       # We convert either to `__`
       property :filename, String,
-               description: "The name of the sudoers.d file.",
+               description: "The name of the sudoers.d file, if it differs from the name of the resource block",
                name_property: true,
                coerce: proc { |x| x.gsub(/[\.~]/, "__") }
 
@@ -99,15 +99,15 @@ class Chef
                default: lazy { [] }
 
       property :visudo_path, String,
-               description: "Deprecated property. Do not use."
+               deprecated: true
 
       property :visudo_binary, String,
                description: "The path to visudo for configuration verification.",
                default: "/usr/sbin/visudo"
 
       property :config_prefix, String,
-               description: "The directory that contains the sudoers configuration file",
-               default: lazy { platform_config_prefix }
+               description: "The directory that contains the sudoers configuration file.",
+               default: lazy { platform_config_prefix }, default_description: "Prefix values based on the node's platform"
 
       # handle legacy cookbook property
       def after_created
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index c42c7b6d59..87920e3d9b 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :path, String,
-               description: "The path to put the swap file on the system.",
+               description: "The path where the swap file will be created on the system, if it differs from the resource block name.",
                name_property: true
 
       property :size, Integer,
diff --git a/lib/chef/resource/sysctl.rb b/lib/chef/resource/sysctl.rb
index 10d6177221..643ceb233a 100644
--- a/lib/chef/resource/sysctl.rb
+++ b/lib/chef/resource/sysctl.rb
@@ -33,7 +33,7 @@ class Chef
       introduced "14.0"
 
       property :key, String,
-               description: "The kernel parameter key in dotted format.",
+               description: "The kernel parameter key in dotted format, if it differs from the resource block name.",
                name_property: true
 
       property :ignore_error, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index fe4d88ccd2..a7508660f7 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -38,10 +38,10 @@ class Chef
                       :reload_or_try_restart
 
       # Internal provider-managed properties
-      property :enabled, [TrueClass, FalseClass]
-      property :active, [TrueClass, FalseClass]
-      property :masked, [TrueClass, FalseClass]
-      property :static, [TrueClass, FalseClass]
+      property :enabled, [TrueClass, FalseClass], skip_docs: true
+      property :active, [TrueClass, FalseClass], skip_docs: true
+      property :masked, [TrueClass, FalseClass], skip_docs: true
+      property :static, [TrueClass, FalseClass], skip_docs: true
 
       # User-provided properties
       property :user, String, desired_state: false
diff --git a/lib/chef/resource/windows_ad_join.rb b/lib/chef/resource/windows_ad_join.rb
index cb0f43e9d1..645dab5ad0 100644
--- a/lib/chef/resource/windows_ad_join.rb
+++ b/lib/chef/resource/windows_ad_join.rb
@@ -58,7 +58,7 @@ class Chef
 
       # define this again so we can default it to true. Otherwise failures print the password
       property :sensitive, [TrueClass, FalseClass],
-               default: true
+               default: true, desired_state: false
 
       action :join do
         description "Join the Active Directory domain."
diff --git a/lib/chef/resource/windows_printer.rb b/lib/chef/resource/windows_printer.rb
index 7d596a9691..1b9047a222 100644
--- a/lib/chef/resource/windows_printer.rb
+++ b/lib/chef/resource/windows_printer.rb
@@ -61,7 +61,7 @@ class Chef
                regex: Resolv::IPv4::Regex
 
       property :exists, [TrueClass, FalseClass],
-               desired_state: true
+               skip_docs: true
 
       PRINTERS_REG_KEY = 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Print\Printers\\'.freeze unless defined?(PRINTERS_REG_KEY)
 
diff --git a/lib/chef/resource/windows_printer_port.rb b/lib/chef/resource/windows_printer_port.rb
index 3d54c72f47..07f0778d9b 100644
--- a/lib/chef/resource/windows_printer_port.rb
+++ b/lib/chef/resource/windows_printer_port.rb
@@ -56,7 +56,7 @@ class Chef
                default: 1, equal_to: [1, 2]
 
       property :exists, [TrueClass, FalseClass],
-               desired_state: true
+               skip_docs: true
 
       PORTS_REG_KEY = 'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Print\Monitors\Standard TCP/IP Port\Ports\\'.freeze unless defined?(PORTS_REG_KEY)
 
diff --git a/lib/chef/resource/windows_workgroup.rb b/lib/chef/resource/windows_workgroup.rb
index 229afa2e8e..f8391a88cd 100644
--- a/lib/chef/resource/windows_workgroup.rb
+++ b/lib/chef/resource/windows_workgroup.rb
@@ -36,20 +36,22 @@ class Chef
                name_property: true
 
       property :user, String,
-               description: "The local administrator user to use to change the workgroup."
+               description: "The local administrator user to use to change the workgroup.",
+               desired_state: false
 
       property :password, String,
-               description: "The password for the local administrator user."
+               description: "The password for the local administrator user.",
+               desired_state: false
 
       property :reboot, Symbol,
                equal_to: [:immediate, :delayed, :never, :request_reboot, :reboot_now],
                validation_message: "The reboot property accepts :immediate (reboot as soon as the resource completes), :delayed (reboot once the Chef run completes), and :never (Don't reboot)",
                description: "Controls the system reboot behavior post workgroup joining. Reboot immediately, after the Chef run completes, or never. Note that a reboot is necessary for changes to take effect.",
-               default: :immediate
+               default: :immediate, desired_state: false
 
       # define this again so we can default it to true. Otherwise failures print the password
       property :sensitive, [TrueClass, FalseClass],
-               default: true
+               default: true, desired_state: false
 
       action :join do
         description "Update the workgroup."
diff --git a/lib/chef/resource/zypper_repository.rb b/lib/chef/resource/zypper_repository.rb
index b3e1db6b83..e4db20d446 100644
--- a/lib/chef/resource/zypper_repository.rb
+++ b/lib/chef/resource/zypper_repository.rb
@@ -85,7 +85,8 @@ class Chef
                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."
+               description: "The cookbook to source the repository template file from. Only necessary if you're not using the built in template.",
+               desired_state: false
 
       property :gpgautoimportkeys, [TrueClass, FalseClass],
                description: "Automatically import the specified key when setting up the repository.",