From 2768466e42cb28e0b93d13a1115edc9466660dd4 Mon Sep 17 00:00:00 2001 From: Tim Smith Date: Fri, 24 Apr 2020 13:27:12 -0700 Subject: Add documentation descriptions to multiple resources Signed-off-by: Tim Smith --- lib/chef/resource/apt_preference.rb | 2 +- lib/chef/resource/apt_repository.rb | 6 +-- lib/chef/resource/windows_firewall_rule.rb | 2 +- lib/chef/resource/windows_service.rb | 71 +++++++++++++++++------------- 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 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 9d61990605..51d016a4f2 100644 --- a/lib/chef/resource/windows_service.rb +++ b/lib/chef/resource/windows_service.rb @@ -41,41 +41,47 @@ class Chef allowed_actions :configure_startup, :create, :delete, :configure - # 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 @@ -85,31 +91,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 -- cgit v1.2.1