gh-117492: Clarify documentation of `typing.Never` (#117678)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>

1 files changed, 22 insertions, 24 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index d816e63..573318b 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -852,14 +852,25 @@ using ``[]``.
    .. versionadded:: 3.11
 
 .. data:: Never
+          NoReturn
 
-   The `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_,
+   :data:`!Never` and :data:`!NoReturn` represent the
+   `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_,
    a type that has no members.
 
-   This can be used to define a function that should never be
-   called, or a function that never returns::
+   They can be used to indicate that a function never returns,
+   such as :func:`sys.exit`::
 
-      from typing import Never
+      from typing import Never  # or NoReturn
+
+      def stop() -> Never:
+          raise RuntimeError('no way')
+
+   Or to define a function that should never be
+   called, as there are no valid arguments, such as
+   :func:`assert_never`::
+
+      from typing import Never  # or NoReturn
 
       def never_call_me(arg: Never) -> None:
           pass
@@ -872,31 +883,18 @@ using ``[]``.
               case str():
                   print("It's a str")
               case _:
-                  never_call_me(arg)  # OK, arg is of type Never
-
-   .. versionadded:: 3.11
-
-      On older Python versions, :data:`NoReturn` may be used to express the
-      same concept. ``Never`` was added to make the intended meaning more explicit.
+                  never_call_me(arg)  # OK, arg is of type Never (or NoReturn)
 
-.. data:: NoReturn
+   :data:`!Never` and :data:`!NoReturn` have the same meaning in the type system
+   and static type checkers treat both equivalently.
 
-   Special type indicating that a function never returns.
-
-   For example::
+   .. versionadded:: 3.6.2
 
-      from typing import NoReturn
+      Added :data:`NoReturn`.
 
-      def stop() -> NoReturn:
-          raise RuntimeError('no way')
-
-   ``NoReturn`` can also be used as a
-   `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_, a type that
-   has no values. Starting in Python 3.11, the :data:`Never` type should
-   be used for this concept instead. Type checkers should treat the two
-   equivalently.
+   .. versionadded:: 3.11
 
-   .. versionadded:: 3.6.2
+      Added :data:`Never`.
 
 .. data:: Self