Merge pull request #9778 from chef/more_and_more_descriptions

Another round of description updates && Docs generator tweaks

19 files changed, 126 insertions, 105 deletions

diff --git a/lib/chef/resource/apt_package.rb b/lib/chef/resource/apt_package.rb
index 9ecbbe9153..369330be9f 100644
--- a/lib/chef/resource/apt_package.rb
+++ b/lib/chef/resource/apt_package.rb
@@ -25,6 +25,35 @@ class Chef
 
       provides :apt_package, target_mode: true
       provides :package, platform_family: "debian", target_mode: true
+      examples <<~DOC
+      **Install a package using package manager**:
+
+      ```ruby
+      apt_package 'name of package' do
+        action :install
+      end
+      ```
+
+      **Install a package without specifying the default action**:
+
+      ```ruby
+      apt_package 'name of package'
+      ```
+
+      **Install multiple packages at once**:
+
+      ```ruby
+      apt_package %(package1 package2 package3)
+      ```
+
+      **Install without using recommend packages as a dependency**
+
+      ```ruby
+      package 'apache2' do
+        options '--no-install-recommends'
+      end
+      ```
+      DOC
 
       description "Use the **apt_package** resource to manage packages on Debian and Ubuntu platforms."
 
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index bee7c265b0..664144619c 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -34,6 +34,10 @@ class Chef
     #    installed
     #  - Runs Gem.clear_paths after the action, ensuring that gem is aware of changes so that it can be required
     #    immediately after it is installed
+
+    require_relative "gem_package"
+    require_relative "../dist"
+
     class ChefGem < Chef::Resource::Package::GemPackage
       unified_mode true
       provides :chef_gem
@@ -45,8 +49,8 @@ class Chef
       property :version, String,
         description: "The version of a package to be installed or upgraded."
 
-      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "Chef's built-in gem binary.",
-                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by the #{Chef::Dist::CLIENT} will be installed.",
+      property :gem_binary, default: "#{RbConfig::CONFIG["bindir"]}/gem", default_description: "The `gem` binary included with #{Chef::Dist::PRODUCT}.",
+                            description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed.",
                             callbacks: {
                  "The chef_gem resource is restricted to the current gem environment, use gem_package to install to other environments." => proc { |v| v == "#{RbConfig::CONFIG["bindir"]}/gem" },
                }
diff --git a/lib/chef/resource/chocolatey_package.rb b/lib/chef/resource/chocolatey_package.rb
index 9d2d7bfffe..e0568e586a 100644
--- a/lib/chef/resource/chocolatey_package.rb
+++ b/lib/chef/resource/chocolatey_package.rb
@@ -25,7 +25,7 @@ class Chef
 
       provides :chocolatey_package
 
-      description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform."
+      description "Use the **chocolatey_package** resource to manage packages using Chocolatey on the Microsoft Windows platform. Note: The Chocolatey package manager is not installed on Windows by default. You will need to install it prior to using this resource by adding the [Chocolatey cookbook](https://supermarket.chef.io/cookbooks/chocolatey/) to your node's run list."
       introduced "12.7"
       examples <<~DOC
         **Install a Chocolatey package**:
diff --git a/lib/chef/resource/cookbook_file.rb b/lib/chef/resource/cookbook_file.rb
index 7a2cb6f236..5981aab194 100644
--- a/lib/chef/resource/cookbook_file.rb
+++ b/lib/chef/resource/cookbook_file.rb
@@ -39,7 +39,8 @@ class Chef
 
       property :cookbook, String,
         description: "The cookbook in which a file is located (if it is not located in the current cookbook).",
-        desired_state: false
+        desired_state: false,
+        default_description: "The current cookbook name"
 
       default_action :create
     end
diff --git a/lib/chef/resource/cron_access.rb b/lib/chef/resource/cron_access.rb
index f995c9b454..f0e5ed64bf 100644
--- a/lib/chef/resource/cron_access.rb
+++ b/lib/chef/resource/cron_access.rb
@@ -28,7 +28,7 @@ class Chef
       provides(:cron_manage) # legacy name @todo in Chef 15 we should { true } this so it wins over the cookbook
 
       introduced "14.4"
