gh-117492: Clarify documentation of typing.Never

Doc/library/typing.rst

@@ -857,7 +857,7 @@ using ``[]``.
    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::
+   called, as there are no valid arguments::
 
       from typing import Never
 
@@ -874,10 +874,19 @@ using ``[]``.
               case _:
                   never_call_me(arg)  # OK, arg is of type Never
 
+   ``Never`` can also be used to indicate that a function never returns::
+
+      from typing import Never
+
+      def stop() -> Never:
+          raise RuntimeError('no way')
+
    .. 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.
+      On older Python versions, :data:`NoReturn` may be used as a
+      replacement for ``Never``, which was added to make the use as a
+      `bottom type <https://en.wikipedia.org/wiki/Bottom_type>`_ more
+      explicit. Type checkers should treat the two equivalently.
 
 .. data:: NoReturn
 
@@ -898,6 +907,10 @@ using ``[]``.
 
    .. versionadded:: 3.6.2
 
+   .. deprecated-removed:: 3.13 3.18
+      :data:`NoReturn` is deprecated in favor of the :data:`Never` type.
+      ``NoReturn`` will be removed from ``typing`` in Python 3.18.
+
 .. data:: Self
 
    Special type to represent the current enclosed class.