[doc] document public methods

3 files changed, 64 insertions, 0 deletions

diff --git a/memoryhole/__init__.py b/memoryhole/__init__.py
index 5cd55b6..fd621ea 100644
--- a/memoryhole/__init__.py
+++ b/memoryhole/__init__.py
@@ -8,6 +8,18 @@ OBSCURED_HEADERS = ('Subject', 'Message-ID', 'Date', 'To', 'From')
 
 
 def unwrap(msg, opengp=Gnupg()):
+    """
+    Unwrap an email replacing and verifying memory hole headers.
+
+    :param msg: the email to be unwrapped
+    :type msg: Message
+    :param openpgp: the implementation of openpgp to use for decryption and/or
+                    verification
+    :type openpgp: OpenPGP
+
+    :return: a dencrypted email
+    :rtype: Message
+    """
     raise NotImplementedError()
 
 
diff --git a/memoryhole/openpgp.py b/memoryhole/openpgp.py
index 5f94861..ac5cb6e 100644
--- a/memoryhole/openpgp.py
+++ b/memoryhole/openpgp.py
@@ -3,10 +3,44 @@ from zope.interface import Interface
 
 class OpenPGP(Interface):
     def encrypt(data, encraddr, singaddr):
+        """
+        Encrypt and sign data.
+
+        :param data: data to be encrypted
+        :type data: str
+        :param encraddr: list of email addresses to encrypt to
+        :type encraddr: [str]
+        :param singaddr: email address to sign with
+        :type singaddr: str
+
+        :return: encrypted and signed data
+        :rtype: str
+        """
         pass
 
     def decrypt(data):
+        """
+        Decrypt and verify data.
+
+        :param data: data to be decrypted
+        :type data: str
+
+        :return: decrypted data
+        :rtype: str
+        """
+        # What about verification???
         pass
 
     def verify(data, signature):
+        """
+        Verify a signature.
+
+        :param data: data to be virified
+        :type data: str
+        :param signature: detached signature
+        :type signature: str
+
+        :return: is signature valid
+        :rtype: bool
+        """
         pass
diff --git a/memoryhole/protection.py b/memoryhole/protection.py
index 900b29a..b179614 100644
--- a/memoryhole/protection.py
+++ b/memoryhole/protection.py
@@ -1,10 +1,28 @@
 from email.mime.application import MIMEApplication
+from email.utils import getaddresses, parseaddr
 
 from memoryhole.gpg import Gnupg
 from memoryhole.rfc3156 import PGPEncrypted, MultipartEncrypted
 
 
 def protect(msg, openpgp=Gnupg(), encrypt=True, obscure=True):
+    """
+    Protect an email with memory hole. It will protect the PROTECTED_HEADERS
+    and if obscure=True will obscure the OBSCURED_HEADERS
+
+    :param msg: the email to be protected
+    :type msg: Message
+    :param openpgp: the implementation of openpgp to use for encryption and/or
+                    signature
+    :type openpgp: OpenPGP
+    :param encrypt: should the message be encrypted
+    :type encrypt: bool
+    :param obscure: should the headers be obscured
+    :type obsucre: bool
+
+    :return: an encrypted and/or signed email
+    :rtype: Message
+    """
     if encrypt:
         return _encrypt_mime(msg, openpgp)