--- a/treepkg/cmdexpand.py	Tue Apr 10 12:07:39 2007 +0200
+++ b/treepkg/cmdexpand.py	Tue Apr 10 12:20:47 2007 +0200
@@ -54,6 +54,49 @@
     return rx_word_expansion.sub(replacment, word)
 
 def cmdexpand(string, **kw):
+    """Split the string into 'words' and expand variable references.
+
+The string is first split into words with shlex.split.  Each of the
+words is then subjected to either word expansion or list expansion.
+Word expansion is very similar to what the Template class in Python's
+string module provides:
+
+  '$$' is expanded to '$'
+
+  '$@' is expanded to '@'
+
+  '$identifier' is expanded to the value of the variable given by
+  identifier.  The identifier has the same syntax as a normal Python
+  identifier.  The identifier stops at the first non-identifier
+  character.  The value is converted to a string with str.
+
+  '${identifier}' is treated like '$identifier' and provides a way to
+  delimit the identifier in cases where the identifier is followed by
+  characters that would otherwise be interpreted as part of the
+  identifier.
+
+A word will remain a single word after the expansion even if the
+expanded string would be treated as multiple words by shlex.
+
+A list expansion is applied to words that consist of a '@' followed by
+an identifier.  Nothing else must be in the word.  The variable the
+identifier refers to must be a sequence and the word will be replaced by
+the sequence with each element of the sequence converted to a string
+with str.
+
+The variables known to the function are the keyword arguments.
+
+Examples:
+
+  >>> from cmdexpand import cmdexpand
+  >>> cmdexpand("ssh $user$@$host", user="john", host="python")
+  ['ssh', 'john@python']
+
+  >>> cmdexpand("scp @files $user$@$host:$remotedir", user="john",
+  ...           host="python", files=["main.py", "cmdexpand.py"],
+  ...           remotedir="/home/john/files")
+  ['scp', 'main.py', 'cmdexpand.py', 'john@python:/home/john/files']
+"""
     words = shlex.split(string)
     for index, word in reversed(list(enumerate(words))):
         match = rx_unquoted_at.search(word)