diff -r 280303da5b30 Lib/threading.py
--- a/Lib/threading.py	Wed May 29 20:58:19 2013 +0200
+++ b/Lib/threading.py	Thu May 30 02:32:36 2013 -0700
@@ -44,10 +44,12 @@
 _trace_hook = None
 
 def setprofile(func):
+    """Set a profile function for all threads started from the threading module."""
     global _profile_hook
     _profile_hook = func
 
 def settrace(func):
+    """Set a trace function for all threads started from the threading module."""
     global _trace_hook
     _trace_hook = func
 
@@ -61,6 +63,10 @@
     return _CRLock(*args, **kwargs)
 
 class _RLock:
+    """This class implements reentrant lock objects. A reentrant lock must be released
+    by the thread that acquired it. Once a thread has acquired a reentrant lock,
+    the same thread may acquire it again without blocking; the thread must release it
+    once for each time it has acquired it."""
 
     def __init__(self):
         self._block = _allocate_lock()
@@ -77,6 +83,7 @@
                 self.__class__.__name__, owner, self._count)
 
     def acquire(self, blocking=True, timeout=-1):
+        """Acquire a lock, blocking or non-blocking."""
         me = get_ident()
         if self._owner == me:
             self._count = self._count + 1
@@ -90,6 +97,7 @@
     __enter__ = acquire
 
     def release(self):
+        """Release a lock, decrementing the recursion level."""
         if self._owner != get_ident():
             raise RuntimeError("cannot release un-acquired lock")
         self._count = count = self._count - 1
@@ -123,6 +131,8 @@
 
 
 class Condition:
+    """This class implements condition variable objects. A condition variable allows one
+    or more threads to wait until they are notified by another thread."""
 
     def __init__(self, lock=None):
         if lock is None:
@@ -173,6 +183,9 @@
             return True
 
     def wait(self, timeout=None):
+        """Wait until notified or until a timeout occurs. If the calling thread
+        has not acquired the lock when this method is called, a RuntimeError is
+        raised."""
         if not self._is_owned():
             raise RuntimeError("cannot wait on un-acquired lock")
         waiter = _allocate_lock()
@@ -198,6 +211,10 @@
             self._acquire_restore(saved_state)
 
     def wait_for(self, predicate, timeout=None):
+        """Wait until a condition evaluates to True.
+        predicate should be a callable which result will be interpreted
+        as a boolean value. A timeout may be provided giving the maximum
+        time to wait."""
         endtime = None
         waittime = timeout
         result = predicate()
@@ -214,6 +231,7 @@
         return result
 
     def notify(self, n=1):
+        """By default, wake up one thread waiting on this condition, if any."""
         if not self._is_owned():
             raise RuntimeError("cannot notify on un-acquired lock")
         __waiters = self._waiters
@@ -228,12 +246,16 @@
                 pass
 
     def notify_all(self):
+        """Wake up all threads waiting on this condition."""
         self.notify(len(self._waiters))
 
     notifyAll = notify_all
 
 
 class Semaphore:
+    """This class implements semaphore objects. A semaphore manages a counter
+    representing the number of release() calls minus the number of acquire()
+    calls, plus an initial value."""
 
     # After Tim Peters' semaphore class, but not quite the same (no maximum)
 
@@ -244,6 +266,7 @@
         self._value = value
 
     def acquire(self, blocking=True, timeout=None):
+        """Acquire a semaphore."""
         if not blocking and timeout is not None:
             raise ValueError("can't specify timeout for non-blocking acquire")
         rc = False
@@ -268,6 +291,7 @@
     __enter__ = acquire
 
     def release(self):
+        """Release a semaphore, incrementing the internal counter by one."""
         with self._cond:
             self._value = self._value + 1
             self._cond.notify()
@@ -289,7 +313,9 @@
 
 
 class Event:
-
+    """Class implementing event objects. An event manages a flag that can be set
+    to true with the set() method and reset to false with the clear() method.
+    The wait() method blocks until the flag is true. The flag is initially false."""
     # After Tim Peters' event class (without is_posted())
 
     def __init__(self):
@@ -301,11 +327,13 @@
         self._cond.__init__()
 
     def is_set(self):
