From 2b0b01768352f3d7a4c7c146128a1ac89eac4809 Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Tue, 27 Sep 2022 17:33:32 -0700
Subject: [PATCH] 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 cc0f3a10f0ee507d9044ef9036cf3e711c5338a9)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
---
 Doc/library/asyncio-dev.rst         |  2 +-
 Doc/library/asyncio-eventloop.rst   |  7 +++++--
 Doc/library/asyncio-llapi-index.rst |  2 +-
 Doc/library/asyncio-policy.rst      | 23 ++++++++++++++++-------
 4 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index 29d69b9f748..921a394a59f 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/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
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 41ebc0447dc..15f4f04fbe9 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/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
 ==================
@@ -1616,6 +1618,7 @@ Do not instantiate the class directly.
 
 
 .. _asyncio-event-loops:
+.. _asyncio-event-loop-implementations:
 
 Event Loop Implementations
 ==========================
@@ -1665,7 +1668,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.
 
diff --git a/Doc/library/asyncio-llapi-index.rst b/Doc/library/asyncio-llapi-index.rst
index cdadb7975ad..c787cb930d4 100644
--- a/Doc/library/asyncio-llapi-index.rst
+++ b/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::
diff --git a/Doc/library/asyncio-policy.rst b/Doc/library/asyncio-policy.rst
index d528db72fb8..a73e99510f0 100644
--- a/Doc/library/asyncio-policy.rst
+++ b/Doc/library/asyncio-policy.rst
@@ -7,7 +7,7 @@
 Policies
 ========
 
-An event loop policy is a global object
+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
@@ -16,18 +16,20 @@ to use different event loop implementations,
 or substituted by a :ref:`custom policy <asyncio-custom-policies>`
 that can override these behaviors.
 
-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.
+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.
 
-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.
+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
 ==============================
 
@@ -45,6 +47,8 @@ for the current process:
    If *policy* is set to ``None``, the default policy is restored.
 
 
+.. _asyncio-policy-objects:
+
 Policy Objects
 ==============
 
@@ -91,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:
 
 
@@ -122,6 +128,7 @@ asyncio ships with the following built-in policies:
 
    .. availability:: Windows.
 
+
 .. _asyncio-watchers:
 
 Process Watchers
@@ -275,6 +282,8 @@ implementation used by the asyncio event loop:
    .. versionadded:: 3.9
 
 
+.. _asyncio-custom-policies:
+
 Custom Policies
 ===============