Update docstrings as well

Author: rhettinger

Lib/asyncio/queues.py

@@ -253,9 +253,11 @@ def shutdown(self, immediate=False):
         By default, gets will only raise once the queue is empty. Set
         'immediate' to True to make gets raise immediately instead.
 
-        All blocked callers of put() and get() will be unblocked. If
-        'immediate', unblock callers of join() regardless of the
-        number of unfinished tasks.
+        All blocked callers of put() and get() will be unblocked.
+
+        If 'immediate', the queue is drained and unfinished tasks
+        is reduced by the number of drained tasks.  If unfinished tasks
+        is reduced to zero, callers of Queue.join are unblocked.
         """
         self._is_shutdown = True
         if immediate:

Lib/queue.py

@@ -236,9 +236,11 @@ def shutdown(self, immediate=False):
         By default, gets will only raise once the queue is empty. Set
         'immediate' to True to make gets raise immediately instead.
 
-        All blocked callers of put() and get() will be unblocked. If
-        'immediate', callers of join() are unblocked regardless of
-        the number of unfinished tasks.
+        All blocked callers of put() and get() will be unblocked.
+
+        If 'immediate', the queue is drained and unfinished tasks
+        is reduced by the number of drained tasks.  If unfinished tasks
+        is reduced to zero, callers of Queue.join are unblocked.
         '''
         with self.mutex:
             self.is_shutdown = True