Add documentation descriptions to multiple resourcesauto-generate-resource-docs

Signed-off-by: Tim Smith <tsmith@chef.io>

4 files changed, 45 insertions, 36 deletions

diff --git a/lib/chef/resource/apt_preference.rb b/lib/chef/resource/apt_preference.rb
index 3432d2241e..9a661ce37d 100644
--- a/lib/chef/resource/apt_preference.rb
+++ b/lib/chef/resource/apt_preference.rb
@@ -43,7 +43,7 @@ class Chef
         required: true
 
       property :pin_priority, [String, Integer],
-        description: "Sets the Pin-Priority for a package.",
+        description: "Sets the Pin-Priority for a package. See <https://wiki.debian.org/AptPreferences> for more details.",
         required: true
 
       default_action :add
diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb
index 75a30146ec..7e56a4b3af 100644
--- a/lib/chef/resource/apt_repository.rb
+++ b/lib/chef/resource/apt_repository.rb
@@ -115,8 +115,8 @@ class Chef
         description: "The base of the Debian distribution."
 
       property :distribution, [ String, nil, FalseClass ],
-        description: "Usually a distribution's codename, such as trusty, xenial or bionic. Default value: the codename of the node's distro.",
-        default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the host such as 'bionic'."
+        description: "Usually a distribution's codename, such as xenial, bionic, or focal.",
+        default: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the node such as 'focal'."
 
       property :components, Array,
         description: "Package groupings, such as 'main' and 'stable'.",
@@ -142,7 +142,7 @@ class Chef
         default: lazy { [] }, coerce: proc { |x| x ? Array(x) : x }
 
       property :key_proxy, [String, nil, FalseClass],
-        description: "If set, a specified proxy is passed to GPG via http-proxy=."
+        description: "If set, a specified proxy is passed to GPG via `http-proxy=`."
 
       property :cookbook, [String, nil, FalseClass],
         description: "If key should be a cookbook_file, specify a cookbook where the key is located for files/default. Default value is nil, so it will use the cookbook where the resource is used.",
diff --git a/lib/chef/resource/windows_firewall_rule.rb b/lib/chef/resource/windows_firewall_rule.rb
index fcba0dc569..0ba4c60a46 100644
--- a/lib/chef/resource/windows_firewall_rule.rb
+++ b/lib/chef/resource/windows_firewall_rule.rb
@@ -26,7 +26,7 @@ class Chef
     class WindowsFirewallRule < Chef::Resource
       provides :windows_firewall_rule
 
-      description "Use the windows_firewall_rule resource to create, change or remove windows firewall rules."
+      description "Use the windows_firewall_rule resource to create, change or remove Windows firewall rules."
       introduced "14.7"
       examples <<~DOC
       Allowing port 80 access
diff --git a/lib/chef/resource/windows_service.rb b/lib/chef/resource/windows_service.rb
index 34f3cfb9a7..3c9a63b86e 100644
--- a/lib/chef/resource/windows_service.rb
+++ b/lib/chef/resource/windows_service.rb
@@ -46,41 +46,47 @@ class Chef
         default: 60,
         desired_state: false
 
-      # The display name to be used by user interface programs to identify the
-      # service. This string has a maximum length of 256 characters.
       property :display_name, String, regex: /^.{1,256}$/,
-               validation_message: "The display_name can only be a maximum of 256 characters!",
-               introduced: "14.0"
+        description: "The display name to be used by user interface programs to identify the service. This string has a maximum length of 256 characters.",
+        validation_message: "The display_name can only be a maximum of 256 characters!",
+        introduced: "14.0"
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L19-L29
-      property :desired_access, Integer, default: SERVICE_ALL_ACCESS
+      property :desired_access, Integer,
+        default: SERVICE_ALL_ACCESS,
+        introduced: "14.0"
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L31-L41
-      property :service_type, Integer, default: SERVICE_WIN32_OWN_PROCESS
+      property :service_type, Integer, default: SERVICE_WIN32_OWN_PROCESS,
+      introduced: "14.0"
 
       # Valid options:
       #   - :automatic
       #   - :manual
       #   - :disabled
       # Reference: https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L49-L54
-      property :startup_type, [Symbol], equal_to: %i{automatic manual disabled}, default: :automatic, coerce: proc { |x|
-        if x.is_a?(Integer)
-          ALLOWED_START_TYPES.invert.fetch(x) do
-            Chef::Log.warn("Unsupported startup_type #{x}, falling back to :automatic")
-            :automatic
+      property :startup_type, [Symbol],
+        equal_to: %i{automatic manual disabled},
+        default: :automatic,
+        description: "Use to specify the startup type of the service.",
+        coerce: proc { |x|
+          if x.is_a?(Integer)
+            ALLOWED_START_TYPES.invert.fetch(x) do
+              Chef::Log.warn("Unsupported startup_type #{x}, falling back to :automatic")
+              :automatic
+            end
+          elsif x.is_a?(String)
+            x.to_sym
+          else
+            x
           end
-        elsif x.is_a?(String)
-          x.to_sym
-        else
-          x
-        end
-      }
-
-      # This only applies if startup_type is :automatic
+        }
+
       # 1 == delayed start is enabled
       # 0 == NO delayed start
       property :delayed_start, [TrueClass, FalseClass],
         introduced: "14.0",
+        description: "Set the startup type to delayed start. This only applies if `startup_type` is `:automatic`",
         default: false, coerce: proc { |x|
           if x.is_a?(Integer)
             x == 0 ? false : true
@@ -90,31 +96,34 @@ class Chef
         }
 
       # https://github.com/chef/win32-service/blob/ffi/lib/win32/windows/constants.rb#L43-L47
-      property :error_control, Integer, default: SERVICE_ERROR_NORMAL
+      property :error_control, Integer,
+        default: SERVICE_ERROR_NORMAL,
+        introduced: "14.0"
 
       property :binary_path_name, String,
         introduced: "14.0",
-        description: "The fully qualified path to the service binary file. The path can also include arguments for an auto-start service. This is required for ':create' and ':configure' actions"
+        description: "The fully qualified path to the service binary file. The path can also include arguments for an auto-start service. This is required for `:create` and `:configure` actions"
 
       property :load_order_group, String,
         introduced: "14.0",
-        description: "The names of the load ordering group of which this service is a member. Don't set this property if the service does not belong to a group."
-
-      # A pointer to a double null-terminated array of null-separated names of
-      # services or load ordering groups that the system must start before this
-      # service. Specify nil or an empty string if the service has no
-      # dependencies. Dependency on a group means that this service can run if
-      # at least one member of the group is running after an attempt to start
-      # all members of the group.
+        description: "The name of the service's load ordering group(s)."
+
       property :dependencies, [String, Array],
+        description: "A pointer to a double null-terminated array of null-separated names of services or load ordering groups that the system must start before this service. Specify `nil` or an empty string if the service has no dependencies. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.",
         introduced: "14.0"
 
       property :description, String,
         description: "Description of the service.",
         introduced: "14.0"
 
-      property :run_as_user, String, default: "localsystem", coerce: proc { |x| x.downcase }
-      property :run_as_password, String, default: ""
+      property :run_as_user, String,
+        description: "The user under which a Microsoft Windows service runs.",
+        default: "localsystem",
+        coerce: proc { |x| x.downcase }
+
+      property :run_as_password, String,
+        description: "The password for the user specified by `run_as_user`.",
+        default: ""
     end
   end
 end