[kupfer: 36/38] commandexec: Long ridiculous explanation (disclaimer)

[Ulrik Sverdrup <usverdrup src gnome org>]

commit 0da1f7e663b7332e49bb365c294a184d744d3ff6
Author: Ulrik Sverdrup <ulrik sverdrup gmail com>
Date:   Sat Jan 16 16:55:13 2010 +0100

    commandexec: Long ridiculous explanation (disclaimer)

 kupfer/commandexec.py |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)
---
diff --git a/kupfer/commandexec.py b/kupfer/commandexec.py
index 3d52299..3f001a6 100644
--- a/kupfer/commandexec.py
+++ b/kupfer/commandexec.py
@@ -1,3 +1,28 @@
+"""
+The main logic for executing constructed commands.
+
+A command is normally a tuple of (object, action, indirect object).
+Where, of course, the indirect object is often not needed (in this module we
+then pass None in its stead).
+
+This code was once a shining machine; While adding the "comma trick" and
+support for "multiple dispatch" was easy in the rest of the program, it shed
+its casualties here: While the main process is simple, we deal here with all
+the exceptions that are, at the moment, tacked on.
+
+The ActionExecutionContext (ACE) keeps track of its nested invocation, so that
+we can catch the results of commands executed inside other commands. The
+delegation mechanism allows a user of the ACE to indicate that the result of
+the command should be passed on from the earlier (more nested) invocation.
+
+Multiple dispatch is straightforward if the action implements the multiple
+dispatch protocol. Is the protocol not implemented, the command is simply
+"multiplied out": executed once for each object, or once for each combination
+of object and indirect object.
+
+With multiple command execution (and delegation), we must then process and
+merge multiple return values.
+"""
 from __future__ import with_statement
 
 import contextlib