Merge pull request #9923 from chef/docs_updates

Update & add resource descriptions for documentation generation

9 files changed, 45 insertions, 34 deletions

diff --git a/lib/chef/provider/remote_file/http.rb b/lib/chef/provider/remote_file/http.rb
index ef7398f756..67a8fe803d 100644
--- a/lib/chef/provider/remote_file/http.rb
+++ b/lib/chef/provider/remote_file/http.rb
@@ -138,7 +138,7 @@ class Chef
             opts[:ssl_verify_mode] = case new_resource.ssl_verify_mode
                                      when :verify_none
                                        Chef::HTTP::VerifyNoneSSLPolicy
-                                     else :verify_peer
+                                     when :verify_peer
                                        Chef::HTTP::VerifyPeerSSLPolicy
                                      end
           end
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index 59e917fbc4..eacddd02af 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -76,7 +76,7 @@ class Chef
       property :diff, [ String, nil ], desired_state: false, skip_docs: true
 
       property :force_unlink, [ TrueClass, FalseClass ], desired_state: false, default: false,
-        description: "How #{Chef::Dist::PRODUCT} 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 #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to false for #{Chef::Dist::PRODUCT} to raise an error."
+        description: "How #{Chef::Dist::PRODUCT} 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 #{Chef::Dist::PRODUCT} to delete the non-file target and replace it with the specified file. Set to `false` for #{Chef::Dist::PRODUCT} to raise an error."
 
       property :manage_symlink_source, [ TrueClass, FalseClass ], desired_state: false,
         description: "Change the behavior of the file resource if it is pointed at a symlink. When this value is set to true, #{Chef::Dist::PRODUCT} will manage the symlink's permissions or will replace the symlink with a normal file if the resource has content. When this value is set to false, #{Chef::Dist::PRODUCT} will follow the symlink and will manage the permissions and content of symlink's target file. The default behavior is true but emits a warning that the default value will be changed to false in a future version; setting this explicitly to true or false suppresses this warning."
diff --git a/lib/chef/resource/homebrew_update.rb b/lib/chef/resource/homebrew_update.rb
index 824d327b67..36dcda810d 100644
--- a/lib/chef/resource/homebrew_update.rb
+++ b/lib/chef/resource/homebrew_update.rb
@@ -30,7 +30,7 @@ class Chef
       description "Use the **homebrew_update** resource to manage Homebrew repository updates on MacOS."
       introduced "16.2"
       examples <<~DOC
