add docstrings for wait()/iwait()

gevent/hub.py

@@ -580,6 +580,10 @@ class Waiter(object):
 
 
 def iwait(objects, timeout=None):
+    """Yield objects as they are ready, until all are ready or timeout expired.
+
+    *objects* must be iterable yielding instance implementing wait protocol (rawlink() and unlink()).
+    """
     # QQQ would be nice to support iterable here that can be generated slowly (why?)
     waiter = Waiter()
     switch = waiter.switch
@@ -609,6 +613,31 @@ def iwait(objects, timeout=None):
 
 
 def wait(objects=None, timeout=None, count=None):
+    """Wait for *objects* to become ready or for event loop to finish.
+
+    If *objects* is provided, it should be an iterable containg objects implementing wait protocol (rawlink() and
+    unlink() methods):
+
+    - :class:`gevent.Greenlet` instance
+    - :class:`gevent.event.Event` instance
+    - :class:`gevent.lock.Semaphore` instance
+    - :class:`gevent.subprocess.Popen` instance
+
+    If *objects* is ``None`` (the default), ``wait()`` blocks until all event loops has nothing to do:
+
+    - all greenlets have finished
+    - all servers were stopped
+    - all event loop watchers were stopped.
+
+    If *count* is ``None`` (the default), wait for all of *object* to become ready.
+
+    If *count* is a number, wait for *count* object to become ready. (For example, if count is ``1`` then the
+    function exits when any object in the list is ready).
+
+    If *timeout* is provided, it specifies the maximum number of seconds ``wait()`` will block.
+
+    Returns the list of ready objects, in the order in which they were ready.
+    """
     if objects is None:
         return get_hub().join(timeout=timeout)
     result = []