-      description "Use the **cron_access** resource to manage the /etc/cron.allow and /etc/cron.deny files."
+      description "Use the **cron_access** resource to manage the /etc/cron.allow and /etc/cron.deny files. Note: This resource previously shipped in the `cron` cookbook as `cron_manage`, which it can still be used as for backwards compatibility with existing Chef Infra Client releases."
       examples <<~DOC
         **Add the mike user to cron.allow**
 
diff --git a/lib/chef/resource/file.rb b/lib/chef/resource/file.rb
index cd848585cf..4816ada504 100644
--- a/lib/chef/resource/file.rb
+++ b/lib/chef/resource/file.rb
@@ -59,10 +59,11 @@ class Chef
                description: "The full path to the file, including the file name and its extension. For example: /files/file.txt. Default value: the name of the resource block. Microsoft Windows: A path that begins with a forward slash (/) will point to the root of the current working directory of the #{Chef::Dist::CLIENT} process. This path can vary from system to system. Therefore, using a path that begins with a forward slash (/) is not recommended."
 
       property :atomic_update, [ TrueClass, FalseClass ], desired_state: false, default: lazy { docker? && special_docker_files?(path) ? false : Chef::Config[:file_atomic_update] },
-               description: "Perform atomic file updates on a per-resource basis. Set to true for atomic file updates. Set to false for non-atomic file updates. This setting overrides file_atomic_update, which is a global setting found in the client.rb file."
+               default_description: "False if modifying /etc/hosts, /etc/hostname, or /etc/resolv.conf within Docker containers. Otherwise default to the client.rb 'file_atomic_update' config value.",
+               description: "Perform atomic file updates on a per-resource basis. Set to true for atomic file updates. Set to false for non-atomic file updates. This setting overrides `file_atomic_update`, which is a global setting found in the `client.rb` file."
 
       property :backup, [ Integer, FalseClass ], desired_state: false, default: 5,
-               description: "The number of backups to be kept in /var/chef/backup (for UNIX- and Linux-based platforms) or C:/chef/backup (for the Microsoft Windows platform). Set to false to prevent backups from being kept."
+               description: "The number of backups to be kept in `/var/chef/backup` (for UNIX- and Linux-based platforms) or `C:/chef/backup` (for the Microsoft Windows platform). Set to `false` to prevent backups from being kept."
 
       property :checksum, [ /^[a-zA-Z0-9]{64}$/, nil ],
         description: "The SHA-256 checksum of the file. Use to ensure that a specific file is used. If the checksum does not match, the file is not used."
diff --git a/lib/chef/resource/gem_package.rb b/lib/chef/resource/gem_package.rb
index 96da7fd513..def92bd34d 100644
--- a/lib/chef/resource/gem_package.rb
+++ b/lib/chef/resource/gem_package.rb
@@ -46,21 +46,21 @@ class Chef
       # FIXME? the array form of installing paths most likely does not work?
       #
       property :source, [ String, Array ],
-        description: "Optional. The URL, or list of URLs, at which the gem package is located. This list is added to the source configured in Chef::Config[:rubygems_url] (see also include_default_source) to construct the complete list of rubygems sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] to their local RubyGems mirror."
+        description: "Optional. The URL, or list of URLs, at which the gem package is located. This list is added to the source configured in `Chef::Config[:rubygems_url]` (see also include_default_source) to construct the complete list of rubygems sources. Users in an 'airgapped' environment should set Chef::Config[:rubygems_url] to their local RubyGems mirror."
 
       property :clear_sources, [ TrueClass, FalseClass, nil ],
-        description: "Set to 'true' to download a gem from the path specified by the `source` property (and not from RubyGems).",
+        description: "Set to `true` to download a gem from the path specified by the `source` property (and not from RubyGems).",
         default: lazy { Chef::Config[:clear_gem_sources] }, desired_state: false
 
       property :gem_binary, String, desired_state: false,
-        description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by the #{Chef::Dist::CLIENT} will be installed."
+        description: "The path of a gem binary to use for the installation. By default, the same version of Ruby that is used by #{Chef::Dist::PRODUCT} will be installed."
 
       property :include_default_source, [ TrueClass, FalseClass, nil ],
-        description: "Set to 'false' to not include 'Chef::Config[:rubygems_url]'' in the sources.",
+        description: "Set to `false` to not include `Chef::Config[:rubygems_url]` in the sources.",
         default: nil, introduced: "13.0"
 
       property :options, [ String, Hash, Array, nil ],
-        description: "Options for the gem install, either a Hash or a String. When a hash is given, the options are passed to Gem::DependencyInstaller.new, and the gem will be installed via the gems API. When a String is given, the gem will be installed by shelling out to the gem command. Using a Hash of options with an explicit gem_binary will result in undefined behavior.",
+        description: "Options for the gem install, either a Hash or a String. When a hash is given, the options are passed to `Gem::DependencyInstaller.new`, and the gem will be installed via the gems API. When a String is given, the gem will be installed by shelling out to the gem command. Using a Hash of options with an explicit gem_binary will result in undefined behavior.",
         desired_state: false
     end
   end
diff --git a/lib/chef/resource/rpm_package.rb b/lib/chef/resource/rpm_package.rb
index bd5eabeefb..3f65e32cef 100644
--- a/lib/chef/resource/rpm_package.rb
+++ b/lib/chef/resource/rpm_package.rb
@@ -27,7 +27,10 @@ class Chef
 
       description "Use the **rpm_package** resource to manage packages using the RPM Package Manager."
 
-      property :allow_downgrade, [ true, false ], default: true, desired_state: false
+      property :allow_downgrade, [ TrueClass, FalseClass ],
+        description: "Allow downgrading a package to satisfy requested version requirements.",
+        default: true,
+        desired_state: false
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/scm/_scm.rb b/lib/chef/resource/scm/_scm.rb
index ddb6619cab..c939246ba1 100644
--- a/lib/chef/resource/scm/_scm.rb
+++ b/lib/chef/resource/scm/_scm.rb
@@ -25,17 +25,18 @@ property :destination, String,
   description: "The location path to which the source is to be cloned, checked out, or exported. Default value: the name of the resource block.",
   name_property: true
 
-property :repository, String
+property :repository, String,
+  description: "The URI of the code repository."
 
 property :revision, String,
   description: "The revision to checkout.",
   default: "HEAD"
 
 property :user, [String, Integer],
-  description: "The system user that should own the checked-out code."
+  description: "The system user that will own the checked-out code."
 
 property :group, [String, Integer],
-  description: "The system group that should own the checked-out code."
+  description: "The system group that will own the checked-out code."
 
 property :timeout, Integer,
   description: "The amount of time (in seconds) to wait before timing out.",
diff --git a/lib/chef/resource/scm/subversion.rb b/lib/chef/resource/scm/subversion.rb
index 328a49072b..14360e9816 100644
--- a/lib/chef/resource/scm/subversion.rb
+++ b/lib/chef/resource/scm/subversion.rb
@@ -38,7 +38,7 @@ class Chef
         default: "--no-auth-cache"
 
       property :svn_info_args, [String, nil, FalseClass],
-        description: "Use when the svn info command is used by the #{Chef::Dist::CLIENT} and arguments need to be passed. The svn_arguments command does not work when the svn info command is used.",
+        description: "Use when the `svn info` command is used by #{Chef::Dist::PRODUCT} and arguments need to be passed. The `svn_arguments` command does not work when the `svn info` command is used.",
         coerce: proc { |v| v == false ? nil : v }, # coerce false to nil
         default: "--no-auth-cache"
 
diff --git a/lib/chef/resource/solaris_package.rb b/lib/chef/resource/solaris_package.rb
index 6a07cede40..c6f5d17ce9 100644
--- a/lib/chef/resource/solaris_package.rb
+++ b/lib/chef/resource/solaris_package.rb
@@ -28,7 +28,7 @@ class Chef
       provides :package, os: "solaris2", platform_family: "nexentacore"
       provides :package, os: "solaris2", platform_family: "solaris2", platform_version: "<= 5.10"
 
-      description "The solaris_package resource is used to manage packages for the Solaris platform."
+      description "Use the **solaris_package** resource to manage packages on the Solaris platform."
 
       property :package_name, String,
         description: "An optional property to set the package name if it differs from the resource block's name.",
diff --git a/lib/chef/resource/sudo.rb b/lib/chef/resource/sudo.rb
index 159291f41e..377e0e432e 100644
--- a/lib/chef/resource/sudo.rb
+++ b/lib/chef/resource/sudo.rb
@@ -88,15 +88,15 @@ class Chef
         default: lazy { [] }
 
       property :setenv, [TrueClass, FalseClass],
-        description: "Determines whether or not to permit preservation of the environment with 'sudo -E'.",
+        description: "Determines whether or not to permit preservation of the environment with `sudo -E`.",
         default: false
 
       property :env_keep_add, Array,
-        description: "An array of strings to add to env_keep.",
+        description: "An array of strings to add to `env_keep`.",
         default: lazy { [] }
 
       property :env_keep_subtract, Array,
-        description: "An array of strings to remove from env_keep.",
+        description: "An array of strings to remove from `env_keep`.",
         default: lazy { [] }
 
       property :visudo_path, String,
diff --git a/lib/chef/resource/swap_file.rb b/lib/chef/resource/swap_file.rb
index a39a05080d..7049b34ea7 100644
--- a/lib/chef/resource/swap_file.rb
+++ b/lib/chef/resource/swap_file.rb
@@ -39,7 +39,7 @@ class Chef
         default: false
 
       property :timeout, Integer,
-        description: "Timeout for 'dd' / 'fallocate' commands.",
+        description: "Timeout for `dd` / `fallocate` commands.",
         default: 600,
         desired_state: false
 
diff --git a/lib/chef/resource/systemd_unit.rb b/lib/chef/resource/systemd_unit.rb
index 031b58f3a7..8bb14be636 100644
--- a/lib/chef/resource/systemd_unit.rb
+++ b/lib/chef/resource/systemd_unit.rb
@@ -52,7 +52,7 @@ class Chef
                description: "The user account that the systemd unit process is run under. The path to the unit for that user would be something like '/etc/systemd/user/sshd.service'. If no user account is specified, the systemd unit will run under a 'system' account, with the path to the unit being something like '/etc/systemd/system/sshd.service'."
 
       property :content, [String, Hash],
-        description: "A string or hash that contains a systemd `unit file <https://www.freedesktop.org/software/systemd/man/systemd.unit.html>`_ definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In #{Chef::Dist::PRODUCT} 14.4 or later, repeatable options can be implemented with an array."
+        description: "A string or hash that contains a systemd [unit file](https://www.freedesktop.org/software/systemd/man/systemd.unit.html) definition that describes the properties of systemd-managed entities, such as services, sockets, devices, and so on. In #{Chef::Dist::PRODUCT} 14.4 or later, repeatable options can be implemented with an array."
 
       property :triggers_reload, [TrueClass, FalseClass],
         description: "Specifies whether to trigger a daemon reload when creating or deleting a unit.",
diff --git a/lib/chef/resource/windows_dfs_folder.rb b/lib/chef/resource/windows_dfs_folder.rb
index 9cf3491654..9724d612e1 100644
--- a/lib/chef/resource/windows_dfs_folder.rb
+++ b/lib/chef/resource/windows_dfs_folder.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsFolder < Chef::Resource
       provides :windows_dfs_folder
 
-      description "The windows_dfs_folder resources creates a folder within dfs as many levels deep as required."
+      description "Use the **windows_dfs_folder** resource to creates a folder within DFS as many levels deep as required."
       introduced "15.0"
 
       property :folder_path, String,
