bpo-37703: improve asyncio.gather documentation regarding cancellation

Author: vinay0410

Doc/library/asyncio-task.rst

@@ -327,6 +327,12 @@ Running Tasks Concurrently
 
    If ``gather()`` is *cancelled*, all submitted awaitables
    (that have not completed yet) are also *cancelled*.
+   **Note:** Cancelling gather() after it has been marked done
+   won't cancel any submitted awaitables. For instance, gather
+   can be marked done after propagating an exception to the caller,
+   therefore, calling ``gather.cancel()`` after catching an exception
+   (raised by one of the awaitables) from gather won't cancel any
+   other awaitables.
 
    If any Task or Future from the *aws* sequence is *cancelled*, it is
    treated as if it raised :exc:`CancelledError` -- the ``gather()``

Lib/asyncio/tasks.py

@@ -729,6 +729,12 @@ def gather(*coros_or_futures, loop=None, return_exceptions=False):
     the outer Future is *not* cancelled in this case.  (This is to
     prevent the cancellation of one child to cause other children to
     be cancelled.)
+    **Note:** Cancelling gather() after it has been marked done
+    won't cancel any submitted awaitables. For instance, gather
+    can be marked done after propagating an exception to the caller,
+    therefore, calling ``gather.cancel()`` after catching an exception
+    (raised by one of the awaitables) from gather won't cancel any
+    other awaitables.
     """
     if not coros_or_futures:
         if loop is None: