Merge pull request #7811 from chef/docs_improvements

Automated resource documentation improvements

12 files changed, 65 insertions, 25 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/dmg_package.rb b/lib/chef/resource/dmg_package.rb
index 7442a8f455..f697d8303b 100644
--- a/lib/chef/resource/dmg_package.rb
+++ b/lib/chef/resource/dmg_package.rb
@@ -75,7 +75,7 @@ class Chef
                default: nil
 
       property :allow_untrusted, [TrueClass, FalseClass],
-               description: "Allows packages with untrusted certs to be installed.",
+               description: "Allow installation of packages that do not have trusted certificates.",
                default: false
 
       load_current_value do |new_resource|
diff --git a/lib/chef/resource/group.rb b/lib/chef/resource/group.rb
index fc2c33322b..2f8406faf4 100644
--- a/lib/chef/resource/group.rb
+++ b/lib/chef/resource/group.rb
@@ -36,7 +36,7 @@ class Chef
 
       property :members, [String, Array], default: lazy { [] },
                coerce: proc { |arg| arg.is_a?(String) ? arg.split(/\s*,\s*/) : arg },
-               description: "Which users should be set or appended to a group. This can be either an array or a comma separated list."
+               description: "Which users should be set or appended to a group. When more than one group member is identified, the list of members should be an array: members ['user1', 'user2']."
 
       property :excluded_members, [String, Array], default: lazy { [] },
                coerce: proc { |arg| arg.is_a?(String) ? arg.split(/\s*,\s*/) : arg },
@@ -46,7 +46,7 @@ class Chef
                description: "How members should be appended and/or removed from a group. When true, members are appended and excluded_members are removed. When false, group members are reset to the value of the members property."
 
       property :system, [ TrueClass, FalseClass ], default: false,
-               description: "Sets the group to belong to the system group."
+               description: "Set if a group belongs to a system group. Set to true if the group belongs to a system group."
 
       property :non_unique, [ TrueClass, FalseClass ], default: false,
                description: "Allow gid duplication. May only be used with the Groupadd provider."
diff --git a/lib/chef/resource/homebrew_cask.rb b/lib/chef/resource/homebrew_cask.rb
index 5789570b01..626ae02a69 100644
--- a/lib/chef/resource/homebrew_cask.rb
+++ b/lib/chef/resource/homebrew_cask.rb
@@ -37,7 +37,7 @@ class Chef
                name_property: true
 
       property :options, String,
-               description: "Options to pass to the brew CLI during installation."
+               description: "Options to pass to the brew command during installation."
 
       property :install_cask, [TrueClass, FalseClass],
                description: "Automatically install the Homebrew cask tap, if necessary.",
@@ -48,7 +48,7 @@ class Chef
                default: "/usr/local/bin/brew"
 
       property :owner, String,
-               description: "The owner of the homebrew installation.",
+               description: "The owner of the Homebrew installation.",
                default: lazy { find_homebrew_username }
 
       action :install do
diff --git a/lib/chef/resource/homebrew_tap.rb b/lib/chef/resource/homebrew_tap.rb
index 6f239e9482..20ac0bb5d5 100644
--- a/lib/chef/resource/homebrew_tap.rb
+++ b/lib/chef/resource/homebrew_tap.rb
@@ -38,7 +38,7 @@ class Chef
                name_property: true
 
       property :url, String,
-               description: "URL to the tap."
+               description: "The URL of the tap."
 
       property :full, [TrueClass, FalseClass],
                description: "Perform a full clone on the tap, as opposed to a shallow clone.",
diff --git a/lib/chef/resource/hostname.rb b/lib/chef/resource/hostname.rb
index 23111d0b92..30446fbead 100644
--- a/lib/chef/resource/hostname.rb
+++ b/lib/chef/resource/hostname.rb
@@ -27,7 +27,7 @@ class Chef
       introduced "14.0"
 
       property :hostname, String,
