add docs on wait_for

rst/modules.rst

@@ -73,6 +73,7 @@ Let's see what's available in the Ansible module library, out of the box:
 .. include:: modules/supervisorctl.rst
 .. include:: modules/template.rst
 .. include:: modules/user.rst
+.. include:: modules/wait_for.rst
 .. include:: modules/virt.rst
 .. include:: modules/yum.rst
 

rst/modules/lineinfile.rst

@@ -31,7 +31,7 @@ For other cases, see the copy or template modules.
 |                    |          |         | line at the end of the file.                                               |
 +--------------------+----------+---------+----------------------------------------------------------------------------+
 
-Example::
+Example action from Ansible :doc:`playbooks`::
 
     lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
     lineinfile name=/etc/sudoers regexp="^#includedir" line="#includedir /etc/sudoers.d"

rst/modules/wait_for.rst

@@ -0,0 +1,32 @@
+.. _wait_for:
+
+wait_for
+````````
+
+.. versionadded:: 0.7
+
+Waits for a given port to become accessible (or inaccessible) on a local or remote server.
+
+This 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 useful when starting guests with the virt module and 
+needing to pause until they are ready.
+
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+| parameter          | required | default   | comments                                                                   |
++====================+==========+===========+============================================================================+
+| host               | no       | 127.0.0.1 | hostname or IP to wait for                                                 |
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+| timeout            | no       | 300       | maximum number of seconds to wait                                          |
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+| delay              | no       | 0         | number of seconds to wait before starting to poll                          |
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+| port               | yes      |           | port to poll for openness or closedness                                    |
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+| state              | no       | started   | either 'started', or 'stopped' depending on whether the module should poll |
+|                    |          |           | for the port being open or closed.                                         |
++--------------------+----------+-----------+----------------------------------------------------------------------------+
+
+Example from Ansible :doc:`playbooks`::
+
+    wait_for port=8080 delay=10
+