[Python-checkins] [3.11] typing docs: Improve the intro to each section (#105901) (#105903)

[AlexWaygood]

https://github.com/python/cpython/commit/8bb16f665691b2869e107e180208d28b292bf3bd
commit: 8bb16f665691b2869e107e180208d28b292bf3bd
branch: 3.11
author: Alex Waygood <Alex.Waygood at Gmail.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-06-19T01:17:06+01:00
summary:

[3.11] typing docs: Improve the intro to each section (#105901) (#105903)

typing docs: Improve the intro to each section (#105901)

files:
M Doc/library/typing.rst

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 68924266811b5..b9e8534fe956c 100644
--- 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:
 
@@ -606,25 +607,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
 -------------------------
@@ -632,7 +615,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
 
@@ -832,7 +816,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
 
@@ -1397,7 +1382,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn
 Building generic types
 """"""""""""""""""""""
 
-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.
 
 .. class:: Generic
@@ -1738,7 +1724,9 @@ for creating generic types.
 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
 
@@ -2125,7 +2113,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
 
@@ -2716,6 +2705,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