1 files changed, 82 insertions, 4 deletions

diff --git a/alot/commands/__init__.py b/alot/commands/__init__.py
index d5ea60bc..d369de1b 100644
--- a/alot/commands/__init__.py
+++ b/alot/commands/__init__.py
@@ -12,16 +12,26 @@ import alot.helper
 class Command(object):
     """base class for commands"""
     def __init__(self, prehook=None, posthook=None):
+        """
+        :param prehook: name of the hook to call directly before
+                        applying this command
+        :type prehook: str
+        :param posthook: name of the hook to call directly after
+                         applying this command
+        :type posthook: str
+        """
         self.prehook = prehook
         self.posthook = posthook
         self.undoable = False
         self.help = self.__doc__
 
     def apply(self, caller):
+        """code that gets executed when this command is applied"""
         pass
 
     @classmethod
     def get_helpstring(cls):
+        # TODO make this interpret kwargs
         return cls.__doc__
 
 
@@ -36,8 +46,17 @@ COMMANDS = {
 
 
 def lookup_command(cmdname, mode):
-    """returns commandclass, argparser and forcedparams
-    for `cmdname` in `mode`"""
+    """
+    returns commandclass, argparser and forced parameters used to construct
+    a command for `cmdname` when called in `mode`.
+
+    :param cmdname: name of the command to look up
+    :type cmdname: str
+    :param mode: mode identifier
+    :type mode: str
+    :rtype: (:class:`Command`, :class:`~argparse.ArgumentParser`,
+            dict(str->dict))
+    """
     if cmdname in COMMANDS[mode]:
         return COMMANDS[mode][cmdname]
     elif cmdname in COMMANDS['global']:
@@ -47,16 +66,26 @@ def lookup_command(cmdname, mode):
 
 
 def lookup_parser(cmdname, mode):
+    """
+    returns the :class:`CommandArgumentParser` used to construct a
+    command for `cmdname` when called in `mode`.
+
+    >>> (cmd, parser, kwargs) = lookup_command('save', 'thread')
+    >>> cmd
+    <class 'alot.commands.thread.SaveAttachmentCommand'>
+    """
     return lookup_command(cmdname, mode)[1]
 
 
 class CommandParseError(Exception):
+    """could not parse commandline string"""
     pass
 
 
 class CommandArgumentParser(argparse.ArgumentParser):
-    """ArgumentParser that raises `CommandParseError`
-    instead of printing to sys.stderr"""
+    """
+    :class:`~argparse.ArgumentParser` that raises :class:`CommandParseError`
+    instead of printing to `sys.stderr`"""
     def exit(self, message):
         raise CommandParseError(message)
 
@@ -65,8 +94,41 @@ class CommandArgumentParser(argparse.ArgumentParser):
 
 
 class registerCommand(object):
+    """
+    Decorator used to register a :class:`Command` as
+    handler for command `name` in `mode` so that it
+    can be looked up later using :func:`lookup_command`.
+
+    Consider this example that shows how a :class:`Command` class
+    definition is decorated to register it as handler for
+    'save' in mode 'thread' and add boolean and string arguments::
+
+        @registerCommand('thread', 'save', arguments=[
+            (['--all'], {'action': 'store_true', 'help':'save all'}),
+            (['path'], {'nargs':'?', 'help':'path to save to'})],
+            help='save attachment(s)')
+        class SaveAttachmentCommand(Command):
+            pass
+
+    """
     def __init__(self, mode, name, help=None, usage=None,
                  forced={}, arguments=[]):
+        """
+        :param mode: mode identifier
+        :type mode: str
+        :param name: command name to register as
+        :type name: str
+        :param help: help string summarizing what this command does
+        :type help: str
+        :param usage: overides the auto generated usage string
+        :type usage: str
+        :param forced: keyword parameter used for commands constructor
+        :type forced: dict (str->str)
+        :param arguments: list of arguments given as pairs (args, kwargs)
+                          accepted by
+                          :meth:`argparse.ArgumentParser.add_argument`.
+        :type arguments: list of (list of str, dict (str->str)
+        """
         self.mode = mode
         self.name = name
         self.help = help
@@ -85,6 +147,22 @@ class registerCommand(object):
 
 
 def commandfactory(cmdline, mode='global'):
+    """
+    parses `cmdline` and constructs a :class:`Command`.
+
+    :param cmdline: command line to interpret
+    :type cmdline: str
+    :param mode: mode identifier
+    :type mode: str
+
+    >>> cmd = alot.commands.commandfactory('save --all /foo', mode='thread')
+    >>> cmd
+    <alot.commands.thread.SaveAttachmentCommand object at 0x272cf10
+    >>> cmd.all
+    True
+    >>> cmd.path
+    u'/foo'
+    """
     # split commandname and parameters
     if not cmdline:
         return None