pythongh-90190: Adds documentation for singledispatch with GenericAli…

…as annotation

Doc/library/functools.rst

@@ -492,6 +492,25 @@ The :mod:`functools` module defines the following functions:
  ... print(arg.real, arg.imag)
  ...
 
+ For code that dispatches on a collections type, e.g. :data:`list`, but wants
+ to typehint the items of the collection, e.g. :data:`list[int]`, then the
+ dispatch type should be passed explicitly to the decorator itself with the
+ typehint going into the function definition::
+
+ >>> @fun.register(list)
+ ... def _(arg: list[int], verbose=False):
+ ... if verbose:
+ ... print("Enumerate this:")
+ ... for i, elem in enumerate(arg):
+ ... print(i, elem)
+
+ .. note::
+
+ At runtime the function will dispatch on an instance of a list regardless
+ of the type contained within the list i.e. :data:`[1,2,3]` will be
+ dispatched the same as :data:`["foo", "bar", "baz"]`. The annontation
+ provided in this example is for static type checkers only and has no
+ runtime application.
 
  To enable registering :term:`lambdas<lambda>` and pre-existing functions,
  the :func:`register` attribute can also be used in a functional form::