From d6408196c1513968491f8d27dca914ad2abc9eb3 Mon Sep 17 00:00:00 2001
From: Alexander Spies <alexander.spies@elastic.co>
Date: Mon, 11 Aug 2025 18:01:10 +0200
Subject: [PATCH 1/2] Expand javadoc on NodeInfo

Move the javadoc from Node#info onto NodeInfo and make it clearer what
it's used for.
---
 .../java/org/elasticsearch/xpack/esql/core/tree/Node.java    | 4 +---
 .../org/elasticsearch/xpack/esql/core/tree/NodeInfo.java     | 5 ++++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/Node.java b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/Node.java
index cedc86dd3b690..ab5bb7579a6bb 100644
--- a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/Node.java
+++ b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/Node.java
@@ -307,13 +307,11 @@ protected final <E> T transformNodeProps(Class<E> typeToken, Function<? super E,
     }
 
     /**
-     * Return the information about this node.
-     * <p>
      * Normally, you want to use one of the static {@code create} methods to implement this.
      * <p>
      * For {@code QueryPlan}s, it is very important that
      * the properties contain all of the expressions and references relevant to this node, and
-     * that all of the properties are used in the provided constructor; otherwise query plan
+     * that all the properties are used in the provided constructor; otherwise query plan
      * transformations like
      * {@code QueryPlan#transformExpressionsOnly(Function)}
      * will not have an effect.
diff --git a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
index 28e4e739085d4..f33c1891261ca 100644
--- a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
+++ b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
@@ -16,7 +16,10 @@
 import static java.util.Collections.unmodifiableList;
 
 /**
- * Information about a {@link Node}.
+ * All the information about a {@link Node} that is needed to recreate or modify it.
+ * <p>
+ * Allows us to perform traversals and transformations of query plans and expressions without resorting to reflection, e.g. via
+ * {@link Node#transformNodeProps(Class, Function)}, which is used e.g. in {@code QueryPlan#transformExpressionsDown}.
  * <p>
  * All the uses of this are fairly non-OO and we're looking
  * for ways to use this less and less.

From 6302e6209145e7e46d9d5711f4793e6b815393a1 Mon Sep 17 00:00:00 2001
From: Alexander Spies <alexander.spies@elastic.co>
Date: Mon, 11 Aug 2025 18:19:31 +0200
Subject: [PATCH 2/2] Iterate a little

---
 .../org/elasticsearch/xpack/esql/core/tree/NodeInfo.java     | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
index f33c1891261ca..856e3a0035a9a 100644
--- a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
+++ b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java
@@ -18,7 +18,10 @@
 /**
  * All the information about a {@link Node} that is needed to recreate or modify it.
  * <p>
- * Allows us to perform traversals and transformations of query plans and expressions without resorting to reflection, e.g. via
+ * Generally, this will contain the longest constructor of the respective {@link Node} subclass; the non-{@link Source} arguments of that
+ * constructor are called "properties" of the node and are modified when transforming the node.
+ * <p>
+ * This allows us to perform traversals and transformations of query plans and expressions without resorting to reflection, e.g. via
  * {@link Node#transformNodeProps(Class, Function)}, which is used e.g. in {@code QueryPlan#transformExpressionsDown}.
  * <p>
  * All the uses of this are fairly non-OO and we're looking