From 5b49a58d6190d13a9c962fcb5df74dee41fa0130 Mon Sep 17 00:00:00 2001
From: Juha Jeronen <juha.jeronen@jyu.fi>
Date: Sat, 6 Oct 2018 01:46:03 +0300
Subject: [PATCH] update docstring and docs: ctx is nowadays passed by name

---
 docs/reference.rst      | 31 ++++++++++++++++---------------
 macropy/core/walkers.py | 10 ++++++----
 2 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/docs/reference.rst b/docs/reference.rst
index b968087f..7c77f65b 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -446,7 +446,7 @@ go into the ``**kw``, but can be explicitly declared for ease of use:
 .. code:: python
 
   @Walker
-  def transform(tree, ctx, set_ctx, **kw):
+  def transform(tree, *, ctx, set_ctx, **kw):
       ... do stuff with ctx ...
       set_ctx(...)
       return new_tree
@@ -457,39 +457,40 @@ This section documents what each one does.
 ``ctx``
 ~~~~~~~
 
-The Walker allows the programmer to provide a *context*:
+The Walker allows the programmer to provide a *context*. Here ``ctx``
+is an arbitrary programmer-defined name:
 
 .. code:: python
 
   @Walker
-  def transform(tree, ctx, **kw):
+  def transform(tree, *, ctx, **kw):
       ... do stuff with ctx ...
       return new_tree
 
   new_tree = transform.recurse(old_tree)
-  new_tree = transform.recurse(old_tree, init_ctx)
+  new_tree = transform.recurse(old_tree, ctx=init_ctx)
 
 
-If the ``transform`` function takes an additional argument, it will be
-given the ``init_ctx`` that is passed in as the second argument to the
-``.recurse()`` method (default ``None``).
+If the ``transform`` function takes a named argument ``ctx``, it will be
+given the ``init_ctx`` that is passed in as the named argument ``ctx`` to the
+``.recurse()`` method.
 
 ``set_ctx``
 ~~~~~~~~~~~
 
-Apart from using the ``ctx`` passed in to the ``recurse`` method,
+Apart from using a ``ctx`` passed in to the ``recurse`` method,
 ``transform`` can request for the ``set_ctx`` function:
 
 .. code:: python
 
   @Walker
-  def transform(tree, ctx, set_ctx, **kw):
+  def transform(tree, *, ctx, set_ctx, **kw):
       ... do stuff with ctx ...
-      set_ctx(new_ctx)
+      set_ctx(ctx=new_ctx)
       return new_tree
 
 This will cause all children of the current ``tree`` to receive
-``new_ctx`` as their ``ctx`` argument.
+the value ``new_ctx`` as their named argument ``ctx``.
 
 ``collect``
 ~~~~~~~~~~~
@@ -501,7 +502,7 @@ as it recurses over the AST. This is done by requesting the
 .. code:: python
 
   @Walker
-  def transform(tree, collect, **kw):
+  def transform(tree, *, collect, **kw):
       ...
       collect(value)
       return new_tree
@@ -523,7 +524,7 @@ Lastly, the Walker provides a way to end the recursion, via the
 .. code:: python
 
   @Walker
-  def transform(tree, stop, **kw):
+  def transform(tree, *, stop, **kw):
       ...
       if ...:
           return new_tree
@@ -548,11 +549,11 @@ arguments. For example, you could have a walker such as:
 .. code:: python
 
   @Walker
-  def transform(tree, ctx, set_ctx, collect, stop, **kw):
+  def transform(tree, *, ctx, set_ctx, collect, stop, **kw):
       ...
       return new_tree
 
-  new_tree, collected = transform.recurse_collect(old_tree, initial_ctx)
+  new_tree, collected = transform.recurse_collect(old_tree, ctx=initial_ctx)
 
 
 This provides it a large amount of versatility, and lets you use the
diff --git a/macropy/core/walkers.py b/macropy/core/walkers.py
index 9c72e7ab..be30dd20 100644
--- a/macropy/core/walkers.py
+++ b/macropy/core/walkers.py
@@ -18,11 +18,11 @@ def transform(tree, **kw):
 
     Which is used via:
 
-    new_tree = transform.recurse(old_tree, initial_ctx)
+    new_tree = transform.recurse(old_tree, ctx=initial_ctx)
     new_tree = transform.recurse(old_tree)
-    new_tree, collected = transform.recurse_collect(old_tree, initial_ctx)
+    new_tree, collected = transform.recurse_collect(old_tree, ctx=initial_ctx)
     new_tree, collected = transform.recurse_collect(old_tree)
-    collected = transform.collect(old_tree, initial_ctx)
+    collected = transform.collect(old_tree, ctx=initial_ctx)
     collected = transform.collect(old_tree)
 
     The `transform` function takes the tree to be transformed, in addition to
@@ -46,13 +46,15 @@ def transform(tree, **kw):
     These additional arguments can be declared in the signature, e.g.:
 
     @Walker
-    def transform(tree, ctx, set_ctx, **kw):
+    def transform(tree, *, ctx, set_ctx, **kw):
         ... do stuff with ctx ...
         set_ctx(...)
         return new_tree
 
     for ease of use.
 
+    The other names are literal, but `ctx` is just a user-defined name;
+    it can be anything, and there can be more than one.
     """
     def __init__(self, func):
         self.func = func