# HG changeset patch
# User John Mulligan <phlogistonjohn@asynchrono.us>
# Date 1257120840 18000
#      Sun Nov 01 19:14:00 2009 -0500
# Node ID 296037180111d5cf5c80e65a1b6cc2d8d4385cea
# Parent  073dbac090e540697b5f80516cf42c7ade191d77
commander: more docstrings

diff --git a/vanity/commander.py b/vanity/commander.py
--- a/vanity/commander.py
+++ b/vanity/commander.py
@@ -8,13 +8,39 @@
 #
 """parse command lines with subcommands
 
+This module provides various utilities for hooking multiple
+subcommands under a single script. The programmer creates
+a table of commands and then either parses the command
+line and manually dispatches the command, or uses the main(...)
+or launch(...) functions that perform automatic dispatch.
 
-XXX
-ret = commander.launch(globalopts, cmdtable, args)
+Example:
+  >>> # cmd1 and cmd2 are functions
+  >>> cmdtable = [
+  ...   ('name', cmd1, '', [OPTS], 'something helpful'),
+  ...   ('other', cmd2, 'alias|alais2', [], 'something helpless'),
+  ...   ]
+  >>> ret = commander.launch(OPTS, cmdtable, argv)
+  >>> cmd, opts, args = commander.parse(OPTS, cmdtable, argv)
 
-cmd, opts, args = commander.parse(globalopts, cmdtable, args)
+The entries in the command table may be tuples, dictionaries,
+or commander.Command objects. As an alternate form of the table
+a dictionary mapping command names to dictionaries may be used.
+
+>>> table = {
+...     'mycommand': {'target':cmd1, 'opts':[], 'help': 'foo bar'},
+...     }
+
 
-XXX
+The parse function parses a command line and returns a 
+command object, opts, args triple. The launch command parses
+and then dispatches the command function, it may raise
+a parsing exception or a HelpWanted exception. The programmer
+should catch the exception and print usage if this exception is
+raised. Finally the main function both dispatches and provides
+simple help usage and error handling for cli parsing errors.
+By default, error messages will be written to the standard
+output.
 """
 
 from vanity import cli