-        **Update the Apt repository at a specified interval**:
+        **Update the homebrew repository data at a specified interval**:
         ```ruby
         homebrew_update 'all platforms' do
           frequency 86400
@@ -76,7 +76,7 @@ class Chef
           end
 
           execute "brew update" do
-            command [ "brew", "update" ]
+            command %w{brew update}
             default_env true
             user Homebrew.owner
             notifies :touch, "file[#{BREW_STAMP}]", :immediately
diff --git a/lib/chef/resource/remote_file.rb b/lib/chef/resource/remote_file.rb
index 965301411a..1641855ebb 100644
--- a/lib/chef/resource/remote_file.rb
+++ b/lib/chef/resource/remote_file.rb
@@ -22,6 +22,7 @@ require_relative "file"
 require_relative "../provider/remote_file"
 require_relative "../mixin/securable"
 require_relative "../mixin/uris"
+require_relative "../dist"
 
 class Chef
   class Resource
@@ -31,7 +32,7 @@ class Chef
 
       provides :remote_file
 
-      description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the file resource."
+      description "Use the **remote_file** resource to transfer a file from a remote location using file specificity. This resource is similar to the **file** resource. Note: Fetching files from the `files/` directory in a cookbook should be done with the **cookbook_file** resource."
 
       def initialize(name, run_context = nil)
         super
@@ -72,7 +73,8 @@ class Chef
         end
       end
 
-      property :checksum, String
+      property :checksum, String,
+        description: "Optional, see `use_conditional_get`. 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."
 
       # Disable or enable ETag and Last Modified conditional GET. Equivalent to
       #   use_etag(true_or_false)
@@ -82,28 +84,39 @@ class Chef
         use_last_modified(true_or_false)
       end
 
-      property :use_etag, [ TrueClass, FalseClass ], default: true
+      property :use_etag, [ TrueClass, FalseClass ], default: true,
+        description: "Enable ETag headers. Set to false to disable ETag headers. To use this setting, `use_conditional_get` must also be set to true."
 
       alias :use_etags :use_etag
 
-      property :use_last_modified, [ TrueClass, FalseClass ], default: true
+      property :use_last_modified, [ TrueClass, FalseClass ], default: true,
+        description: "Enable `If-Modified-Since` headers. Set to `false` to disable `If-Modified-Since` headers. To use this setting, `use_conditional_get` must also be set to `true`."
 
-      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false
+      property :ftp_active_mode, [ TrueClass, FalseClass ], default: false,
+        description: "Whether #{Chef::Dist::PRODUCT} uses active or passive FTP. Set to `true` to use active FTP."
 
-      property :headers, Hash, default: lazy { {} }
+      property :headers, Hash, default: lazy { {} },
+        description: "A Hash of custom HTTP headers."
 
       property :show_progress, [ TrueClass, FalseClass ], default: false
 
-      property :ssl_verify_mode, equal_to: %i{verify_none verify_peer}, default: nil,
-        description: "Optional property to override SSL policy. If not specified, uses the SSL polify from config.rb."
+      property :ssl_verify_mode, Symbol, equal_to: %i{verify_none verify_peer},
+        introduced: "16.2",
+        description: "Optional property to override SSL policy. If not specified, uses the SSL polify from `config.rb`."
 
-      property :remote_user, String
+      property :remote_user, String,
+        introduced: "13.4",
+        description: '**Windows only** The name of a user with access to the remote file specified by the source property. The user name may optionally be specified with a domain, such as: `domain\user` or `user@my.dns.domain.com` via Universal Principal Name (UPN) format. The domain may also be set using the `remote_domain` property. Note that this property is ignored if source is not a UNC path. If this property is specified, the `remote_password` property is required.'
 
-      property :remote_domain, String
+      property :remote_domain, String,
+        introduced: "13.4",
+        description: "**Windows only** The domain of the user specified by the `remote_user` property. By default the resource will authenticate against the domain of the remote system, or as a local account if the remote system is not joined to a domain. If the remote system is not part of a domain, it is necessary to authenticate as a local user on the remote system by setting the domain to `.`, for example: remote_domain '.'. The domain may also be specified as part of the `remote_user` property."
 
-      property :remote_password, String, sensitive: true
+      property :remote_password, String, sensitive: true,
+        introduced: "13.4",
+        description: "**Windows only** The password of the user specified by the `remote_user` property. This property is required if `remote_user` is specified and may only be specified if `remote_user` is specified. The `sensitive` property for this resource will automatically be set to `true` if `remote_password` is specified."
 
-      property :authentication, equal_to: %i{remote local}, default: :remote
+      property :authentication, Symbol, equal_to: %i{remote local}, default: :remote
 
       def after_created
         validate_identity_platform(remote_user, remote_password, remote_domain)
diff --git a/lib/chef/resource/windows_shortcut.rb b/lib/chef/resource/windows_shortcut.rb
index e272e89e16..b5b532cb86 100644
--- a/lib/chef/resource/windows_shortcut.rb
+++ b/lib/chef/resource/windows_shortcut.rb
@@ -34,7 +34,6 @@ class Chef
         description 'Make a shortcut to C:\\original_dir'
       end
       ```
-
       DOC
 
       property :shortcut_name, String,
diff --git a/lib/chef/resource/windows_task.rb b/lib/chef/resource/windows_task.rb
index d73030311e..2dfa22b8ca 100644
--- a/lib/chef/resource/windows_task.rb
+++ b/lib/chef/resource/windows_task.rb
@@ -189,11 +189,11 @@ class Chef
                description: "The frequency with which to run the task."
 
       property :start_day, String,
