ESQL: Expand javadoc on NodeInfo (#132665)

Author: alex-spies

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.

x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/tree/NodeInfo.java

@@ -16,7 +16,13 @@
 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>
+ * 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
  * for ways to use this less and less.