gh-85747: Active voice & suggested edits, 'running/stopping loop' & 'callbacks' subsections of asyncio-eventloop.rst (#100270)

bskinn · CAM-Gerlach · terryjreedy · web-flow · commit c4de6b1d5230 · 2023-02-06T21:25:42.000-08:00
Co-authored-by: C.A.M. Gerlach &lt;CAM.Gerlach@Gerlach.CAM&gt;
Co-authored-by: Terry Jan Reedy &lt;tjreedy@udel.edu&gt;
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
@@ -186,19 +186,24 @@ Running and stopping the loop
 .. coroutinemethod:: loop.shutdown_default_executor(timeout=None)
 
    Schedule the closure of the default executor and wait for it to join all of
-   the threads in the :class:`ThreadPoolExecutor`. After calling this method, a
-   :exc:`RuntimeError` will be raised if :meth:`loop.run_in_executor` is called
-   while using the default executor.
+   the threads in the :class:`~concurrent.futures.ThreadPoolExecutor`.
+   Once this method has been called,
+   using the default executor with :meth:`loop.run_in_executor`
+   will raise a :exc:`RuntimeError`.
 
-   The *timeout* parameter specifies the amount of time the executor will
-   be given to finish joining. The default value is ``None``, which means the
-   executor will be given an unlimited amount of time.
+   The *timeout* parameter specifies the amount of time
+   (in :class:`float` seconds) the executor will be given to finish joining.
+   With the default, ``None``,
+   the executor is allowed an unlimited amount of time.
 
-   If the timeout duration is reached, a warning is emitted and executor is
-   terminated without waiting for its threads to finish joining.
+   If the *timeout* is reached, a :exc:`RuntimeWarning` is emitted
+   and the default executor is terminated
+   without waiting for its threads to finish joining.
 
-   Note that there is no need to call this function when
-   :func:`asyncio.run` is used.
+   .. note::
+
+      Do not call this method when using :func:`asyncio.run`,
+      as the latter handles default executor shutdown automatically.
 
    .. versionadded:: 3.9
 
@@ -213,22 +218,23 @@ Scheduling callbacks
    Schedule the *callback* :term:`callback` to be called with
    *args* arguments at the next iteration of the event loop.
 
+   Return an instance of :class:`asyncio.Handle`,
+   which can be used later to cancel the callback.
+
    Callbacks are called in the order in which they are registered.
    Each callback will be called exactly once.
 
-   An optional keyword-only *context* argument allows specifying a
+   The optional keyword-only *context* argument specifies a
    custom :class:`contextvars.Context` for the *callback* to run in.
-   The current context is used when no *context* is provided.
-
-   An instance of :class:`asyncio.Handle` is returned, which can be
-   used later to cancel the callback.
+   Callbacks use the current context when no *context* is provided.
 
-   This method is not thread-safe.
+   Unlike :meth:`call_soon_threadsafe`, this method is not thread-safe.
 
 .. method:: loop.call_soon_threadsafe(callback, *args, context=None)
 
-   A thread-safe variant of :meth:`call_soon`.  Must be used to
-   schedule callbacks *from another thread*.
+   A thread-safe variant of :meth:`call_soon`. When scheduling callbacks from
+   another thread, this function *must* be used, since :meth:`call_soon` is not
+   thread-safe.
 
    Raises :exc:`RuntimeError` if called on a loop that's been closed.
    This can happen on a secondary thread when the main application is
