bpo-42198: Improve consistency of Union docs (GH-23029)

No backport is required since union is only in 3.10.

This addresses "3. Consistency nitpicks for Union's docs" in the bpo.

Please skip news. Thank you.

2 files changed, 15 insertions, 24 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 09477e6..8a9cadd 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -4968,15 +4968,16 @@ Union Type
    pair: union; type
 
 A union object holds the value of the ``|`` (bitwise or) operation on
-multiple :ref:`type objects<bltin-type-objects>`.  These types are intended
-primarily for type annotations. The union type expression enables cleaner
-type hinting syntax compared to :data:`typing.Union`.
+multiple :ref:`type objects <bltin-type-objects>`.  These types are intended
+primarily for :term:`type annotations <annotation>`. The union type expression
+enables cleaner type hinting syntax compared to :data:`typing.Union`.
 
 .. describe:: X | Y | ...
 
    Defines a union object which holds types *X*, *Y*, and so forth. ``X | Y``
    means either X or Y.  It is equivalent to ``typing.Union[X, Y]``.
-   Example::
+   For example, the following function expects an argument of type
+   :class:`int` or :class:`float`::
 
       def square(number: int | float) -> int | float:
           return number ** 2
@@ -4985,15 +4986,15 @@ type hinting syntax compared to :data:`typing.Union`.
 
    Union objects can be tested for equality with other union objects.  Details:
 
-   * Unions of unions are flattened, e.g.::
+   * Unions of unions are flattened::
 
        (int | str) | float == int | str | float
 
-   * Redundant types are removed, e.g.::
+   * Redundant types are removed::
 
        int | str | int == int | str
 
-   * When comparing unions, the order is ignored, e.g.::
+   * When comparing unions, the order is ignored::
 
       int | str == str | int
 
@@ -5012,14 +5013,8 @@ type hinting syntax compared to :data:`typing.Union`.
       >>> isinstance("", int | str)
       True
 
-   ..
-      At the time of writing this, there is no documentation for parameterized
-      generics or PEP 585. Thus the link currently points to PEP 585 itself.
-      Please change the link for parameterized generics to reference the correct
-      documentation once documentation for PEP 585 becomes available.
-
-   However, union objects containing `parameterized generics
-   <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
+   However, union objects containing :ref:`parameterized generics
+   <types-genericalias>` cannot be used::
 
       >>> isinstance(1, int | list[int])
       Traceback (most recent call last):
@@ -5033,20 +5028,16 @@ type hinting syntax compared to :data:`typing.Union`.
       >>> issubclass(bool, int | str)
       True
 
-   ..
-      Once again, please change the link below for parameterized generics to
-      reference the correct documentation once documentation for PEP 585
-      becomes available.
-
-   However, union objects containing `parameterized generics
-   <https://www.python.org/dev/peps/pep-0585/>`_ cannot be used::
+   However, union objects containing :ref:`parameterized generics
+   <types-genericalias>` cannot be used::
 
       >>> issubclass(bool, bool | list[str])
       Traceback (most recent call last):
         File "<stdin>", line 1, in <module>
       TypeError: issubclass() argument 2 cannot contain a parameterized generic
 
-The type of a union object is :data:`types.Union`.  An object cannot be
+The user-exposed type for the union object can be accessed from
+:data:`types.Union` and used for :func:`isinstance` checks.  An object cannot be
 instantiated from the type::
 
    >>> import types
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index f4d7290..60dee0c 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -134,7 +134,7 @@ arguments of multiple types, :data:`typing.Union` was used::
        return number ** 2
 
 
-Now, type hints can be written in a more succinct manner::
+Type hints can now be written in a more succinct manner::
 
    def square(number: int | float) -> int | float:
        return number ** 2