[doc] update documentation

I'm updating (1) some very outdated doc from when the program was not yet
written, and (2) some small stuff inside classes docstrings.

3 files changed, 19 insertions, 1 deletions

diff --git a/src/leap/mx/alias_resolver.py b/src/leap/mx/alias_resolver.py
index 752eac4..c6f2acc 100644
--- a/src/leap/mx/alias_resolver.py
+++ b/src/leap/mx/alias_resolver.py
@@ -19,6 +19,12 @@
 """
 Classes for resolving postfix aliases.
 
+The resolver is queried by the mail server before delivery to the mail spool
+directory, and should return the user uuid. This way, we get rid from the user
+address early and the mail server will delivery the message to
+"<uuid>@<domain>". Later, the mail receiver part of MX will parse the
+"Delivered-To" header to extract the uuid and fetch the user's pgp public key.
+
 Test this with postmap -v -q "foo" tcp:localhost:4242
 
 TODO:
diff --git a/src/leap/mx/check_recipient_access.py b/src/leap/mx/check_recipient_access.py
index 9f79dfe..55460a6 100644
--- a/src/leap/mx/check_recipient_access.py
+++ b/src/leap/mx/check_recipient_access.py
@@ -17,7 +17,12 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 """
-Classes for resolving postfix recipient access
+Classes for resolving postfix recipient access.
+
+The resolver is queried by the mail server before delivery to the mail spool
+directory, and should check if the address is able to receive messages.
+Examples of reasons for denying delivery would be that the user is out of
+quota, is user, or have no pgp public key in the server.
 
 Test this with postmap -v -q "foo" tcp:localhost:2244
 """
@@ -44,6 +49,9 @@ class LEAPPostFixTCPMapAccessServer(postfix.PostfixTCPMapServer):
         Return a code and message depending on the result of the factory's
         get().
 
+        If there's no pgp public key for the user, we currently return a
+        temporary failure saying that the user account is disabled.
+
         For more info, see: http://www.postfix.org/access.5.html
 
         :param value: The uuid and public key.
diff --git a/src/leap/mx/tcp_map.py b/src/leap/mx/tcp_map.py
index 108c2aa..597c830 100644
--- a/src/leap/mx/tcp_map.py
+++ b/src/leap/mx/tcp_map.py
@@ -30,6 +30,10 @@ TCP_MAP_CODE_TEMPORARY_FAILURE = 400
 TCP_MAP_CODE_PERMANENT_FAILURE = 500
 
 
+# we have to also extend from object here to make the class a new-style class.
+# If we don't, we get a TypeError because "new-style classes can't have only
+# classic bases". This has to do with the way abc.ABCMeta works and the old
+# and new style of python classes.
 class LEAPPostfixTCPMapServerFactory(ServerFactory, object):
     """
     A factory for postfix tcp map servers.