+        """Return true if and only if the internal flag is true."""
         return self._flag
 
     isSet = is_set
 
     def set(self):
+        """Set the internal flag to true. All threads waiting for it to become true are awakened."""
         self._cond.acquire()
         try:
             self._flag = True
@@ -314,6 +342,7 @@
             self._cond.release()
 
     def clear(self):
+        """Reset the internal flag to false."""
         self._cond.acquire()
         try:
             self._flag = False
@@ -321,6 +350,7 @@
             self._cond.release()
 
     def wait(self, timeout=None):
+        """Block until the internal flag is true."""
         self._cond.acquire()
         try:
             signaled = self._flag
@@ -518,6 +548,9 @@
 # Main class for threads
 
 class Thread:
+    """The Thread class represents an activity that is run in a separate thread
+    of control. There are two ways to specify the activity: by passing a callable
+    object to the constructor, or by overriding the run() method in a subclass."""
 
     __initialized = False
     # Need to store a reference to sys.exc_info for printing
@@ -573,6 +606,7 @@
         return "<%s(%s, %s)>" % (self.__class__.__name__, self._name, status)
 
     def start(self):
+        """Start the thread’s activity."""
         if not self._initialized:
             raise RuntimeError("thread.__init__() not called")
 
@@ -589,6 +623,7 @@
         self._started.wait()
 
     def run(self):
+        """Method representing the thread’s activity."""
         try:
             if self._target:
                 self._target(*self._args, **self._kwargs)
@@ -727,6 +762,10 @@
                 raise
 
     def join(self, timeout=None):
+        """Wait until the thread terminates.
+
+        When the timeout argument is not present or None, the operation will block
+        until the thread terminates."""
         if not self._initialized:
             raise RuntimeError("Thread.__init__() not called")
         if not self._started.is_set():
@@ -751,6 +790,7 @@
 
     @property
     def name(self):
+        """A string used for identification purposes only. It has no semantics."""
         assert self._initialized, "Thread.__init__() not called"
         return self._name
 
@@ -761,10 +801,13 @@
 
     @property
     def ident(self):
+        """The 'thread identifier' of this thread or None if the thread has not been started.
+        This is a nonzero integer."""
         assert self._initialized, "Thread.__init__() not called"
         return self._ident
 
     def is_alive(self):
+        """Return whether the thread is alive."""
         assert self._initialized, "Thread.__init__() not called"
         return self._started.is_set() and not self._stopped
 
@@ -772,6 +815,10 @@
 
     @property
     def daemon(self):
+        """A boolean value indicating whether this thread is
+        a daemon thread (True) or not (False).
+        This must be set before start() is called,
+        otherwise RuntimeError is raised."""
         assert self._initialized, "Thread.__init__() not called"
         return self._daemonic
 
@@ -784,15 +831,19 @@
         self._daemonic = daemonic
 
     def isDaemon(self):
+        """Old getter API for daemon"""
         return self.daemon
 
     def setDaemon(self, daemonic):
+        """Old setter API for daemon"""
         self.daemon = daemonic
 
     def getName(self):
+        """Old getter API for name"""
         return self.name
 
     def setName(self, name):
+        """Old setter API for name"""
         self.name = name
 
 # The timer class was contributed by Itamar Shtull-Trauring
@@ -814,7 +865,7 @@
         self.finished = Event()
 
     def cancel(self):
-        """Stop the timer if it hasn't finished yet"""
+        """Stop the timer, and cancel the execution of the timer's action."""
         self.finished.set()
 
     def run(self):
@@ -883,6 +934,7 @@
 # Global API functions
 
 def current_thread():
+    """Return the current Thread object, corresponding to the caller's thread of control."""
     try:
         return _active[get_ident()]
     except KeyError:
@@ -891,12 +943,14 @@
 currentThread = current_thread
 
 def active_count():
+    """Return the number of Thread objects currently alive."""
     with _active_limbo_lock:
         return len(_active) + len(_limbo)
 
 activeCount = active_count
 
 def _enumerate():
+    """Return a list of all Thread objects currently alive."""
     # Same as enumerate(), but without the lock. Internal use only.
     return list(_active.values()) + list(_limbo.values())