-               description: "Used to specify the hostname if it is different than the resource’s name.",
+               description: "Used to specify the hostname if it is different than the resource's name.",
                name_property: true
 
       property :compile_time, [ TrueClass, FalseClass ],
diff --git a/lib/chef/resource/macos_userdefaults.rb b/lib/chef/resource/macos_userdefaults.rb
index f2ad5a0213..5eed3f8648 100644
--- a/lib/chef/resource/macos_userdefaults.rb
+++ b/lib/chef/resource/macos_userdefaults.rb
@@ -29,11 +29,11 @@ class Chef
       introduced "14.0"
 
       property :domain, String,
-               description: "The domain the defaults belong to.",
+               description: "The domain that the user defaults belong to.",
                required: true
 
       property :global, [TrueClass, FalseClass],
-               description: "Whether the domain is global.",
+               description: "Determines whether or not the domain is global.",
                default: false
 
       property :key, String,
@@ -44,21 +44,22 @@ class Chef
                required: true
 
       property :type, String,
-               description: "Value type of the preference key.",
+               description: "The value type of the preference key.",
                default: ""
 
       property :user, String,
-               description: "User for which to set the default."
+               description: "The system user that the default will be applied to."
 
       property :sudo, [TrueClass, FalseClass],
-               description: "Set to true if the setting requires privileged access to modify.",
+               description: "Set to true if the setting you wish to modify requires privileged access.",
                default: false,
                desired_state: false
 
       # @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/openssl_ec_public_key.rb b/lib/chef/resource/openssl_ec_public_key.rb
index 9b1ded4043..d6900c1ad4 100644
--- a/lib/chef/resource/openssl_ec_public_key.rb
+++ b/lib/chef/resource/openssl_ec_public_key.rb
@@ -27,7 +27,7 @@ class Chef
       preview_resource true
       resource_name :openssl_ec_public_key
 
-      description "Use the openssl_ec_public_key resource to generate elliptic curve (EC) public key files given a private key."
+      description "Use the openssl_ec_public_key resource to generate elliptic curve (EC) public key files from a given EC private key."
       introduced "14.4"
 
       property :path, String,
@@ -38,7 +38,7 @@ class Chef
                description: "The path to the private key file."
 
       property :private_key_content, String,
-               description: "The content of the private key including new lines. This property is used in place of private_key_path to avoid having to first write a key to disk."
+               description: "The content of the private key including new lines. This property is used in place of private_key_path in instances where you want to avoid having to first write the private key to disk"
 
       property :private_key_pass, String,
                description: "The passphrase of the provided private key."
diff --git a/lib/chef/resource/openssl_rsa_public_key.rb b/lib/chef/resource/openssl_rsa_public_key.rb
index c213284235..b9a4924c3e 100644
--- a/lib/chef/resource/openssl_rsa_public_key.rb
+++ b/lib/chef/resource/openssl_rsa_public_key.rb
@@ -26,18 +26,18 @@ class Chef
       resource_name :openssl_rsa_public_key
       provides(:openssl_rsa_public_key) { true }
 
-      description "Use the openssl_rsa_public_key resource to generate RSA public key files given a RSA private key."
+      description "Use the openssl_rsa_public_key resource to generate RSA public key files for a given RSA private key."
       introduced "14.0"
 
       property :path, String,
-               description: "The path to write the file to if different than the resource's name.",
+               description: "The path to the public key file, if it differs from the resource name.",
                name_property: true
 
       property :private_key_path, String,
                description: "The path to the private key file."
 
       property :private_key_content, String,
-               description: "The content of the private key including new lines. This property is used in place of private_key_path to avoid having to first write a key to disk."
+               description: "The content of the private key, including new lines. This property is used in place of private_key_path in instances where you want to avoid having to first write the private key to disk."
 
       property :private_key_pass, String,
                description: "The passphrase of the provided private key."
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