diff --git a/lib/chef/resource/windows_dfs_namespace.rb b/lib/chef/resource/windows_dfs_namespace.rb
index 19e43c8284..1293117e2b 100644
--- a/lib/chef/resource/windows_dfs_namespace.rb
+++ b/lib/chef/resource/windows_dfs_namespace.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsNamespace < Chef::Resource
       provides :windows_dfs_namespace
 
-      description "Creates a share and DFS namespace on the local server."
+      description "Use the **windows_dfs_namespace** resource to creates a share and DFS namespace on a Windows server."
       introduced "15.0"
 
       property :namespace_name, String,
diff --git a/lib/chef/resource/windows_dfs_server.rb b/lib/chef/resource/windows_dfs_server.rb
index 2b9dfdcdd3..cb2bee1234 100644
--- a/lib/chef/resource/windows_dfs_server.rb
+++ b/lib/chef/resource/windows_dfs_server.rb
@@ -23,7 +23,7 @@ class Chef
     class WindowsDfsServer < Chef::Resource
       provides :windows_dfs_server
 
-      description "The windows_dfs_server resource sets system-wide DFS settings."
+      description "Use the **windows_dfs_server** resource to set system-wide DFS settings."
       introduced "15.0"
 
       property :use_fqdn, [TrueClass, FalseClass],
diff --git a/lib/chef/resource/yum_package.rb b/lib/chef/resource/yum_package.rb
index b865fdad03..7db8bcc948 100644
--- a/lib/chef/resource/yum_package.rb
+++ b/lib/chef/resource/yum_package.rb
@@ -151,8 +151,8 @@ class Chef
           end
         }
 
-      property :allow_downgrade, [ true, false ],
-        description: "Downgrade a package to satisfy requested version requirements.",
+      property :allow_downgrade, [ TrueClass, FalseClass ],
+        description: "Allow downgrading a package to satisfy requested version requirements.",
         default: true,
         desired_state: false
 
diff --git a/tasks/docs.rb b/tasks/docs.rb
index cfa937c58d..f0aff0e32a 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -33,10 +33,12 @@ namespace :docs_site do
       text = ""
       text << "#{resource_name} 'name' do\n"
       properties.each do |p|
+        pretty_default = pretty_default(p["default"])
+
         text << "  #{p["name"].ljust(padding_size)}"
         text << friendly_types_list(p["is"])
         text << " # default value: 'name' unless specified" if p["name_property"]
-        text << " # default value: #{pretty_default(p["default"])}" unless pretty_default(p["default"]).nil?
+        text << " # default value: #{pretty_default}" unless pretty_default.nil? || (pretty_default.is_a?(String) && pretty_default.length > 45) # 45 chars is too long for these example blocks
         text << "\n"
       end
       text << "  #{"action".ljust(padding_size)}Symbol # defaults to :#{default_action.first} if not specified\n"
@@ -55,12 +57,16 @@ namespace :docs_site do
     end
 
     def friendly_full_property_list(name, properties)
