Index: Doc/library/compiler.rst
===================================================================
--- Doc/library/compiler.rst	(revision 61179)
+++ Doc/library/compiler.rst	(working copy)
@@ -589,50 +589,104 @@
 
 .. module:: compiler.visitor
 
+:class:`compiler.visitor.ASTVisitor` walks the abstract syntax tree created by 
+the parser. The compiler package uses a variant on the visitor pattern that 
+takes advantage of Python's introspection features to eliminate the need for 
+much of the visitor's infrastructure.
 
-The visitor pattern is ...  The :mod:`compiler` package uses a variant on the
-visitor pattern that takes advantage of Python's introspection features to
-eliminate the need for much of the visitor's infrastructure.
+The classes being visited do not need to be programmed to accept visitors. 
+The visitor needs only to define visit methods for nodes it is specifically 
+interested in; a default visit method handles the rest.
 
-The classes being visited do not need to be programmed to accept visitors.  The
-visitor need only define visit methods for classes it is specifically interested
-in; a default visit method can handle the rest.
+.. function:: walk(tree, visitor[, walker [, verbose]])
 
-XXX The magic :meth:`visit` method for visitors.
+    Initiate a preorder walk of *tree*. *visitor* is an instance of a class 
+    that defines a visitNodeType method for each AST node of interest. 
+    NodeType is the name of the AST class to be visited.
+    
+    *walker* is an instance of :class:`ASTVisitor` (the default) or a subclass.
+    This is the class that will actually walk the tree and dispatch to the 
+    visitor.
+    
+    The *verbose* argument is used to set the VERBOSE attribute of walker. 
+    It is used by :class:`ExampleASTVisitor`, not by :class:`ASTVisitor`.
+    
+    Note: This function is also exposed as compiler.walk().
 
 
-.. function:: walk(tree, visitor[, verbose])
+.. class:: ASTVisitor
 
+    The :class:`ASTVisitor` is responsible for walking over the tree in 
+    the correctorder.  A walk begins with a call to :meth:`preorder`.  
+    For each node, it checks the *visitor* argument to :meth:`preorder` for 
+    a method named 'visitNodeType,' where NodeType is the name of the 
+    node's class, e.g. for a :class:`While` node a :meth:`visitWhile` would 
+    be called.  If the method exists, it is called with the node as its 
+    first argument.
 
-.. class:: ASTVisitor()
+    The visitor method for a particular node type can control how child 
+    nodes are visited during the walk. 
 
-   The :class:`ASTVisitor` is responsible for walking over the tree in the correct
-   order.  A walk begins with a call to :meth:`preorder`.  For each node, it checks
-   the *visitor* argument to :meth:`preorder` for a method named 'visitNodeType,'
-   where NodeType is the name of the node's class, e.g. for a :class:`While` node a
-   :meth:`visitWhile` would be called.  If the method exists, it is called with the
-   node as its first argument.
+    The :class:`ASTVisitor` modifies the visitor argument by adding a visit 
+    method to the visitor; this method can be used to visit a particular 
+    child node.  If no visitor is found for a particular node type, the 
+    :meth:`default` method is called.
 
-   The visitor method for a particular node type can control how child nodes are
-   visited during the walk.  The :class:`ASTVisitor` modifies the visitor argument
-   by adding a visit method to the visitor; this method can be used to visit a
-   particular child node.  If no visitor is found for a particular node type, the
-   :meth:`default` method is called.
 
+.. class:: ExampleASTVisitor
+
+    This subclass of :class:`ASTVisitor` can be passed as the walker 
+    argument to walk. It prints information about any node that is not 
+    handled by the visitor object. This is useful for inspecting a tree and 
+    developing a visitor. 
+
+    Set the verbose parameter of :func:`walk` to 1 or higher to get the extra 
+    output.
+
+
 :class:`ASTVisitor` objects have the following methods:
 
-XXX describe extra arguments
 
-
 .. method:: ASTVisitor.default(node[, ...])
 
+    The default *node* handler. The :meth:`dispatch` method calls 
+    :meth:`default` for a node when the visitor does not define a handler 
+    for the node. The default handler visits each child node of the given node.
+    Any extra arguments are passed to the :meth:`dispatch` method.
 
+
 .. method:: ASTVisitor.dispatch(node[, ...])
 
+    Finds the handler for a *node* and dispatches to it. Any extra arguments 
+    are passed to the handler.
 
+
 .. method:: ASTVisitor.preorder(tree, visitor)
+    
+    Initiates a preorder walk of the *tree* using *visitor*. Any extra 
+    arguments are passed to the node handlers.
 
 
+Example
+-------
+
+::
+
+    from compiler import parse, walk
+    from compiler.visitor import ExampleASTVisitor
+
+    testdata = "def aFunction(anArg):\n   return anArg + 1"
+
+    class SimpleVisitor(object):
+        def visitFunction(self, parsedFunc):
+            print "Function %(name)s at %(lineno)s takes %(argnames)s " \
+                " with code %(code)s" % parsedFunc.__dict__
+                
+    if __name__ == "__main__":
+        ast = parse(testdata)
+        walk(ast, SimpleVisitor(), walker=ExampleASTVisitor(), verbose=1)
+
+
 Bytecode Generation
 ===================