[3.12] typing docs: Improve the intro to each section (GH-105901) (#105902)

typing docs: Improve the intro to each section (GH-105901)
(cherry picked from commit 4426279a4399158027a1145cff1c4c92424bf5b5)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 5c7ddc7e5a29b084bf026e1c2819029f552aacca..f6851199466f3267ddde624a4bd9dcb3b998d2d8 100644 (file)
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -23,10 +23,9 @@
 
 --------------
 
-This module provides runtime support for type hints. The most fundamental
-support consists of the types :data:`Any`, :data:`Union`, :data:`Callable`,
-:class:`TypeVar`, and :class:`Generic`. For a specification, please see
-:pep:`484`. For a simplified introduction to type hints, see :pep:`483`.
+This module provides runtime support for type hints. For the original
+specification of the typing system, see :pep:`484`. For a simplified
+introduction to type hints, see :pep:`483`.
 
 
 The function below takes and returns a string and is annotated as follows::
@@ -47,16 +46,18 @@ For a summary of deprecated features and a deprecation timeline, please see
 
 .. seealso::
 
-   For a quick overview of type hints, refer to
-   `this cheat sheet <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_.
+   `"Typing cheat sheet" <https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_
+       A quick overview of type hints (hosted at the mypy docs)
 
-   The "Type System Reference" section of https://mypy.readthedocs.io/ -- since
-   the Python typing system is standardised via PEPs, this reference should
-   broadly apply to most Python type checkers, although some parts may still be
-   specific to mypy.
+   "Type System Reference" section of `the mypy docs <https://mypy.readthedocs.io/en/stable/index.html>`_
+      The Python typing system is standardised via PEPs, so this reference
+      should broadly apply to most Python type checkers. (Some parts may still
+      be specific to mypy.)
 
-   The documentation at https://typing.readthedocs.io/ serves as useful reference
-   for type system features, useful typing related tools and typing best practices.
+   `"Static Typing with Python" <https://typing.readthedocs.io/en/latest/>`_
+      Type-checker-agnostic documentation written by the community detailing
+      type system features, useful typing related tools and typing best
+      practices.
 
 .. _relevant-peps:
 
@@ -654,25 +655,7 @@ can define new custom protocols to fully enjoy structural subtyping
 Module contents
 ===============
 
-The module defines the following classes, functions and decorators.
-
-.. note::
-
-   This module defines several deprecated aliases to pre-existing
-   standard library classes. These were originally included in the typing
-   module in order to support parameterizing these generic classes using ``[]``.
-   However, the aliases became redundant in Python 3.9 when the
-   corresponding pre-existing classes were enhanced to support ``[]``.
-
-   The redundant types are deprecated as of Python 3.9 but no
-   deprecation warnings are issued by the interpreter.
-   It is expected that type checkers will flag the deprecated types
-   when the checked program targets Python 3.9 or newer.
-
-   The deprecated types will be removed from the :mod:`typing` module
-   no sooner than the first Python version released 5 years after the release of Python 3.9.0.
-   See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
-
+The ``typing`` module defines the following classes, functions and decorators.
 
 Special typing primitives
 -------------------------
@@ -680,7 +663,8 @@ Special typing primitives
 Special types
 """""""""""""
 
-These can be used as types in annotations and do not support ``[]``.
+These can be used as types in annotations. They do not support subscription
+using ``[]``.
 
 .. data:: Any
 
@@ -890,7 +874,8 @@ These can be used as types in annotations and do not support ``[]``.
 Special forms
 """""""""""""
 
-These can be used as types in annotations using ``[]``, each having a unique syntax.
+These can be used as types in annotations. They all support subscription using
+``[]``, but each has a unique syntax.
 
 .. data:: Tuple
 
@@ -1471,7 +1456,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 Building generic types and type aliases
 """""""""""""""""""""""""""""""""""""""
 
-The following objects are not used directly in annotations. Instead, they are building blocks
+The following classes should not be used directly as annotations.
+Their intended purpose is to be building blocks
 for creating generic types and type aliases.
 
 These objects can be created through special syntax
@@ -1962,7 +1948,9 @@ without the dedicated syntax, as documented below.
 Other special directives
 """"""""""""""""""""""""
 
-These are not used in annotations. They are building blocks for declaring types.
+These functions and classes should not be used directly as annotations.
+Their intended purpose is to be building blocks for creating and declaring
+types.
 
 .. class:: NamedTuple
 
@@ -2386,7 +2374,8 @@ These are not used in annotations. They are building blocks for declaring types.
 Protocols
 ---------
 
-These protocols are decorated with :func:`runtime_checkable`.
+The following protocols are provided by the typing module. All are decorated
+with :func:`@runtime_checkable <runtime_checkable>`.
 
 .. class:: SupportsAbs
 
@@ -3024,6 +3013,21 @@ Constant
 Deprecated aliases
 ------------------
 
+This module defines several deprecated aliases to pre-existing
+standard library classes. These were originally included in the typing
+module in order to support parameterizing these generic classes using ``[]``.
+However, the aliases became redundant in Python 3.9 when the
+corresponding pre-existing classes were enhanced to support ``[]``.
+
+The redundant types are deprecated as of Python 3.9 but no
+deprecation warnings are issued by the interpreter.
+It is expected that type checkers will flag the deprecated types
+when the checked program targets Python 3.9 or newer.
+
+The deprecated types will be removed from the :mod:`typing` module
+no sooner than the first Python version released 5 years after the release of Python 3.9.0.
+See details in :pep:`585`—*Type Hinting Generics In Standard Collections*.
+
 .. _corresponding-to-built-in-types:
 
 Aliases to built-in types