diff -r 31114e40178d -r 0a5eb5aac0be iro/model/job.py
--- a/iro/model/job.py	Thu Mar 29 13:46:37 2012 +0200
+++ b/iro/model/job.py	Thu Mar 29 16:27:40 2012 +0200
@@ -8,12 +8,25 @@
 from .dbdefer import dbdefer
 
 class ExJob:
-    '''One Job is a class that handles one job. One Job has multiple tasks.'''
+    ''' A ExJob object represents a message to multiple recipients over multiple offers to send.  
+
+    One single message to one recipient is handeld in :class:`iro.controller.task.Task`.
+    This class holds connections to all tasks.
+    This class is responsiple to update the status in database of one job and updating the bill.
+    '''
     
     synchronized = ["incStatus", "_status"]
 
     def __init__(self, dbjob, recipients, message, offers):
-        self.dbjob = dbjob       #Connection to mysql job element (id)
+        """Constructor of ExJob.
+        
+        :param dbjob: primary key of the job element in database
+        :param list recipients: list of all recipients
+        :param `iro.model.message.Message` message: message to send
+        :param list offers: list of all possible offers to send message over
+        """
+
+        self.dbjob = dbjob       #Connection to database job element (id)
         self.message = message
         self.recipients = recipients
         self.offers = offers
@@ -23,13 +36,23 @@
         log.msg("Job(%s) created."%(self.dbjob))
 
     def addTask(self,task):
+        """adding a task to tasks dict - key is the recipient.
+        
+        :param `iro.controller.task.Task` task: a task
+        """
         self.tasks[task.recipient] = task
 
     def incStatus(self):
+        """increments the processed messages (function is threadsafe)."""
         self.c += 1
         return self.c
 
     def _status(self, session, status):
+        """updates the status of the database object (function is threadsafe).
+
+        :param session: a valid database session
+        :param string status: new status
+        """
         job = schema.Job.get(session, self.dbjob)
         if self.status == "error":
             return
@@ -42,6 +65,10 @@
 
     @dbdefer
     def setStatus(self, session, task, status):
+        """callback of one task.
+        
+        This function  updates the database object and the bill.
+        """
         c = self.incStatus()
         job = schema.Job.get(session, self.dbjob)
         
@@ -59,6 +86,10 @@
 
     @dbdefer
     def setError(self, session, task, err):
+        """errback for one task.
+
+        This function updates the database object.
+        """
         self.incStatus()
         if self.status != "error":
             self._status(session,"error")
@@ -67,9 +98,19 @@
 threadable.synchronize(ExJob)
 
 class ExJobs(dict, MutableMapping):
-
+    """ a dict to handle all jobs.
+    """
     @dbdefer
     def create(self, session, user, recipients, message, offers, info=None):
+        """creates on new Job.
+        
+        :param session: a valid session ( created by decorator :func:`iro.model.dbdefer.dbdefer`)
+        :param `iro.model.schema.User` user: a user object
+        :param list recipients: list of all recipients
+        :param `iro.model.message.Message` message: message to send
+        :param list offers: a list of offers ( list will be reduced to the allowed offers for the **user** -- using :func:`iro.model.offer.extendProvider`)
+        :returns: the new job
+        """
         user = session.merge(user)
         job = schema.Job(info=info, status="started")
         user.jobs.append(job)
@@ -80,3 +121,4 @@
         return self[job.id]
 
 exJobs = ExJobs()
+"""the dict of all available jobs."""