gh-96377: Update asyncio policy doc intro paras to be clear and accurate (GH-97603)

Also fix up some cross-references in the asyncio docs.
(cherry picked from commit cc0f3a1)

Co-authored-by: C.A.M. Gerlach <[email protected]>

Author: miss-islington

Doc/library/asyncio-dev.rst

@@ -109,7 +109,7 @@ that the event loop runs in.
 
 There is currently no way to schedule coroutines or callbacks directly
 from a different process (such as one started with
-:mod:`multiprocessing`). The :ref:`Event Loop Methods <asyncio-event-loop>`
+:mod:`multiprocessing`). The :ref:`asyncio-event-loop-methods`
 section lists APIs that can read from pipes and watch file descriptors
 without blocking the event loop. In addition, asyncio's
 :ref:`Subprocess <asyncio-subprocess>` APIs provide a way to start a

Doc/library/asyncio-eventloop.rst

@@ -1,6 +1,8 @@
 .. currentmodule:: asyncio
 
 
+.. _asyncio-event-loop:
+
 ==========
 Event Loop
 ==========
@@ -92,7 +94,7 @@ This documentation page contains the following sections:
   loop APIs.
 
 
-.. _asyncio-event-loop:
+.. _asyncio-event-loop-methods:
 
 Event Loop Methods
 ==================
@@ -1498,6 +1500,7 @@ Do not instantiate the class directly.
 
 
 .. _asyncio-event-loops:
+.. _asyncio-event-loop-implementations:
 
 Event Loop Implementations
 ==========================
@@ -1544,7 +1547,7 @@ on Unix and :class:`ProactorEventLoop` on Windows.
 
    Abstract base class for asyncio-compliant event loops.
 
-   The :ref:`Event Loop Methods <asyncio-event-loop>` section lists all
+   The :ref:`asyncio-event-loop-methods` section lists all
    methods that an alternative implementation of ``AbstractEventLoop``
    should have defined.
 

Doc/library/asyncio-llapi-index.rst

@@ -37,7 +37,7 @@ Event Loop Methods
 ==================
 
 See also the main documentation section about the
-:ref:`event loop methods <asyncio-event-loop>`.
+:ref:`asyncio-event-loop-methods`.
 
 .. rubric:: Lifecycle
 .. list-table::

Doc/library/asyncio-policy.rst

@@ -7,22 +7,29 @@
 Policies
 ========
 
-An event loop policy is a global per-process object that controls
-the management of the event loop. Each event loop has a default
-policy, which can be changed and customized using the policy API.
-
-A policy defines the notion of *context* and manages a
-separate event loop per context. The default policy
-defines *context* to be the current thread.
-
-By using a custom event loop policy, the behavior of
-:func:`get_event_loop`, :func:`set_event_loop`, and
-:func:`new_event_loop` functions can be customized.
+An event loop policy is a global (per-interpreter) object
+used to get and set the current :ref:`event loop <asyncio-event-loop>`,
+as well as create new event loops.
+The default policy can be :ref:`replaced <asyncio-policy-get-set>` with
+:ref:`built-in alternatives <asyncio-policy-builtin>`
+to use different event loop implementations,
+or substituted by a :ref:`custom policy <asyncio-custom-policies>`
+that can override these behaviors.
+
+The :ref:`policy object <asyncio-policy-objects>`
+gets and sets a separate event loop per *context*.
+This is per-thread by default,
+though custom policies could define *context* differently.
+
+Custom event loop policies can control the behavior of
+:func:`get_event_loop`, :func:`set_event_loop`, and :func:`new_event_loop`.
 
 Policy objects should implement the APIs defined
 in the :class:`AbstractEventLoopPolicy` abstract base class.
 
 
+.. _asyncio-policy-get-set:
+
 Getting and Setting the Policy
 ==============================
 
@@ -40,6 +47,8 @@ for the current process:
    If *policy* is set to ``None``, the default policy is restored.
 
 
+.. _asyncio-policy-objects:
+
 Policy Objects
 ==============
 
@@ -86,6 +95,8 @@ The abstract event loop policy base class is defined as follows:
       This function is Unix specific.
 
 
+.. _asyncio-policy-builtin:
+
 asyncio ships with the following built-in policies:
 
 
@@ -117,6 +128,7 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
+
 .. _asyncio-watchers:
 
 Process Watchers
@@ -270,6 +282,8 @@ implementation used by the asyncio event loop:
    .. versionadded:: 3.9
 
 
+.. _asyncio-custom-policies:
+
 Custom Policies
 ===============