Update documentation and add a Test Kitchen test

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

2 files changed, 31 insertions, 1 deletions

diff --git a/kitchen-tests/cookbooks/end_to_end/recipes/default.rb b/kitchen-tests/cookbooks/end_to_end/recipes/default.rb
index 901c0aa63d..f6639f2dd1 100644
--- a/kitchen-tests/cookbooks/end_to_end/recipes/default.rb
+++ b/kitchen-tests/cookbooks/end_to_end/recipes/default.rb
@@ -9,6 +9,8 @@ hostname "chef-bk-ci.chef.io"
 
 apt_update
 
+chef_sleep '2'
+
 timezone "UTC"
 
 include_recipe "ubuntu" if platform?("ubuntu")
diff --git a/lib/chef/resource/chef_sleep.rb b/lib/chef/resource/chef_sleep.rb
index 6ae70c1f31..c1f31e3fe1 100644
--- a/lib/chef/resource/chef_sleep.rb
+++ b/lib/chef/resource/chef_sleep.rb
@@ -25,8 +25,36 @@ class Chef
 
       unified_mode true
 
-      description "Use the chef_sleep resource to sleep for a number of seconds during a #{Chef::Dist::PRODUCT} run."
+      description "Use the chef_sleep resource to sleep for a number of seconds during a #{Chef::Dist::PRODUCT} run. This resource should only be used when a command or service exits successfuly , but is not fully ready for the next step of the recipe."
       introduced "15.5"
+      examples <<~DOC
+        Sleep for 10 seconds
+        ```ruby
+        chef_sleep '10'
+        ```
+
+        Sleep for 10 seconds with a friendly resource name for logging
+        ```ruby
+        chef_sleep 'wait for the service to start' do
+          seconds 10
+        end
+        ````
+
+        Use a notify from another resource to sleep only when necessary
+        ```ruby
+        service 'Service that is slow to start and reports as started' do
+          service_name 'my_database'
+          action :start
+          notifies :sleep, chef_sleep['wait for service start']
+        end
+
+        chef_sleep 'wait for service start' do
+          seconds 30
+          action :nothing
+        end
+        ```
+      DOC
+
 
       property :seconds, [String, Integer],
         description: "The number of seconds to sleep.",