Update asynico main docs

Author: rhettinger

Doc/library/asyncio-queue.rst

@@ -102,17 +102,33 @@ Queue
 
    .. method:: shutdown(immediate=False)
 
-      Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
-      raise :exc:`QueueShutDown`.
+      Put a :class:`Queue` instance into a shutdown mode.
 
-      By default, :meth:`~Queue.get` on a shut down queue will only
-      raise once the queue is empty. Set *immediate* to true to make
-      :meth:`~Queue.get` raise immediately instead.
+      The queue can no longer grow.
+      Future calls to :meth:`~Queue.put` raise :exc:`ShutDown`.
+      Currently blocked callers of :meth:`~Queue.put` will be unblocked
+      and will raise :exc:`ShutDown` in the formerly blocked thread.
 
-      All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
-      will be unblocked. If *immediate* is true, a task will be marked
-      as done for each remaining item in the queue, which may unblock
-      callers of :meth:`~Queue.join`.
+      If *immediate* is false (the default), the queue can be wound
+      down normally with calls :meth:`~Queue.get` to extract tasks
+      that have already been loaded.
+
+      And if :meth:`~Queue.task_done` is called for each remaining task, a
+      pending :meth:`~Queue.join` will be unblocked normally.
+
+      Once the queue is empty, future calls to :meth:`~Queue.get` will
+      raise :exc:`ShutDown`.
+
+      If *immediate* is true, the queue is terminated immediately.
+      The queue is drained to be completely empty.  All callers of
+      :meth:`~Queue.join` are unblocked regardless of the number
+      of unfinished tasks.  Blocked callers of :meth:`~Queue.get`
+      are unblocked and will raise :exc:`ShutDown` because the
+      queue is empty.
+
+      Use caution when using :meth:`~Queue.join` with *immediate* set
+      to true. This unblocks the join even when no work has been done
+      on the tasks, violating the usual invariant for joining a queue.
 
       .. versionadded:: 3.13
 
@@ -129,9 +145,6 @@ Queue
       call was received for every item that had been :meth:`~Queue.put`
       into the queue).
 
-      ``shutdown(immediate=True)`` calls :meth:`task_done` for each
-      remaining item in the queue.
-
       Raises :exc:`ValueError` if called more times than there were
       items placed in the queue.