[3.11] Improve docs for typing.TypeAlias (GH-105372). (#105447)

(cherry picked from commit c5ec51e)

Co-authored-by: Alex Waygood <[email protected]>

Author: JelleZijlstra

Doc/library/typing.rst

@@ -786,13 +786,34 @@ These can be used as types in annotations and do not support ``[]``.
 .. data:: TypeAlias
 
    Special annotation for explicitly declaring a :ref:`type alias <type-aliases>`.
+
    For example::
 
-    from typing import TypeAlias
+      from typing import TypeAlias
+
+      Factors: TypeAlias = list[int]
+
+   ``TypeAlias`` is particularly useful for annotating
+   aliases that make use of forward references, as it can be hard for type
+   checkers to distinguish these from normal variable assignments:
+
+   .. testcode::
+
+      from typing import Generic, TypeAlias, TypeVar
+
+      T = TypeVar("T")
+
+      # "Box" does not exist yet,
+      # so we have to use quotes for the forward reference.
+      # Using ``TypeAlias`` tells the type checker that this is a type alias declaration,
+      # not a variable assignment to a string.
+      BoxOfStrings: TypeAlias = "Box[str]"
 
-    Factors: TypeAlias = list[int]
+      class Box(Generic[T]):
+          @classmethod
+          def make_box_of_strings(cls) -> BoxOfStrings: ...
 
-   See :pep:`613` for more details about explicit type aliases.
+   See :pep:`613` for more details.
 
    .. versionadded:: 3.10