Tweaked docstrings.

eventlet/parallel.py

@@ -6,7 +6,7 @@ import sys
 __all__ = ['GreenPool', 'GreenPile']
     
 class GreenPool(object):
-    """ The Parallel class allows you to easily control coroutine concurrency.
+    """ The GreenPool class is a pool of green threads.
     """
     def __init__(self, size):
         self.size = size
@@ -18,10 +18,10 @@ class GreenPool(object):
         """ Change the max number of coroutines doing work at any given time.
     
         If resize is called when there are more than *new_size*
-        coroutines already working on tasks, they will be allowed to complete but no 
-        new tasks will be allowed to get launched until enough coroutines finish their
-        tasks to drop the overall quantity below *new_size*.  Until then, the 
-        return value of free() will be negative.
+        coroutines already working on tasks, they will be allowed to complete 
+        but no new tasks will be allowed to get launched until enough coroutines 
+        finish their tasks to drop the overall quantity below *new_size*.  Until 
+        then, the return value of free() will be negative.
         """
         size_delta = new_size - self.size 
         self.sem.counter += size_delta
@@ -37,7 +37,8 @@ class GreenPool(object):
         return self.sem.counter
 
     def spawn(self, func, *args, **kwargs):
-        """Run func(*args, **kwargs) in its own green thread.
+        """Run func(*args, **kwargs) in its own green thread.  Returns the
+        GreenThread object that is running the function.  
         """
         return self._spawn(func, *args, **kwargs)
         
@@ -80,7 +81,7 @@ class GreenPool(object):
             self.no_coros_running.send(None)
             
     def waiting(self):
-        """Return the number of coroutines waiting to execute.
+        """Return the number of coroutines waiting to spawn.
         """
         if self.sem.balance < 0:
             return -self.sem.balance
@@ -98,6 +99,8 @@ except NameError:
             raise TypeError("%s object is not an iterator" % type(it))
         
 class GreenPile(object):
+    """GreenPile is an abstraction representing a bunch of I/O-related tasks.
+    """
     def __init__(self, size_or_pool):
         if isinstance(size_or_pool, GreenPool):
             self.pool = size_or_pool
@@ -107,6 +110,8 @@ class GreenPile(object):
         self.counter = 0
             
     def spawn(self, func, *args, **kw):
+        """Runs *func* in its own green thread, with the result available by 
+        iterating over the GreenPile object."""
         self.counter += 1
         try:
             gt = self.pool.spawn(func, *args, **kw)
@@ -119,6 +124,8 @@ class GreenPile(object):
         return self
     
     def next(self):
+        """Wait for the next result, suspending the current coroutine until it
+        is available.  Raises StopIteration when there are no more results."""
         if self.counter == 0:
             raise StopIteration()
         try:
@@ -135,14 +142,9 @@ class GreenPile(object):
                 break
     
     def imap(self, function, *iterables):
-        """This is the same as itertools.imap, except that *func* is executed
-        with the specified concurrency.
-        
-        Make an iterator that computes the *function* using arguments from
-        each of the *iterables*, and using the coroutine concurrency specified 
-        in the GreenPile's constructor.  Like map() except that it returns an 
-        iterator instead of a list and that it stops when the shortest iterable 
-        is exhausted instead of filling in None for shorter iterables.
+        """This is the same as itertools.imap, except that *func* is 
+        executed in separate green threads, with the specified concurrency 
+        control.
         """
         if function is None:
             function = lambda *a: a