commands docs

1 files changed, 30 insertions, 0 deletions

diff --git a/docs/commands.rst b/docs/commands.rst
index c2fb069f..468378ee 100644
--- a/docs/commands.rst
+++ b/docs/commands.rst
@@ -2,6 +2,36 @@ Commands
 =========
 
 .. module:: alot.commands
+
+User actions are given as alot commandline strings that get interpreted
+by :func:`commandfactory` which returns a :class:`Command` object
+representing the action. Commands can then be triggered by
+:meth:`alot.ui.UI.apply_command`.
+
+.. Note:: 
+
+    that the return value
+    of :func:`commandfactory` depends on the current *mode* the user interface is in.
+    The mode identifier is a string that is uniquely defined by the currently focussed
+    :class:`~alot.buffers.Buffer`.
+
+Specific actions are defined as subclasses of :class:`Command` and can be registered
+to a global command pool using the :class:`registerCommand` decorator.
+
+.. note::
+
+    The names of the commands available to the user in any given mode do not correspond
+    one-to-one to these subclasses. You canregister a Command multiple times under different
+    names, with different forced constructor parameters and so on. See for instance the
+    definition of BufferFocusCommand in 'commands/globals.py'::
+
+        @registerCommand(MODE, 'bprevious', forced={'offset': -1},
+                         help='focus previous buffer')
+        @registerCommand(MODE, 'bnext', forced={'offset': +1},
+                         help='focus next buffer')
+        class BufferFocusCommand(Command):
+            ...
+
 .. autoclass:: Command
     :members: