From bda3aa99c797d609c185642fb767272e9bf884c1 Mon Sep 17 00:00:00 2001
From: Lucas Hoffmann <l-m-h@web.de>
Date: Fri, 11 Mar 2016 12:37:37 +0100
Subject: Add and update several docstrings.

---
 alot/commands/globals.py |  8 ++++++++
 alot/commands/utils.py   | 14 ++++++++++++++
 alot/crypto.py           | 17 +++++++++++++++--
 alot/helper.py           |  7 ++++---
 4 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/alot/commands/globals.py b/alot/commands/globals.py
index f16647bf..b0ca6b7b 100644
--- a/alot/commands/globals.py
+++ b/alot/commands/globals.py
@@ -853,6 +853,14 @@ class ComposeCommand(Command):
 
     @inlineCallbacks
     def _set_encrypt(self, ui, envelope):
+        """Find and set the encryption keys in an envolope.
+
+        :param ui: the main user interface object
+        :type ui: alot.ui.UI
+        :param envolope: the envolope buffer object
+        :type envolope: alot.buffers.EnvelopeBuffer
+
+        """
         encrypt_keys = []
         for recipient in envelope.headers['To'][0].split(','):
             if not recipient:
diff --git a/alot/commands/utils.py b/alot/commands/utils.py
index a6290671..5ac8a74c 100644
--- a/alot/commands/utils.py
+++ b/alot/commands/utils.py
@@ -9,6 +9,20 @@ from alot import crypto
 
 @inlineCallbacks
 def get_keys(ui, encrypt_keyids, block_error=False):
+    """Get several keys from the GPG keyring.  The keys are selected by keyid
+    and are checked if they can be used for encryption.
+
+    :param ui: the main user interface object
+    :type ui: alot.ui.UI
+    :param encrypt_keyids: the key ids of the keys to get
+    :type encrypt_keyids: list(str)
+    :param block_error: wether error messages for the user should expire
+        automatically or block the ui
+    :type block_error: bool
+    :returns: the available keys indexed by their key hash
+    :rtype: dict(str->gpgme.Key)
+
+    """
     keys = {}
     for keyid in encrypt_keyids:
         try:
diff --git a/alot/crypto.py b/alot/crypto.py
index d5931618..5565b890 100644
--- a/alot/crypto.py
+++ b/alot/crypto.py
@@ -219,10 +219,12 @@ def hash_key(key):
     """
     Returns a hash of the given key. This is a workaround for
     https://bugs.launchpad.net/pygpgme/+bug/1089865
-    and can be removed if the missing feature is added to pygpgme
+    and can be removed if the missing feature is added to pygpgme.
 
     :param key: the key we want a hash of
-    :rtype: a has of the key as string
+    :type key: gpgme.Key
+    :returns: a hash of the key
+    :rtype: str
     """
     hash_str = ""
     for tmp_key in key.subkeys:
@@ -231,6 +233,17 @@ def hash_key(key):
 
 
 def validate_key(key, sign=False, encrypt=False):
+    """Assert that a key is valide and optionally that it can be used for
+    signing or encrypting.  Raise GPGProblem otherwise.
+
+    :param key: the GPG key to check
+    :type key: gpgme.Key
+    :param sign: whether the key should be able to sign
+    :type sign: bool
+    :param encrypt: whether the key should be able to encrypt
+    :type encrypt: bool
+
+    """
     if key.revoked:
         raise GPGProblem("The key \"" + key.uids[0].uid + "\" is revoked.",
                          code=GPGCode.KEY_REVOKED)
diff --git a/alot/helper.py b/alot/helper.py
index 040467a6..359eabdf 100644
--- a/alot/helper.py
+++ b/alot/helper.py
@@ -559,9 +559,10 @@ def parse_mailto(mailto_str):
     Interpret mailto-string
 
     :param mailto_str: the string to interpret. Must conform to :rfc:2368.
-    :return: pair headers,body. headers is a dict mapping str to lists of
-        (str, body) is a str.
-    :rtype: (dict(str-->[str,..], str)
+    :type mailto_str: str
+    :return: the header fields and the body found in the mailto link as a tuple
+        of length two
+    :rtype: tuple(dict(str->list(str)), str)
     """
     if mailto_str.startswith('mailto:'):
         import urllib
-- 
cgit v1.2.3