diff options
author | Tim Smith <tsmith@chef.io> | 2018-10-28 21:36:28 -0700 |
---|---|---|
committer | Tim Smith <tsmith@chef.io> | 2018-10-28 21:39:45 -0700 |
commit | 51296dde0d9c0731d05a1e7f1fba1bbf9036b14b (patch) | |
tree | e193a032e67ccef9264b5818b37bd8254cbae3e6 | |
parent | f343740fbd93812ed9b247b8a7752372ee0ae1fc (diff) | |
download | chef-51296dde0d9c0731d05a1e7f1fba1bbf9036b14b.tar.gz |
Add skip_docs and default_description to resource propertiesdocumentation_enhancements
skip_docs is used to specify a property that we don't want to include in the documentation. We have several of these.
default_description is used to describe the default in a way we'd want to put on the docs site. This is particularly useful for describing all our lazy / computed values.
I've used both of these in resources to show how I think we'll use them.
Signed-off-by: Tim Smith <tsmith@chef.io>
-rw-r--r-- | lib/chef/property.rb | 26 | ||||
-rw-r--r-- | lib/chef/resource.rb | 19 | ||||
-rw-r--r-- | lib/chef/resource/apt_repository.rb | 2 | ||||
-rw-r--r-- | lib/chef/resource/macos_userdefaults.rb | 3 | ||||
-rw-r--r-- | lib/chef/resource_inspector.rb | 6 |
5 files changed, 48 insertions, 8 deletions
diff --git a/lib/chef/property.rb b/lib/chef/property.rb index 0d7b0f06cf..aee3080dc0 100644 --- a/lib/chef/property.rb +++ b/lib/chef/property.rb @@ -103,6 +103,10 @@ class Chef # be run in the context of the instance (and able to access other # properties) and cached. If not, the value will be frozen with Object#freeze # to prevent users from modifying it in an instance. + # @option options [String] :default_description The description of the default value + # used in docs. Particularly useful when a default is computed or lazily eval'd. + # @option options [Boolean] :skip_docs This property should not be included in any + # documentation output # @option options [Proc] :coerce A proc which will be called to # transform the user input to canonical form. The value is passed in, # and the transformed value returned as output. Lazy values will *not* @@ -230,6 +234,15 @@ class Chef end # + # A desciption of the default value of this property. + # + # @return [String] + # + def default_description + options[:default_description] + end + + # # Whether this is part of the resource's natural identity or not. # # @return [Boolean] @@ -278,6 +291,17 @@ class Chef end # + # Whether this property should be skipped for documentation purposes. + # + # Defaults to false. + # + # @return [Boolean] + # + def skip_docs? + options.fetch(:skip_docs, false) + end + + # # Whether this property is sensitive or not. # # Defaults to false. @@ -295,7 +319,7 @@ class Chef # def validation_options @validation_options ||= options.reject do |k, v| - [:declared_in, :name, :instance_variable_name, :desired_state, :identity, :default, :name_property, :coerce, :required, :nillable, :sensitive, :description, :introduced, :deprecated].include?(k) + [:declared_in, :name, :instance_variable_name, :desired_state, :identity, :default, :name_property, :coerce, :required, :nillable, :sensitive, :description, :introduced, :deprecated, :default_description, :skip_docs].include?(k) end end diff --git a/lib/chef/resource.rb b/lib/chef/resource.rb index 5222dc7286..c857d76c02 100644 --- a/lib/chef/resource.rb +++ b/lib/chef/resource.rb @@ -131,6 +131,7 @@ class Chef @only_if = [] @source_line = nil @deprecated = false + @skip_docs = false # We would like to raise an error when the user gives us a guard # interpreter and a ruby_block to the guard. In order to achieve this # we need to understand when the user overrides the default guard @@ -1183,8 +1184,8 @@ class Chef # Internal Resource Interface (for Chef) # - FORBIDDEN_IVARS = [:@run_context, :@logger, :@not_if, :@only_if, :@enclosing_provider, :@description, :@introduced, :@examples, :@validation_message, :@deprecated].freeze - HIDDEN_IVARS = [:@allowed_actions, :@resource_name, :@source_line, :@run_context, :@logger, :@name, :@not_if, :@only_if, :@elapsed_time, :@enclosing_provider, :@description, :@introduced, :@examples, :@validation_message, :@deprecated].freeze + FORBIDDEN_IVARS = [:@run_context, :@logger, :@not_if, :@only_if, :@enclosing_provider, :@description, :@introduced, :@examples, :@validation_message, :@deprecated, :@default_description, :@skip_docs].freeze + HIDDEN_IVARS = [:@allowed_actions, :@resource_name, :@source_line, :@run_context, :@logger, :@name, :@not_if, :@only_if, :@elapsed_time, :@enclosing_provider, :@description, :@introduced, :@examples, :@validation_message, :@deprecated, :@default_description, :@skip_docs].freeze include Chef::Mixin::ConvertToClassName extend Chef::Mixin::ConvertToClassName @@ -1448,6 +1449,20 @@ class Chef @deprecated end + def self.skip_docs(skip_docs = "NOT_PASSED") + if skip_docs != "NOT_PASSED" + @skip_docs = skip_docs + end + @skip_docs + end + + def self.default_description(default_description = "NOT_PASSED") + if default_description != "NOT_PASSED" + @default_description = default_description + end + @default_description + end + # # The cookbook in which this Resource was defined (if any). # diff --git a/lib/chef/resource/apt_repository.rb b/lib/chef/resource/apt_repository.rb index 7ff337ec7c..9a7632cde9 100644 --- a/lib/chef/resource/apt_repository.rb +++ b/lib/chef/resource/apt_repository.rb @@ -43,7 +43,7 @@ class Chef 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: lazy { node["lsb"]["codename"] }, default_description: "The LSB codename of the host such as 'bionic'." property :components, Array, description: "Package groupings, such as 'main' and 'stable'.", diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb index 9c1acc3334..5eed3f8648 100644 --- a/lib/chef/resource/macos_userdefaults.rb +++ b/lib/chef/resource/macos_userdefaults.rb @@ -58,7 +58,8 @@ class Chef # @todo this should get refactored away: https://github.com/chef/chef/issues/7622 property :is_set, [TrueClass, FalseClass], default: false, - desired_state: false + desired_state: false, + skip_docs: true # 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 diff --git a/lib/chef/resource_inspector.rb b/lib/chef/resource_inspector.rb index 7363aad2a6..1a49f05b72 100644 --- a/lib/chef/resource_inspector.rb +++ b/lib/chef/resource_inspector.rb @@ -46,9 +46,9 @@ module ResourceInspector data[:preview] = resource.preview_resource properties = unless complete - resource.properties.reject { |_, k| k.options[:declared_in] == Chef::Resource } + resource.properties.reject { |_, k| k.options[:declared_in] == Chef::Resource || k.options[:skip_docs] } else - resource.properties + resource.properties.reject { |_, k| k.options[:skip_docs] } end data[:properties] = properties.each_with_object([]) do |(n, k), acc| @@ -57,7 +57,7 @@ module ResourceInspector introduced: opts[:introduced], is: opts[:is], deprecated: opts[:deprecated] || false, required: opts[:required] || false, - default: get_default(opts[:default]), + default: opts[:default_description] || get_default(opts[:default]), name_property: opts[:name_property] || false } end data |