Further improve commentary about ChangeVarNodesWalkExpression()

The updated comment explains why we use ChangeVarNodes_walker() instead of
expression_tree_walker(), and provides a bit more detail about the differences
in processing top-level Query and subqueries.

Author: Alexander Korotkov <aekorotkov@gmail.com>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Discussion: https://postgr.es/m/CAPpHfdvbjq342WTQ705Wmqhe8794pcp7wospz%2BWUJ2qB7vuOqA%40mail.gmail.com
Backpatch-through: 18

diff --git a/src/backend/rewrite/rewriteManip.c b/src/backend/rewrite/rewriteManip.c
index dc803a1703736593797bbbc1c517fd21425b8ed9..4bf4aa0d6d11f416637e86fb39d13e010727c650 100644 (file)
--- a/src/backend/rewrite/rewriteManip.c
+++ b/src/backend/rewrite/rewriteManip.c
@@ -742,11 +742,17 @@ ChangeVarNodes(Node *node, int rt_index, int new_index, int sublevels_up)
  *
  * This is intended to be used by a callback that needs to recursively
  * process subexpressions of some node being visited by an outer
- * ChangeVarNodesExtended call (not letting ChangeVarNodes_walker do that).
- * Hence, we invoke ChangeVarNodes_walker directly.  This means that if
- * the passed Node is a Query node, it will be treated as a sub-Query,
- * so sublevels_up will be incremented immediately.  Do not apply this
- * to a top-level Query node, or you'll likely get wrong results.
+ * ChangeVarNodesExtended call, instead of relying on ChangeVarNodes_walker's
+ * default recursion.  We invoke ChangeVarNodes_walker directly rather than
+ * via expression_tree_walker, because expression_tree_walker only visits
+ * child nodes and would fail to process the passed node itself --
+ * for example, a bare Var node would not get its varno adjusted.
+ *
+ * Because this calls ChangeVarNodes_walker directly, if the passed node is
+ * a Query, it will be treated as a sub-Query: sublevels_up is incremented
+ * before recursing into it, and Query-level fields (resultRelation,
+ * mergeTargetRelation, rowMarks, etc.) will not be adjusted.  Do not apply
+ * this to a top-level Query node; use ChangeVarNodesExtended for that.
  */
 bool
 ChangeVarNodesWalkExpression(Node *node, ChangeVarNodes_context *context)