bpo-45701: Improve documentation for *typed* parameter (GH-29498) (GH-29509)

(cherry picked from commit 912a4ccc3a523e2990cc501393adfc661614c73a)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index a01b17287878c1164b286f790c6a530e6f2bc928..c78818bfab1a51c1cd946b825eb317c2c4dcb0a8 100644 (file)
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -160,10 +160,16 @@ The :mod:`functools` module defines the following functions:
    grow without bound.
 
    If *typed* is set to true, function arguments of different types will be
-   cached separately.  For example, ``f(3)`` and ``f(3.0)`` will always be
-   treated as distinct calls with distinct results.  If *typed* is false,
-   the implementation will usually but not always regard them as equivalent
-   calls and only cache a single result.
+   cached separately.  If *typed* is false, the implementation will usually
+   regard them as equivalent calls and only cache a single result. (Some
+   types such as *str* and *int* may be cached separately even when *typed*
+   is false.)
+
+   Note, type specificity applies only to the function's immediate arguments
+   rather than their contents.  The scalar arguments, ``Decimal(42)`` and
+   ``Fraction(42)`` are be treated as distinct calls with distinct results.
+   In contrast, the tuple arguments ``('answer', Decimal(42))`` and
+   ``('answer', Fraction(42))`` are treated as equivalent.
 
    The wrapped function is instrumented with a :func:`cache_parameters`
    function that returns a new :class:`dict` showing the values for *maxsize*