From 99d39eb112069defc4eb7f42b0d98be254437fce Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Sat, 26 Mar 2022 15:50:14 -0500
Subject: [PATCH] clarifies the traversal order in a Mapper

---
 doc/gotchas.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/gotchas.rst b/doc/gotchas.rst
index 176a07b..dc2b17e 100644
--- a/doc/gotchas.rst
+++ b/doc/gotchas.rst
@@ -13,3 +13,15 @@ order of 1000 intermediate arrays. Following remedies may be helpful:
 - Increasing the recursion limit via :func:`sys.setrecursionlimit`.
 - Checking for any broken memoization implementation in the sub-classed
   :class:`pytato.transform.Mapper`.
+
+
+Traversal order in a :class:`pytato.transform.Mapper`
+-----------------------------------------------------
+
+Although the direction of our DAG is similar to a data-flow graph, the
+traversal order in mapper is the opposite way around i.e. the mapper method of
+a node's user would be *entered* before the node's mapper method. However, the
+mapper method of a node would be *returned* before it's user's mapper method is
+returned. Similar traversal order is routinely seen in `visitors
+<https://en.wikipedia.org/wiki/Visitor_pattern>`__ of other packages like
+:mod:`pymbolic`, `pycparser <https://github.com/eliben/pycparser>`__, etc.
-- 
GitLab