From 44e8329dc439382b5c2a3e7829e433f894809716 Mon Sep 17 00:00:00 2001
From: Kali Kaneko <kali@leap.se>
Date: Thu, 2 Jan 2014 17:14:03 -0400
Subject: add documentation to the decorator, fix errorback.

* it also fixes the traceback in the errorback, thanks to
  chiiph, who reads documentation instead of whinning :D

* other minor documentation corrections
---
 mail/src/leap/mail/decorators.py    | 68 ++++++++++++++++++++++++++++++++-----
 mail/src/leap/mail/imap/fetch.py    |  4 +--
 mail/src/leap/mail/imap/messages.py |  5 ++-
 3 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/mail/src/leap/mail/decorators.py b/mail/src/leap/mail/decorators.py
index 9e496056..024a1399 100644
--- a/mail/src/leap/mail/decorators.py
+++ b/mail/src/leap/mail/decorators.py
@@ -19,13 +19,10 @@ Useful decorators for mail package.
 """
 import logging
 import os
-import sys
-import traceback
 
 from functools import wraps
 
 from twisted.internet.threads import deferToThread
-from twisted.python import log
 
 logger = logging.getLogger(__name__)
 
@@ -41,27 +38,68 @@ def deferred(f):
     method wrapper.
     """
     class descript(object):
+        """
+        The class to be used as decorator.
+
+        It takes any method as the passed object.
+        """
+
         def __init__(self, f):
+            """
+            Initializes the decorator object.
+
+            :param f: the decorated function
+            :type f: callable
+            """
             self.f = f
 
         def __get__(self, instance, klass):
+            """
+            Descriptor implementation.
+
+            At creation time, the decorated `method` is unbound.
+
+            It will dispatch the make_unbound method if we still do not
+            have an instance available, and the make_bound method when the
+            method has already been bound to the instance.
+
+            :param instance: the instance of the class, or None if not exist.
+            :type instance: instantiated class or None.
+            """
             if instance is None:
                 # Class method was requested
                 return self.make_unbound(klass)
             return self.make_bound(instance)
 
         def _errback(self, failure):
-            err = failure.value
-            logger.warning('error in method: %s' % (self.f.__name__))
-            logger.exception(err)
-            log.err(err)
+            """
+            Errorback that logs the exception catched.
+
+            :param failure: a twisted failure
+            :type failure: Failure
+            """
+            logger.warning('Error in method: %s' % (self.f.__name__))
+            logger.exception(failure.getTraceback())
 
         def make_unbound(self, klass):
+            """
+            Return a wrapped function with the unbound call, during the
+            early access to the decortad method. This gets passed
+            only the class (not the instance since it does not yet exist).
+
+            :param klass: the class to which the still unbound method belongs
+            :type klass: type
+            """
 
             @wraps(self.f)
             def wrapper(*args, **kwargs):
                 """
-                this doc will vanish
+                We're temporarily wrapping the decorated method, but this
+                should not be called, since our application should use
+                the bound-wrapped method after this decorator class has been
+                used.
+
+                This documentation will vanish at runtime.
                 """
                 raise TypeError(
                     'unbound method {}() must be called with {} instance '
@@ -72,11 +110,23 @@ def deferred(f):
             return wrapper
 
         def make_bound(self, instance):
+            """
+            Return a function that wraps the bound method call,
+            after we are able to access the instance object.
+
+            :param instance: an instance of the class the decorated method,
+                             now bound, belongs to.
+            :type instance: object
+            """
 
             @wraps(self.f)
             def wrapper(*args, **kwargs):
                 """
-                This documentation will disapear
+                Do a proper function wrapper that defers the decorated method
+                call to a separated thread if the LEAPMAIL_DEBUG
+                environment variable is set.
+
+                This documentation will vanish at runtime.
                 """
                 if not os.environ.get('LEAPMAIL_DEBUG'):
                     d = deferToThread(self.f, instance, *args, **kwargs)
diff --git a/mail/src/leap/mail/imap/fetch.py b/mail/src/leap/mail/imap/fetch.py
index fdf14123..cb200be9 100644
--- a/mail/src/leap/mail/imap/fetch.py
+++ b/mail/src/leap/mail/imap/fetch.py
@@ -455,8 +455,8 @@ class LeapIncomingMail(object):
         :param senderPubkey: The key of the sender of the message.
         :type senderPubkey: OpenPGPKey
 
-        :return: A unitary tuple containing a decrypted message and
-                 a bool indicating wether the signature is valid.
+        :return: A tuple containing a decrypted message and
+                 a bool indicating whether the signature is valid.
         :rtype: (Message, bool)
         """
         log.msg('maybe decrypting inline encrypted msg')
diff --git a/mail/src/leap/mail/imap/messages.py b/mail/src/leap/mail/imap/messages.py
index c69c023c..47c40d57 100644
--- a/mail/src/leap/mail/imap/messages.py
+++ b/mail/src/leap/mail/imap/messages.py
@@ -695,6 +695,9 @@ class LeapMessage(fields, MailParser, MBoxParser):
 SoledadWriterPayload = namedtuple(
     'SoledadWriterPayload', ['mode', 'payload'])
 
+# TODO we could consider using enum here:
+# https://pypi.python.org/pypi/enum
+
 SoledadWriterPayload.CREATE = 1
 SoledadWriterPayload.PUT = 2
 SoledadWriterPayload.BODY_CREATE = 3
@@ -758,7 +761,7 @@ class SoledadDocWriter(object):
     Message deduplication.
 
     We do a query for the content hashes before writing to our beloved
-    slcipher backend of Soledad. This means, by now, that:
+    sqlcipher backend of Soledad. This means, by now, that:
 
     1. We will not store the same attachment twice, only the hash of it.
     2. We will not store the same message body twice, only the hash of it.
-- 
cgit v1.2.3