GH-100101: Clarify documentation of zip's strict option (GH-100103)

(cherry picked from commit cf1c09818032df3080c2cd9e7edb5f657213dc83)

Co-authored-by: JustAnotherArchivist <JustAnotherArchivist@users.noreply.github.com>

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 46e77fdb41552fcfe48550844599255faad2406f..5400feb35567a7210034630656c07908842c1c4b 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1894,14 +1894,24 @@ are always available.  They are listed here in alphabetical order.
         >>> list(zip(('a', 'b', 'c'), (1, 2, 3), strict=True))
         [('a', 1), ('b', 2), ('c', 3)]
 
-     Unlike the default behavior, it checks that the lengths of iterables are
-     identical, raising a :exc:`ValueError` if they aren't:
-
-        >>> list(zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True))
+     Unlike the default behavior, it raises a :exc:`ValueError` if one iterable
+     is exhausted before the others:
+
+        >>> for item in zip(range(3), ['fee', 'fi', 'fo', 'fum'], strict=True):  # doctest: +SKIP
+        ...     print(item)
+        ...
+        (0, 'fee')
+        (1, 'fi')
+        (2, 'fo')
         Traceback (most recent call last):
           ...
         ValueError: zip() argument 2 is longer than argument 1
 
+     ..
+        This doctest is disabled because doctest does not support capturing
+        output and exceptions in the same code unit.
+        https://github.com/python/cpython/issues/65382
+
      Without the ``strict=True`` argument, any bug that results in iterables of
      different lengths will be silenced, possibly manifesting as a hard-to-find
      bug in another part of the program.