bpo-42259: clarify pprint saferepr docs (#30256)

diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst
index 3da5aa9389b17df618210a65509b1992f88e87f7..4e29192311fc21130b58f4fda9ea9cdc7ed909f6 100644 (file)
--- a/Doc/library/pprint.rst
+++ b/Doc/library/pprint.rst
@@ -171,17 +171,21 @@ The :mod:`pprint` module defines one class:
 
 .. function:: isrecursive(object)
 
-   Determine if *object* requires a recursive representation.
+   Determine if *object* requires a recursive representation.  This function is
+   subject to the same limitations as noted in :func:`saferepr` below and may raise an
+   :exc:`RecursionError` if it fails to detect a recursive object.
 
 
 One more support function is also defined:
 
 .. function:: saferepr(object)
 
-   Return a string representation of *object*, protected against recursive data
-   structures.  If the representation of *object* exposes a recursive entry, the
-   recursive reference will be represented as ``<Recursion on typename with
-   id=number>``.  The representation is not otherwise formatted.
+   Return a string representation of *object*, protected against recursion in
+   some common data structures, namely instances of :class:`dict`, :class:`list`
+   and :class:`tuple` or subclasses whose ``__repr__`` has not been overridden.  If the
+   representation of object exposes a recursive entry, the recursive reference
+   will be represented as ``<Recursion on typename with id=number>``.  The
+   representation is not otherwise formatted.
 
    >>> pprint.saferepr(stuff)
    "[<Recursion on list with id=...>, 'spam', 'eggs', 'lumberjack', 'knights', 'ni']"