# HG changeset patch
# User Sandro Knauß <knauss@netzguerilla.net>
# Date 1333038713 -7200
# Node ID 584b9c97ecfdfaa988c4b42f935cac0dfc456764
# Parent  52284710c0b4a15a7633e76942de64bd8ac14b66
iro.controller: adding docstrings

diff -r 52284710c0b4 -r 584b9c97ecfd iro/controller/pool.py
--- a/iro/controller/pool.py	Thu Mar 29 18:27:15 2012 +0200
+++ b/iro/controller/pool.py	Thu Mar 29 18:31:53 2012 +0200
@@ -2,30 +2,41 @@
 from twisted.internet import threads
 
 class Pool:
+    """wrapper class to handles a twisted threadpool"""
     def __init__(self,name,maxthreads):
+        """
+        :param string name: name of the threadpool
+        :param integer maxthreads: how many thread a allowed at maximum
+        """
         self.maxthreads = maxthreads
         self.pool =  ThreadPool(minthreads=1, maxthreads=maxthreads, name=name)
         self.reactor = None
 
     def start(self, reactor):
+        """stats the pool and adds the pool.stop function to the stop procedure.
+        
+        :param reactor: a valid twisted reactor
+        """
         self.pool.start()
         self.reactor = reactor
         self.reactor.addSystemEventTrigger('before', 'shutdown', self.pool.stop)
 
     def run(self,f,*args,**kwargs):
-        """To run a function in Twisted's thread pool"""
+        """run a function in Twisted's thread pool"""
         return threads.deferToThreadPool(self.reactor, self.pool, f, *args, **kwargs)
 
-#task Pool for sending
 taskPool = Pool('task',5)
+"""taskpool to handle sending data"""
 
-#db Pool to handle reqests to sqlalchemy
 dbPool = Pool('database',5)
+"""pool to handle database connection via sqlalchemy""" 
 
-# all pools in one list
 pools=[taskPool,dbPool]
+"""all available pools"""
 
 def startPool(reactor):
-    '''starting all pools'''
+    '''run start function for all items in :attr:`pools`'''
     for pool in pools:
         pool.start(reactor)
+
+__all__=["Pool", "startPool", "dbPool", "taskPool", "pools"]
diff -r 52284710c0b4 -r 584b9c97ecfd iro/controller/task.py
--- a/iro/controller/task.py	Thu Mar 29 18:27:15 2012 +0200
+++ b/iro/controller/task.py	Thu Mar 29 18:31:53 2012 +0200
@@ -11,25 +11,34 @@
 from .pool  import taskPool
 
 class Task:
-    '''one single part of a job.
-    a task is one message to one recipient
+    '''A Task is one message to one recipient and is a part of one :class:`iro.model.job.ExJob`.
     '''
     def __init__(self, recipient, job):
+        """
+        :param recipient: a recipient
+        :param `iro.model.job.ExJob` job: connected job
+        """
         self.recipient = recipient
         self.job = job
         self.status = None
         self.error = False
 
     def setStatus(self,status):
+        """callback, to set status of task"""
         self.status = status
         return status
 
     def setError(self, error):
+        """errback to set error of task"""
         self.status = error
         self.error = True
         return error
 
     def start(self):
+        """Starting to send message to recipient.
+
+        :return: a defer, that is fired, when message is sended successfully over any offer.
+        """
         self.d = Deferred()
         self.d.addCallback(self.setStatus)
         self.d.addCallback(partial(self.job.setStatus,self))
@@ -39,6 +48,7 @@
         return self.d
 
     def _run(self):
+        """sends the message to recipient, tries all possible offers."""
         os= iter(self.job.offers)
         def n():
             try:
@@ -61,6 +71,14 @@
 
 @inlineCallbacks
 def createJob(user,recipients, msg, offers, info=None):
+    """Creates a :class:`iro.model.job.ExJob` and start for all recipients one task.
+    
+    :param `iro.model.schema.User` user: the sender 
+    :param `iro.model.message.Message` msg: the message
+    :param list offers: a list of possible offer and provider names, to try to send the message over. The first entry will be tried first.
+    :param string info: a bill group name
+    :return: the new :class:`iro.model.job.ExJob` object.
+    """
     job = yield exJobs.create(user, recipients, msg, offers, info)
     for r in recipients:
         task = Task(r,job)