-        description: "Specifies the first date on which the task runs in MM/DD/YYYY format.",
+        description: "Specifies the first date on which the task runs in **MM/DD/YYYY** format.",
         default_description: "The current date."
 
       property :start_time, String,
-        description: "Specifies the start time to run the task, in HH:mm format."
+        description: "Specifies the start time to run the task, in **HH:mm** format."
 
       property :day, [String, Integer],
         description: "The day(s) on which the task runs."
diff --git a/lib/chef/resource/windows_user_privilege.rb b/lib/chef/resource/windows_user_privilege.rb
index 862a348e68..aeff7ad468 100644
--- a/lib/chef/resource/windows_user_privilege.rb
+++ b/lib/chef/resource/windows_user_privilege.rb
@@ -68,7 +68,7 @@ class Chef
                         }
 
       provides :windows_user_privilege
-      description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege. \n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
+      description "The windows_user_privilege resource allows to add and set principal (User/Group) to the specified privilege.\n Ref: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/user-rights-assignment"
 
       introduced "16.0"
 
@@ -78,7 +78,7 @@ class Chef
       ```ruby
       windows_user_privilege 'Network Logon Rights' do
         privilege      'SeNetworkLogonRight'
-        users          ['BUILTIN\Administrators', 'NT AUTHORITY\Authenticated Users']
+        users          ['BUILTIN\\Administrators', 'NT AUTHORITY\\Authenticated Users']
         action         :set
       end
       ```
@@ -88,7 +88,7 @@ class Chef
       ```ruby
       windows_user_privilege 'Remote interactive logon' do
         privilege      'SeDenyRemoteInteractiveLogonRight'
-        users          ['Builtin\Guests', 'NT AUTHORITY\Local Account']
+        users          ['Builtin\\Guests', 'NT AUTHORITY\\Local Account']
         action         :add
       end
       ```
@@ -98,7 +98,7 @@ class Chef
       ```ruby
       windows_user_privilege 'Create Pagefile' do
         privilege      'SeCreatePagefilePrivilege'
-        users          ['BUILTIN\Guests', 'BUILTIN\Administrators']
+        users          ['BUILTIN\\Guests', 'BUILTIN\\Administrators']
         action         :set
       end
       ```
@@ -108,7 +108,7 @@ class Chef
       ```ruby
       windows_user_privilege 'Create Pagefile' do
         privilege      'SeCreatePagefilePrivilege'
-        users          ['BUILTIN\Guests']
+        users          ['BUILTIN\\Guests']
         action         :remove
       end
       ```
diff --git a/lib/chef/resource/yum_repository.rb b/lib/chef/resource/yum_repository.rb
index 4e23244dfe..3070075959 100644
--- a/lib/chef/resource/yum_repository.rb
+++ b/lib/chef/resource/yum_repository.rb
@@ -95,7 +95,7 @@ class Chef
         description: "URL pointing to the ASCII-armored GPG key file for the repository. This is used if Yum needs a public key to verify a package and the required key hasn't been imported into the RPM database. If this option is set, Yum will automatically import the key from the specified URL. Multiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed.\nMultiple URLs may be specified in the same manner as the baseurl option. If a GPG key is required to install a package from a repository, all keys specified for that repository will be installed."
 
       property :http_caching, String, equal_to: %w{packages all none},
-               description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values: all (all HTTP downloads should be cached), packages (only RPM package downloads should be cached, but not repository metadata downloads), or none (no HTTP downloads should be cached)"
+               description: "Determines how upstream HTTP caches are instructed to handle any HTTP downloads that Yum does. This option can take the following values:\n - `all` means all HTTP downloads should be cached\n - `packages` means only RPM package downloads should be cached, but not repository metadata downloads\n - `none` means no HTTP downloads should be cached.\n\nThe default value of `all` is recommended unless you are experiencing caching related issues."
 
       property :include_config, String,
         description: "An external configuration file using the format `url://to/some/location`."
