commander: more docstrings
1 files changed, 30 insertions(+), 4 deletions(-)

M vanity/commander.py
M vanity/commander.py +30 -4
@@ 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