commands docs

6 files changed, 105 insertions, 8 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
diff --git a/alot/ui.py b/alot/ui.py
index 68010472..0bdf5c82 100644
--- a/alot/ui.py
+++ b/alot/ui.py
@@ -433,6 +433,15 @@ class UI(object):
         return urwid.AttrMap(columns, 'global_footer')
 
     def apply_command(self, cmd):
+        """
+        applies a command
+
+        This calls the pre and post hooks attached to the command,
+        as well as :meth:`cmd.apply`.
+
+        :param cmd: an applicable command
+        :type cmd: :class:`~alot.commands.Command`
+        """
         if cmd:
             if cmd.prehook:
                 self.logger.debug('calling pre-hook')
diff --git a/alot/widgets.py b/alot/widgets.py
index bc9e14a7..582857b3 100644
--- a/alot/widgets.py
+++ b/alot/widgets.py
@@ -511,7 +511,7 @@ class MessageSummaryWidget(urwid.WidgetWrap):
 
     def __init__(self, message, even=True):
         """
-        :param message: amessage
+        :param message: a message
         :type message: alot.db.Message
         :param even: even entry in a pile of messages? Used for theming.
         :type even: bool
diff --git a/docs/commands.rst b/docs/commands.rst
index a59ceaf5..c2fb069f 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -3,6 +3,15 @@ Commands
 
 .. module:: alot.commands
 .. autoclass:: Command
+    :members:
+    
+.. autoclass:: CommandParseError
+.. autoclass:: CommandArgumentParser
+.. autofunction:: commandfactory
+.. autofunction:: lookup_command
+.. autofunction:: lookup_parser
+.. autoclass:: registerCommand
+
 
 Globals
 --------
diff --git a/docs/index.rst b/docs/index.rst
index 3e54ddf5..2864cad4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,9 +12,9 @@ Moreover, it integrates different "managers" responsible for core functionalitie
 * a :class:`~settings.AlotConfigParser` (subclasses :class:`configparser.ConfigParser`) for user settings
 * a :class:`~settings.HookManager` to load custom python code to be used as hooks
 
-All user actions, triggered either by keybindings or the prompt, are given as commandline strings
-that are translated into :class:`commands.Command` objects by
-:func:`commands.commandfactory` and applied by :meth:`ui.UI.apply_command`.
+Every user action, triggered either by keybindings or as input to the commandprompt, is
+given as commandline string that gets :func:`translated <commands.commandfactory>`
+to a :class:`~commands.Command` which is then :meth:`applied <ui.UI.apply_command>`.
 Different actions are defined as a subclasses of :class:`~commands.Command`, which live
 in `alot/commands/MODE.py`, where MODE is the name of the mode (:class:`Buffer` type) they
 are used in.
diff --git a/docs/interface.rst b/docs/interface.rst
index 3e6c9288..242fc7dd 100644
--- a/docs/interface.rst
+++ b/docs/interface.rst
@@ -45,6 +45,7 @@ input and acts on it:
     .. autoattribute:: logger
     .. autoattribute:: accountman
 
+    .. automethod:: apply_command
     .. automethod:: prompt
     .. automethod:: choice
     .. automethod:: notify