@@ -114,25 +114,25 @@ class Chef
         description: "Number of times any attempt to retrieve a file should retry before returning an error. Setting this to `0` makes Yum try forever."
 
       property :metadata_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/, /never/],
-               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
-               validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!"
+               description: "Time (in seconds) after which the metadata will expire. If the current metadata downloaded is less than the value specified, then Yum will not update the metadata against the repository. If you find that Yum is not downloading information on updates as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively. The default is six hours to compliment yum-updates running once per hour. It is also possible to use the word `never`, meaning that the metadata will never expire. Note: When using a metalink file, the metalink must always be newer than the metadata for the repository due to the validation, so this timeout also applies to the metalink file.",
+               validation_message: "The metadata_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!"
 
       property :metalink, String,
         description: "Specifies a URL to a metalink file for the repomd.xml, a list of mirrors for the entire repository are generated by converting the mirrors for the repomd.xml file to a baseurl."
 
       property :mirror_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/],
-               description: "Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively.",
-               validation_message: "The mirror_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!"
+               description: "Time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than this many seconds old then Yum will not download another copy of the mirrorlist, it has the same extra format as metadata_expire. If you find that Yum is not downloading the mirrorlists as often as you would like lower the value of this option. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively.",
+               validation_message: "The mirror_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!"
 
       property :mirrorlist_expire, String, regex: [/^\d+$/, /^\d+[mhd]$/],
-               description: "Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist. You can also change from the default of using seconds to using days, hours or minutes by appending a 'd', 'h' or 'm' respectively.",
-               validation_message: "The mirrorlist_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with 'd', 'h', or 'm'!"
+               description: "Specifies the time (in seconds) after which the mirrorlist locally cached will expire. If the current mirrorlist is less than the value specified, then Yum will not download another copy of the mirrorlist. You can also change from the default of using seconds to using days, hours or minutes by appending a `d`, `h` or `m` respectively.",
+               validation_message: "The mirrorlist_expire property must be a numeric value for time in seconds, the string 'never', or a numeric value appended with with `d`, `h`, or `m`!"
 
       property :mirrorlist, String,
         description: "URL to a file containing a list of baseurls. This can be used instead of or with the baseurl option. Substitution variables, described below, can be used with this option."
 
       property :mode, [String, Integer],
-        description: "Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to '600', normal users will not be able to use Yum search, Yum info, etc.",
+        description: "Permissions mode of .repo file on disk. This is useful for scenarios where secrets are in the repo file. If this value is set to `600`, normal users will not be able to use Yum search, Yum info, etc.",
         default: "0644"
 
       property :options, Hash,
@@ -142,7 +142,7 @@ class Chef
         description: "Password to use with the username for basic authentication."
 
       property :priority, String, regex: /^(\d?[1-9]|[0-9][0-9])$/,
-               description: "Assigns a priority to a repository where the priority value is between '1' and '99' inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority.",
+               description: "Assigns a priority to a repository where the priority value is between `1` and `99` inclusive. Priorities are used to enforce ordered protection of repositories. Packages from repositories with a lower priority (higher numerical value) will never be used to upgrade packages that were installed from a repository with a higher priority (lower numerical value). The repositories with the lowest numerical priority number have the highest priority.",
                validation_message: "The priority property must be a numeric value from 1-99!"
 
       property :proxy_password, String,
diff --git a/spec/unit/resource/homebrew_update_spec.rb b/spec/unit/resource/homebrew_update_spec.rb
index f9c2e47f5f..3bf39afe9c 100644
--- a/spec/unit/resource/homebrew_update_spec.rb
+++ b/spec/unit/resource/homebrew_update_spec.rb
@@ -10,7 +10,6 @@ describe Chef::Resource::HomebrewUpdate do
   let(:stamp_file) { Dir.mktmpdir("apt_update_periodic") }
   let(:brew_update_cmd) { %w{homebrew update} }
 
-
   it "sets the default action as :periodic" do
     expect(resource.action).to eql([:periodic])
   end