doc: docstrings

5 files changed, 32 insertions, 16 deletions

diff --git a/alot/account.py b/alot/account.py
index 83126f4c..1a4a28a2 100644
--- a/alot/account.py
+++ b/alot/account.py
@@ -24,7 +24,6 @@ class Account(object):
     settings, can send and store mails to maildirs (drafts/send).
 
     .. note::
-
         This is an abstract class that leaves :meth:`send_mail` unspecified.
         See :class:`SendmailAccount` for a subclass that uses a sendmail
         command to send out mails.
@@ -74,7 +73,8 @@ class Account(object):
 
     def store_mail(self, mbx, mail):
         """
-        stores given mail in mailbox. If mailbox is maildir, set the S-flag.
+        stores given mail in mailbox. If mailbox is maildir, set the S-flag and
+        return path to newly added mail. Oherwise this will return `None`.
 
         :param mbx: mailbox to use
         :type mbx: :class:`mailbox.Mailbox`
diff --git a/alot/addressbooks.py b/alot/addressbooks.py
index a8453b09..06e9284b 100644
--- a/alot/addressbooks.py
+++ b/alot/addressbooks.py
@@ -13,7 +13,6 @@ class AddressBook(object):
     """can look up email addresses and realnames for contacts.
 
     .. note::
-
         This is an abstract class that leaves :meth:`get_contacts`
         unspecified. See :class:`AbookAddressBook` and
         :class:`MatchSdtoutAddressbook` for implementations.
@@ -57,6 +56,7 @@ class AbookAddressBook(AddressBook):
 
 class MatchSdtoutAddressbook(AddressBook):
     """:class:`AddressBook` that parses a shell command's output for lookups"""
+
     def __init__(self, command, match=None):
         """
         :param command: lookup command
diff --git a/alot/buffers.py b/alot/buffers.py
index 7ea5359e..331375b6 100644
--- a/alot/buffers.py
+++ b/alot/buffers.py
@@ -49,7 +49,10 @@ class Buffer(object):
         pass
 
     def get_info(self):
-        """return dict of meta infos about this buffer"""
+        """
+        return dict of meta infos about this buffer.
+        This can be requested to be displayed in the statusbar.
+        """
         return {}
 
 
diff --git a/alot/helper.py b/alot/helper.py
index a8327145..973443b0 100644
--- a/alot/helper.py
+++ b/alot/helper.py
@@ -55,7 +55,7 @@ def split_commandstring(cmdstring):
 def safely_get(clb, E, on_error=''):
     """
     returns result of :func:`clb` and falls back to `on_error`
-    in case `E` is raised.
+    in case exception `E` is raised.
 
     :param clb: function to evaluate
     :type clb: callable
@@ -112,8 +112,9 @@ def string_sanitize(string, tab_width=8):
 
 
 def string_decode(string, enc='ascii'):
-    """safely decodes string to unicode bytestring,
-    respecting `enc` as a hint"""
+    """
+    safely decodes string to unicode bytestring, respecting `enc` as a hint.
+    """
 
     if enc is None:
         enc = 'ascii'
@@ -127,6 +128,7 @@ def string_decode(string, enc='ascii'):
 
 
 def shorten(string, maxlen):
+    """shortens string if longer than maxlen, appending ellipsis"""
     if maxlen > 1 and len(string) > maxlen:
         string = string[:maxlen - 1] + u'\u2026'
     return string[:maxlen]
@@ -145,17 +147,14 @@ def shorten_author_string(authors_string, maxlength):
 
       - First author is always shown (if too long is shorten with ellipsis)
 
-      - If possible, last author is also shown (if too long, uses
-        ellipsis)
+      - If possible, last author is also shown (if too long, uses ellipsis)
 
       - If there are more than 2 authors in the thread, show the
-        maximum of them. More recent senders have more priority (Is
-        the list of authors already sorted by the date of msgs????)
+        maximum of them. More recent senders have higher priority.
 
       - If it is finally necessary to hide any author, an ellipsis
         between first and next authors is added.
 
-
     >>> authors = u'King Kong, Mucho Muchacho, Jaime Huerta, Flash Gordon'
     >>> print shorten_author_string(authors, 60)
     King Kong, Mucho Muchacho, Jaime Huerta, Flash Gordon
diff --git a/alot/ui.py b/alot/ui.py
index 5268752b..49c878b9 100644
--- a/alot/ui.py
+++ b/alot/ui.py
@@ -142,6 +142,13 @@ class UI(object):
             self.update()
 
     def apply_commandline(self, cmdline):
+        """
+        Interprets a command line string and applies the resulting
+        (sequence of) :class:`Commands <alot.commands.Command>`.
+
+        :param cmdline: command line to interpret
+        :type cmdline: str
+        """
         # split commandline if necessary
         cmd = None
         cmdlist = split_commandline(cmdline)
@@ -177,7 +184,10 @@ class UI(object):
         self._locked = True
 
     def prompt(self, prefix, text=u'', completer=None, tab=0, history=[]):
-        """prompt for text input
+        """
+        prompt for text input.
+        This returns a :class:`~twisted.defer.Deferred` that calls back with
+        the input string.
 
         :param prefix: text to print before the input field
         :type prefix: str
@@ -305,7 +315,11 @@ class UI(object):
     def get_buffers_of_type(self, t):
         """
         returns currently open buffers for a given subclass of
-        :class:`~alot.buffers.Buffer`
+        :class:`~alot.buffers.Buffer`.
+
+        :param t: Buffer class
+        :type t: alot.buffers.Buffer
+        :rtype: list
         """
         return filter(lambda x: isinstance(x, t), self.buffers)
 
@@ -330,7 +344,7 @@ class UI(object):
     def choice(self, message, choices={'y': 'yes', 'n': 'no'},
                select=None, cancel=None, msg_position='above'):
         """
-        prompt user to make a choice
+        prompt user to make a choice.
 
         :param message: string to display before list of choices
         :type message: unicode
@@ -388,7 +402,7 @@ class UI(object):
 
     def notify(self, message, priority='normal', timeout=0, block=False):
         """
-        opens notification popup
+        opens notification popup.
 
         :param message: message to print
         :type message: str