bpo-45762: Improve docs for ``@singledispatch``/``@singledispatchmethod`` (GH-29426) (GH-29430)

(cherry picked from commit 71e8a3e76a32f5eabe20e7fa984f384ca9af6ec6)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

2 files changed, 28 insertions, 22 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index b2901e43be..1e408482c7 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -392,8 +392,8 @@ The :mod:`functools` module defines the following functions:
    dispatch>` :term:`generic function`.
 
    To define a generic function, decorate it with the ``@singledispatch``
-   decorator. Note that the dispatch happens on the type of the first argument,
-   create your function accordingly::
+   decorator. When defining a function using ``@singledispatch``, note that the
+   dispatch happens on the type of the first argument::
 
      >>> from functools import singledispatch
      >>> @singledispatch
@@ -403,9 +403,9 @@ The :mod:`functools` module defines the following functions:
      ...     print(arg)
 
    To add overloaded implementations to the function, use the :func:`register`
-   attribute of the generic function.  It is a decorator.  For functions
-   annotated with types, the decorator will infer the type of the first
-   argument automatically::
+   attribute of the generic function, which can be used as a decorator.  For
+   functions annotated with types, the decorator will infer the type of the
+   first argument automatically::
 
      >>> @fun.register
      ... def _(arg: int, verbose=False):
@@ -431,17 +431,17 @@ The :mod:`functools` module defines the following functions:
      ...
 
 
-   To enable registering lambdas and pre-existing functions, the
-   :func:`register` attribute can be used in a functional form::
+   To enable registering :term:`lambdas<lambda>` and pre-existing functions,
+   the :func:`register` attribute can also be used in a functional form::
 
      >>> def nothing(arg, verbose=False):
      ...     print("Nothing.")
      ...
      >>> fun.register(type(None), nothing)
 
-   The :func:`register` attribute returns the undecorated function which
-   enables decorator stacking, pickling, as well as creating unit tests for
-   each variant independently::
+   The :func:`register` attribute returns the undecorated function. This
+   enables decorator stacking, :mod:`pickling<pickle>`, and the creation
+   of unit tests for each variant independently::
 
      >>> @fun.register(float)
      ... @fun.register(Decimal)
@@ -476,11 +476,12 @@ The :mod:`functools` module defines the following functions:
    Where there is no registered implementation for a specific type, its
    method resolution order is used to find a more generic implementation.
    The original function decorated with ``@singledispatch`` is registered
-   for the base ``object`` type, which means it is used if no better
+   for the base :class:`object` type, which means it is used if no better
    implementation is found.
 
-   If an implementation registered to :term:`abstract base class`, virtual
-   subclasses will be dispatched to that implementation::
+   If an implementation is registered to an :term:`abstract base class`,
+   virtual subclasses of the base class will be dispatched to that
+   implementation::
 
      >>> from collections.abc import Mapping
      >>> @fun.register
@@ -493,7 +494,7 @@ The :mod:`functools` module defines the following functions:
      >>> fun({"a": "b"})
      a => b
 
-   To check which implementation will the generic function choose for
+   To check which implementation the generic function will choose for
    a given type, use the ``dispatch()`` attribute::
 
      >>> fun.dispatch(float)
@@ -516,7 +517,7 @@ The :mod:`functools` module defines the following functions:
    .. versionadded:: 3.4
 
    .. versionchanged:: 3.7
-      The :func:`register` attribute supports using type annotations.
+      The :func:`register` attribute now supports using type annotations.
 
 
 .. class:: singledispatchmethod(func)
@@ -525,8 +526,9 @@ The :mod:`functools` module defines the following functions:
    dispatch>` :term:`generic function`.
 
    To define a generic method, decorate it with the ``@singledispatchmethod``
-   decorator. Note that the dispatch happens on the type of the first non-self
-   or non-cls argument, create your function accordingly::
+   decorator. When defining a function using ``@singledispatchmethod``, note
+   that the dispatch happens on the type of the first non-*self* or non-*cls*
+   argument::
 
     class Negator:
         @singledispatchmethod
@@ -542,9 +544,10 @@ The :mod:`functools` module defines the following functions:
             return not arg
 
    ``@singledispatchmethod`` supports nesting with other decorators such as
-   ``@classmethod``. Note that to allow for ``dispatcher.register``,
-   ``singledispatchmethod`` must be the *outer most* decorator. Here is the
-   ``Negator`` class with the ``neg`` methods being class bound::
+   :func:`@classmethod<classmethod>`. Note that to allow for
+   ``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*
+   decorator. Here is the ``Negator`` class with the ``neg`` methods bound to
+   the class, rather than an instance of the class::
 
     class Negator:
         @singledispatchmethod
@@ -562,8 +565,9 @@ The :mod:`functools` module defines the following functions:
         def _(cls, arg: bool):
             return not arg
 
-   The same pattern can be used for other similar decorators: ``staticmethod``,
-   ``abstractmethod``, and others.
+   The same pattern can be used for other similar decorators:
+   :func:`@staticmethod<staticmethod>`,
+   :func:`@abstractmethod<abc.abstractmethod>`, and others.
 
    .. versionadded:: 3.8
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst b/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst
new file mode 100644
index 0000000000..7ff6283a2a
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-11-05-12-15-24.bpo-45726.GwRr7e.rst
@@ -0,0 +1,2 @@
+Improve documentation for :func:`functools.singledispatch` and
+:class:`functools.singledispatchmethod`.