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

Also fix up some cross-references in the asyncio docs.

1 files changed, 25 insertions, 11 deletions

diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst
index ef6a058..a73e995 100644
--- a/Doc/library/asyncio-policy.rst
+++ b/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
 ===============