better wait_for docs on timeout (#28344)

* better waitfor docs on timeout

shippable errors unrelated to docs

lib/ansible/modules/utilities/logic/pause.py

@@ -15,14 +15,13 @@ DOCUMENTATION = '''
 module: pause
 short_description: Pause playbook execution
 description:
-  - Pauses playbook execution for a set amount of time, or until a prompt is acknowledged. All parameters are optional. The default behavior is to
+  - Pauses playbook execution for a set amount of time, or until a prompt is acknowledged.
-    pause with a prompt.
+    All parameters are optional. The default behavior is to pause with a prompt.
-  - >
+  - To pause/wait/sleep per host, use the `wait_for` module.
-    You can use C(ctrl+c) if you wish to advance a pause earlier than it is set to expire or if you need to abort a playbook run entirely. To continue early:
+  - You can use C(ctrl+c) if you wish to advance a pause earlier than it is set to expire or if you need to abort a playbook run entirely.
-    press C(ctrl+c) and then C(c). To abort a playbook: press C(ctrl+c) and then C(a).
+    To continue early press C(ctrl+c) and then C(c). To abort a playbook press C(ctrl+c) and then C(a).
-  - >
+  - The pause module integrates into async/parallelized playbooks without any special considerations (see Rolling Updates).
-    The pause module integrates into async/parallelized playbooks without any special considerations (see also: Rolling Updates). When using pauses with
+    When using pauses with the C(serial) playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts.
-    the C(serial) playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts.
   - This module is also supported for Windows targets.
 version_added: "0.8"
 options:

lib/ansible/modules/utilities/logic/wait_for.py

@@ -17,17 +17,15 @@ DOCUMENTATION = r'''
 module: wait_for
 short_description: Waits for a condition before continuing
 description:
-     - You can wait for a set amount of time C(timeout), this is the default if nothing is specified.
+     - You can wait for a set amount of time C(timeout), this is the default if nothing is specified or just C(timeout) is specified.
-     - Waiting for a port to become available is useful for when services
+       This does not produce an error.
-       are not immediately available after their init scripts return
+     - Waiting for a port to become available is useful for when services are not immediately available after their init scripts return
-       which is true of certain Java application servers. It is also
+       which is true of certain Java application servers. It is also useful when starting guests with the M(virt) module and
-       useful when starting guests with the M(virt) module and
        needing to pause until they are ready.
      - This module can also be used to wait for a regex match a string to be present in a file.
      - In 1.6 and later, this module can also be used to wait for a file to be available or
        absent on the filesystem.
-     - In 1.8 and later, this module can also be used to wait for active
+     - In 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node
-       connections to be closed before continuing, useful if a node
        is being rotated out of a load balancer pool.
      - This module is also supported for Windows targets.
 version_added: "0.7"
@@ -38,7 +36,8 @@ options:
     default: "127.0.0.1"
   timeout:
     description:
-      - Maximum number of seconds to wait for.
+      - Maximum number of seconds to wait for, when used with another condition it will force an error.
+      - When used without other conditions it is equivalent of just sleeping.
     default: 300
   connect_timeout:
     description:
@@ -99,6 +98,10 @@ author:
 '''
 
 EXAMPLES = r'''
+- name: sleep for 300 seconds and continue with play
+  wait_for: timeout=300
+  delegate_to: localhost
+
 - name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
   wait_for:
     port: 8000