Improve the auto-generated docs

Formatting fixes and updates to the text to make the generated text match what's currently on the site.

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

5 files changed, 18 insertions, 14 deletions

diff --git a/lib/chef/resource/ohai.rb b/lib/chef/resource/ohai.rb
index 4dca91daea..164ef22b04 100644
--- a/lib/chef/resource/ohai.rb
+++ b/lib/chef/resource/ohai.rb
@@ -29,7 +29,7 @@ class Chef
       description "Use the ohai resource to reload the Ohai configuration on a node. This allows recipes that change system attributes (like a recipe that adds a user) to refer to those attributes later on during the #{Chef::Dist::CLIENT} run."
 
       property :plugin, String,
-        description: "The name of an Ohai plugin to be reloaded. If this property is not specified, the #{Chef::Dist::CLIENT} will reload all plugins."
+        description: "The name of an Ohai plugin to be reloaded. If this property is not specified, #{Chef::Dist::PRODUCT} will reload all plugins."
 
       default_action :reload
       allowed_actions :reload
diff --git a/lib/chef/resource/ruby_block.rb b/lib/chef/resource/ruby_block.rb
index c0cb4d95e4..4f5c7e4b95 100644
--- a/lib/chef/resource/ruby_block.rb
+++ b/lib/chef/resource/ruby_block.rb
@@ -26,7 +26,7 @@ class Chef
     class RubyBlock < Chef::Resource
       provides :ruby_block, target_mode: true
 
-      description "Use the ruby_block resource to execute Ruby code during a #{Chef::Dist::CLIENT} run."\
+      description "Use the ruby_block resource to execute Ruby code during a #{Chef::Dist::PRODUCT} run."\
                   " Ruby code in the ruby_block resource is evaluated with other resources during"\
                   " convergence, whereas Ruby code outside of a ruby_block resource is evaluated"\
                   " before other resources, as the recipe is compiled."
diff --git a/lib/chef/resource/service.rb b/lib/chef/resource/service.rb
index f04e7b3c9c..dec7209fd0 100644
--- a/lib/chef/resource/service.rb
+++ b/lib/chef/resource/service.rb
@@ -35,7 +35,7 @@ class Chef
 
       # this is a poor API please do not re-use this pattern
       property :supports, Hash, default: { restart: nil, reload: nil, status: nil },
-               description: "A list of properties that controls how the #{Chef::Dist::CLIENT} is to attempt to manage a service: :restart, :reload, :status. For :restart, the init script or other service provider can use a restart command; if :restart is not specified, the #{Chef::Dist::CLIENT} attempts to stop and then start a service. For :reload, the init script or other service provider can use a reload command. For :status, the init script or other service provider can use a status command to determine if the service is running; if :status is not specified, the #{Chef::Dist::CLIENT} attempts to match the service_name against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value: { restart: false, reload: false, status: false } for all platforms (except for the Red Hat platform family, which defaults to { restart: false, reload: false, status: true }.)",
+               description: "A list of properties that controls how #{Chef::Dist::PRODUCT} is to attempt to manage a service: :restart, :reload, :status. For :restart, the init script or other service provider can use a restart command; if :restart is not specified, the #{Chef::Dist::CLIENT} attempts to stop and then start a service. For :reload, the init script or other service provider can use a reload command. For :status, the init script or other service provider can use a status command to determine if the service is running; if :status is not specified, the #{Chef::Dist::CLIENT} attempts to match the service_name against the process table as a regular expression, unless a pattern is specified as a parameter property. Default value: { restart: false, reload: false, status: false } for all platforms (except for the Red Hat platform family, which defaults to { restart: false, reload: false, status: true }.)",
                coerce: proc { |x| x.is_a?(Array) ? x.each_with_object({}) { |i, m| m[i] = true } : x }
 
       property :service_name, String,
diff --git a/lib/chef/resource/windows_ad_join.rb b/lib/chef/resource/windows_ad_join.rb
index 23faa60ee5..c0a84746b5 100644
--- a/lib/chef/resource/windows_ad_join.rb
+++ b/lib/chef/resource/windows_ad_join.rb
@@ -31,7 +31,7 @@ class Chef
       introduced "14.0"
 
       property :domain_name, String,
-        description: "The FQDN of the Active Directory domain to join if it differs from the resource block's name.",
+        description: "An optional property to set the FQDN of the Active Directory domain to join if it differs from the resource block's name.",
         validation_message: "The 'domain_name' property must be a FQDN.",
         regex: /.\../, # anything.anything
         name_property: true
diff --git a/tasks/docs.rb b/tasks/docs.rb
index af35e77701..c4758ba398 100755
--- a/tasks/docs.rb
+++ b/tasks/docs.rb
@@ -156,6 +156,7 @@ namespace :docs_site do
 
         Notifications
         -----------------------------------------------------
+
         ``notifies``
           **Ruby Type:** Symbol, 'Chef::Resource[String]'
 
@@ -167,13 +168,13 @@ namespace :docs_site do
 
         .. tag resources_common_notification_timers
 
-        A timer specifies the point during the Chef Infra Client run at which a notification is run. The following timers are available:
+        A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
 
         ``:before``
            Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
 
         ``:delayed``
-           Default. Specifies that a notification should be queued up, and then executed at the end of the Chef Infra Client run.
+           Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
 
         ``:immediate``, ``:immediately``
            Specifies that a notification should be run immediately, per resource notified.
@@ -216,13 +217,13 @@ namespace :docs_site do
 
         .. tag resources_common_notification_timers
 
-        A timer specifies the point during the Chef Infra Client run at which a notification is run. The following timers are available:
+        A timer specifies the point during a Chef Infra Client run at which a notification is run. The following timers are available:
 
         ``:before``
            Specifies that the action on a notified resource should be run before processing the resource block in which the notification is located.
 
         ``:delayed``
-           Default. Specifies that a notification should be queued up, and then executed at the end of the Chef Infra Client run.
+           Default. Specifies that a notification should be queued up, and then executed at the end of a Chef Infra Client run.
 
         ``:immediate``, ``:immediately``
            Specifies that a notification should be run immediately, per resource notified.
@@ -244,17 +245,20 @@ namespace :docs_site do
 
         .. tag resources_common_guards
 
-        A guard property can be used to evaluate the state of a node during the execution phase of the Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell the Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
+        A guard property can be used to evaluate the state of a node during the execution phase of a Chef Infra Client run. Based on the results of this evaluation, a guard property is then used to tell Chef Infra Client if it should continue executing a resource. A guard property accepts either a string value or a Ruby block value:
 
         * A string is executed as a shell command. If the command returns ``0``, the guard is applied. If the command returns any other value, then the guard property is not applied. String guards in a **powershell_script** run Windows PowerShell commands and may return ``true`` in addition to ``0``.
         * A block is executed as Ruby code that must return either ``true`` or ``false``. If the block returns ``true``, the guard property is applied. If the block returns ``false``, the guard property is not applied.
 
-        A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for the Chef Infra Client to do nothing.
+        A guard property is useful for ensuring that a resource is idempotent by allowing that resource to test for the desired state as it is being executed, and then if the desired state is present, for Chef Infra Client to do nothing.
 
         .. end_tag
+
+        **Properties**
+
         .. tag resources_common_guards_properties
 
-        The following properties can be used to define a guard that is evaluated during the execution phase of the Chef Infra Client run:
+        The following properties can be used to define a guard that is evaluated during the execution phase of a Chef Infra Client run:
 
         ``not_if``
           Prevent a resource from executing when the condition returns ``true``.
@@ -305,7 +309,7 @@ The <%= @name %> resource has the following actions:
 ``:nothing``
    .. tag resources_common_actions_nothing
 
-   This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of the Chef Infra Client run.
+   This resource block does not act unless notified by another resource to take action. Once notified, this resource block either runs immediately or is queued up to run at the end of a Chef Infra Client run.
 
    .. end_tag
 
@@ -317,8 +321,8 @@ The <%= @name %> resource has the following properties:
 ``<%= p['name'] %>``
    **Ruby Type:** <%= friendly_types_list(p['is']) %><% unless pretty_default(p['default']).nil? %> | **Default Value:** ``<%= pretty_default(p['default']) %>``<% end %><% if p['required'] %> | ``REQUIRED``<% end %><% if p['deprecated'] %> | ``DEPRECATED``<% end %><% if p['name_property'] %> | **Default Value:** ``The resource block's name``<% end %>
 
-   <%= p['description'] %>
-<% unless p['introduced'].nil? -%>\n   *New in <%= branded_chef_client_name(@introduced) %> <%= p['introduced'] -%>.*<% end -%>
+<% unless p['description'].nil? %>   <%= p['description'].strip %><% end %>
+<% unless p['introduced'].nil? -%>\n\n   *New in <%= branded_chef_client_name(@introduced) %> <%= p['introduced'] -%>.*\n<% end -%>
 <% end %>
 <% if @properties.empty? %>This resource does not have any properties.\n<% end -%>
 <%= boilerplate_content %>