-      [
+      prop_list = [
         "`#{name}` is the resource.",
         "`name` is the name given to the resource block.",
         "`action` identifies which steps Chef Infra Client will take to bring the node into the desired state.",
-        friendly_property_list(properties),
       ]
+
+      # handle the case where we have no properties
+      prop_list << friendly_property_list(properties) unless properties.empty?
+
+      prop_list
     end
 
     # given an array of properties print out a single comma separated string
@@ -83,8 +89,9 @@ namespace :docs_site do
     end
 
     # given an array of types print out a single comma separated string
-    # handling a nil value that needs to be printed as "nil" and TrueClass/FalseClass
-    # which needs to be "true" and "false"
+    # handling TrueClass/FalseClass which needs to be "true" and "false"
+    # and removing any nil values since those are less types in properties
+    # and more side effects of legacy design
     # @return String
     # TODO:
     # - still does not include nil (?)
@@ -95,41 +102,28 @@ namespace :docs_site do
           "true"
         when "FalseClass"
           "false"
-        when "NilClass", nil
-          "nil"
+        when "NilClass"
+          nil
         else
           x
         end
       end
+      # compact to remove the nil values
       fixed_arr.compact.join(", ")
     end
 
-    # Makes sure the resource name is bolded within the description
-    # @return String
-    def bolded_description(name, description)
-      return nil if description.nil? # handle resources missing descriptions
-
-      # we only want to bold occurences of the resource name in the first 5 words so treat it as an array
-      desc_array = description.split(" ")
-
-      desc_array = desc_array[0..4].map! { |x| name == x ? "**#{x}**" : x } + desc_array[5..-1]
-
-      # strip out notes and return just the description
-      desc_array.join(" ").split("Note: ").first.strip
-    end
-
+    # split out notes from the description field. We didn't design a note syntax so we stick them in there
     def note_text(description)
       return nil if description.nil?
 
-      note = description.split("Note: ")[1]
-      if note
-        <<-HEREDOC
+      description.split("Note: ")[1]
+    end
 
-      .. note::
+    # Returns description without embedded notes that may be present
+    def description_text(description)
+      return nil if description.nil?
 
-      #{note}
-        HEREDOC
-      end
+      description.split(" Note:")[0]
     end
 
     # build the menu entry for this resource
@@ -180,7 +174,7 @@ namespace :docs_site do
         values["required"] = property["required"]
         values["default_value"] = default_val unless default_val.nil?
         values["new_in"] = property["introduced"] unless property["introduced"].nil?
-        values["allowed_values"] = property["equal_to"].join(', ') unless property["equal_to"].empty?
+        values["allowed_values"] = property["equal_to"].join(", ") unless property["equal_to"].empty?
         values["description_list"] = [{ "markdown" => property["description"] }]
         values
       end
@@ -189,85 +183,69 @@ namespace :docs_site do
     def special_properties(name, data)
       properties = {}
 
-      properties["common_resource_functionality_multiple_packages"] =
-        case name
-        when "yum_package", "apt_package", "zypper_package", "homebrew_package", "dnf_package", "pacman_package"
-          true
-        when "package"
-          nil
-        else
-          false
-        end
+      # these package properties support passing arrays for the package name
+      properties["common_resource_functionality_multiple_packages"] = true if %w{yum_package apt_package zypper_package homebrew_package dnf_package pacman_package}.include?(name)
 
-      properties["common_resource_functionality_resources_common_windows_security"] = name == "remote_directory"
+      properties["common_resource_functionality_resources_common_windows_security"] = true if name == "remote_directory"
 
-      properties["cookbook_file_specificity"] = name == "cookbook_file"
+      properties["cookbook_file_specificity"] = true if name == "cookbook_file"
 
-      properties["debug_recipes_chef_shell"] = name == "breakpoint"
+      properties["debug_recipes_chef_shell"] = true if name == "breakpoint"
 
-      properties["handler_custom"] = name == "chef_handler"
+      properties["handler_custom"] = true if name == "chef_handler"
 
-      properties["handler_types"] = name == "chef_handler"
+      properties["handler_types"] = true if name == "chef_handler"
 
-      properties["nameless_apt_update"] = name == "apt_update"
+      properties["nameless_apt_update"] = true if name == "apt_update"
 
-      properties["nameless_build_essential"] = name == "build_essential"
+      properties["nameless_build_essential"] = true if name == "build_essential"
 
-      properties["properties_multiple_packages"] = %w{dnf_package package zypper_package}.include?(name)
+      properties["properties_multiple_packages"] = true if %w{dnf_package package zypper_package}.include?(name)
 
-      properties["properties_resources_common_windows_security"] = %w{cookbook_file file template remote_file directory}.include?(name)
+      properties["properties_resources_common_windows_security"] = true if %w{cookbook_file file template remote_file directory}.include?(name)
 
       properties["properties_shortcode"] =
         case name
-        when "breakpoint"
-          "resource_breakpoint_properties.md"
         when "ohai"
           "resource_ohai_properties.md"
         when "log"
           "resource_log_properties.md"
-        else
-          nil
         end
 
-      properties["ps_credential_helper"] = name == "dsc_script"
+      properties["ps_credential_helper"] = true if name == "dsc_script"
 
-      properties["registry_key"] = name == "registry_key"
+      properties["registry_key"] = true if name == "registry_key"
 
-      properties["remote_directory_recursive_directories"] = name == "remote_directory"
+      properties["remote_directory_recursive_directories"] = true if name == "remote_directory"
 
-      properties["remote_file_prevent_re_downloads"] = name == "remote_file"
+      properties["remote_file_prevent_re_downloads"] =  true if name == "remote_file"
 
-      properties["remote_file_unc_path"] = name == "remote_file"
+      properties["remote_file_unc_path"] = true if name == "remote_file"
 
-      properties["resource_directory_recursive_directories"] = %w{directory remote_directory}.include?(name)
+      properties["resource_directory_recursive_directories"] = true if %w{directory remote_directory}.include?(name)
 
-      properties["resource_package_options"] = name == "package"
+      properties["resource_package_options"] = true if name == "package"
 
-      properties["resources_common_atomic_update"] = %w{cookbook_file file template remote_file}.include?(name)
+      properties["resources_common_atomic_update"] = true if %w{cookbook_file file template remote_file}.include?(name)
 
-      properties["resources_common_guard_interpreter"] = name == "script"
+      properties["resources_common_guard_interpreter"] = true if name == "script"
 
-      properties["resources_common_guards"] = !%w{ruby_block chef_acl chef_environment chef_data_bag chef_mirror chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user package}.include?(name)
+      properties["resources_common_guards"] = true unless %w{ruby_block chef_acl chef_environment chef_data_bag chef_mirror chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user package}.include?(name)
 
-      properties["resources_common_notification"] = !%w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
+      properties["resources_common_notification"] = true unless %w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
 
-      properties["resources_common_properties"] = !%w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
+      properties["resources_common_properties"] = true unless %w{ruby_block chef_acl python chef_environment chef_data_bag chef_mirror perl chef_container chef_client chef_organization remote_file chef_node chef_group breakpoint chef_role registry_key chef_data_bag_item chef_user ruby package}.include?(name)
 
-      properties["ruby_style_basics_chef_log"] = name == "log"
+      properties["ruby_style_basics_chef_log"] = true if name == "log"
 
-      properties["syntax_shortcode"] =
-        case name
-        when "breakpoint"
-          "resource_breakpoint_syntax.md"
-        when "log"
-          "resource_log_syntax.md"
-        else
-          nil
-        end
+      properties["syntax_shortcode"] = "resource_log_syntax.md" if name == "log"
 
-      properties["template_requirements"] = name == "template"
+      properties["template_requirements"] = true if name == "template"
 
-      properties["unit_file_verification"] = name == "systemd_unit"
+      properties["unit_file_verification"] = true if name == "systemd_unit"
+
+      # these packages all provide 'package' depending on OS and we want to inject a warning / note that you can just use 'package' instead
+      properties["notes_resource_based_on_package" ] = true if %w{apt_package bff_package dnf_package homebrew_package ips_package openbsd_package pacman_package portage_package smartos_package solaris_package windows_package yum_package zypper_package}.include?(name)
 
       properties
     end
@@ -289,8 +267,12 @@ namespace :docs_site do
       r["aliases"] = ["/resource_#{name}.html"]
       r["menu"] = build_menu_item(name)
       r["resource_description_list"] = {}
-      r["resource_description_list"] = [{ "markdown" => data["description"] }]
-      r["resource_new_in"] = data["introduced"]
+      r["resource_description_list"] = [{ "markdown" => description_text(data["description"]) }]
+
+      # if the description contained a note then add it
+      r["resource_description_list"] << { "note" => { "markdown" => note_text(data["description"]) } } unless note_text(data["description"]).nil?
+
+      r["resource_new_in"] = data["introduced"] unless data["introduced"].nil?
       r["syntax_full_code_block"] = generate_resource_block(name, properties, data["default_action"])
       r["syntax_properties_list"] = nil
       r["syntax_full_properties_list"] = friendly_full_property_list(name, properties)