Improve descriptions

Signed-off-by: Tim Smith <tsmith@chef.io>

5 files changed, 12 insertions, 7 deletions

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/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/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/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/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