Add skip_docs and default_description to resource propertiesdocs_improvements

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>

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