diff --git a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/expression/UnresolvedAttribute.java b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/expression/UnresolvedAttribute.java
index 428ab4023a3f9..e73ee2f09458d 100644
--- a/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/expression/UnresolvedAttribute.java
+++ b/x-pack/plugin/esql-core/src/main/java/org/elasticsearch/xpack/esql/core/expression/UnresolvedAttribute.java
@@ -19,7 +19,16 @@
 import java.util.List;
 import java.util.Objects;
 
-// unfortunately we can't use UnresolvedNamedExpression
+/**
+ * An unresolved attribute. We build these while walking the syntax
+ * tree and then resolve them into other {@link Attribute} subclasses during
+ * analysis.
+ * <p>
+ *     For example, if they reference the data directly from lucene they'll be
+ *     {@link FieldAttribute}s. If they reference the results of another calculation
+ *     they will be {@link ReferenceAttribute}s.
+ * </p>
+ */
 public class UnresolvedAttribute extends Attribute implements Unresolvable {
     private final boolean customMessage;
     private final String unresolvedMsg;
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/UnresolvedFunction.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/UnresolvedFunction.java
index e35ca7e518532..db56202339ad8 100644
--- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/UnresolvedFunction.java
+++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/UnresolvedFunction.java
@@ -7,6 +7,7 @@
 package org.elasticsearch.xpack.esql.expression.function;
 
 import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.xpack.esql.analysis.Analyzer;
 import org.elasticsearch.xpack.esql.core.capabilities.Unresolvable;
 import org.elasticsearch.xpack.esql.core.capabilities.UnresolvedException;
 import org.elasticsearch.xpack.esql.core.expression.Expression;
@@ -24,6 +25,11 @@
 import java.util.Objects;
 import java.util.Set;
 
+/**
+ * An unresolved function call. We build these while walking the syntax
+ * tree and then resolve them into other {@link Function} subclasses during
+ * {@link Analyzer analysis}.
+ */
 public class UnresolvedFunction extends Function implements Unresolvable {
 
     private final String name;