Tweak wording. Add doctest.

Author: rhettinger

Doc/library/threading.rst

@@ -1461,9 +1461,11 @@ of the derived iterators.
 .. class:: serialize(iterable)
 
    Return an iterator wrapper that serializes concurrent calls to
-   :meth:`~iterator.__next__` using a lock.  For generators, will also
-   serialize calls to :meth:`~generator.send`, :meth:`~generator.throw`,
-   and :meth:`~generator.close`.
+   :meth:`~iterator.__next__` using a lock.
+
+   If the wrapped iterator also defines :meth:`~generator.send`,
+   :meth:`~generator.throw`, or :meth:`~generator.close`, those calls
+   are serialized as well.
 
    This makes it possible to share a single iterator, including a generator
    iterator, between multiple threads. A lock assures that calls are handled
@@ -1474,7 +1476,9 @@ of the derived iterators.
    :func:`next` while another thread is already advancing the iterator will
    block until the active call completes.
 
-   Example::
+   Example:
+
+   .. doctest::
 
       import threading
 
@@ -1505,7 +1509,9 @@ of the derived iterators.
    This is especially useful as a :term:`decorator` for generator functions,
    allowing their generator-iterators to be consumed from multiple threads.
 
-   Example::
+   Example:
+
+   .. doctest::
 
       import threading
 
@@ -1519,7 +1525,7 @@ of the derived iterators.
       it = counter()
 
       def worker():
-          for _ in range(3):
+          for _ in range(5):
               print(next(it))
 
       threads = [threading.Thread(target=worker) for _ in range(2)]
@@ -1552,7 +1558,9 @@ of the derived iterators.
    If *n* is ``0``, return an empty tuple. If *n* is negative, raise
    :exc:`ValueError`.
 
-   Example::
+   Example:
+
+   .. doctest::
 
       import threading
 

Lib/threading.py

@@ -849,7 +849,10 @@ class BrokenBarrierError(RuntimeError):
 class serialize:
     """Wrap a non-concurrent iterator with a lock to enforce sequential access.
 
-    Applies a non-reentrant lock around calls to __next__, send, throw, and close.
+    Applies a non-reentrant lock around calls to __next__.  If the
+    wrapped iterator also defines send(), throw(), or close(), those
+    calls are serialized as well.
+
     Allows iterator and generator instances to be shared by multiple consumer
     threads.
     """
@@ -906,10 +909,12 @@ def synchronized(func):
     Can also be used as a decorator for generator functions definitions
     so that the generator instances are serialized::
 
+        import time
+
         @synchronized
         def enumerate_and_timestamp(iterable):
             for count, value in enumerate(iterable):
-                yield count, time_ns(), value
+                yield count, time.time_ns(), value
 
     """
 
@@ -934,7 +939,7 @@ def concurrent_tee(iterable, n=2):
     """
 
     if n < 0:
-        raise ValueError("n must be positive integer")
+        raise ValueError("n must be a non-negative integer")
     if n == 0:
         return ()
     iterator = _concurrent_tee(iterable)