SQL: Add some Javadocs (elastic/x-pack-elasticsearch#3816)

* SQL: Add some Javadocs

* Reflow javadoc for fewer columns

Original commit: elastic/x-pack-elasticsearch@d23239b2e5

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Alias.java

@@ -15,6 +15,14 @@ import static java.util.Collections.singletonList;
 import java.util.Collections;
 import java.util.List;
 
+/**
+ * An {@code Alias} is a {@code NamedExpression} that gets renamed to something else through the Alias.
+ *
+ * For example, in the statement {@code 5 + 2 AS x}, {@code x} is an alias which is points to {@code ADD(5, 2)}.
+ *
+ * And in {@code SELECT col AS x} "col" is a named expression that gets renamed to "x" through an alias.
+ *
+ */
 public class Alias extends NamedExpression {
 
     private final Expression child;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Attribute.java

@@ -18,6 +18,22 @@ import java.util.List;
  * {@link Expression}s that can be converted into Elasticsearch
  * sorts, aggregations, or queries. They can also be extracted
  * from the result of a search.
+ *
+ * In the statement {@code SELECT ABS(foo), A, B+C FROM ...} the three named
+ * expressions (ABS(foo), A, B+C) get converted to attributes and the user can
+ * only see Attributes.
+ *
+ * In the statement {@code SELECT foo FROM TABLE WHERE foo > 10 + 1} 10+1 is an
+ * expression. It's not named - meaning there's no alias for it (defined by the
+ * user) and as such there's no attribute - no column to be returned to the user.
+ * It's an expression used for filtering so it doesn't appear in the result set
+ * (derived table). "foo" on the other hand is an expression, a named expression
+ * (it has a name) and also an attribute - it's a column in the result set.
+ *
+ * Another example {@code SELECT foo FROM ... WHERE bar > 10 +1} "foo" gets
+ * converted into an Attribute, bar does not. That's because bar is used for
+ * filtering alone but it's not part of the projection meaning the user doesn't
+ * need it in the derived table.
  */
 public abstract class Attribute extends NamedExpression {
 

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/Expression.java

@@ -18,6 +18,15 @@ import java.util.Locale;
 
 import static java.lang.String.format;
 
+/**
+ * In a SQL statement, an Expression is whatever a user specifies inside an
+ * action, so for instance:
+ *
+ * {@code SELECT a, b, MAX(c, d) FROM i}
+ *
+ * a, b, ABS(c), and i are all Expressions, with ABS(c) being a Function
+ * (which is a type of expression) with a single child, c.
+ */
 public abstract class Expression extends Node<Expression> implements Resolvable {
 
     public static class TypeResolution {

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/Function.java

@@ -15,6 +15,10 @@ import org.elasticsearch.xpack.sql.util.StringUtils;
 import java.util.List;
 import java.util.StringJoiner;
 
+/**
+ * Any SQL expression with parentheses, like {@code MAX()}, or {@code ABS()}. A
+ * function is always a {@code NamedExpression}.
+ */
 public abstract class Function extends NamedExpression {
 
     private final String functionName, name;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/aggregate/AggregateFunction.java

@@ -16,6 +16,9 @@ import java.util.Objects;
 import static java.util.Collections.emptyList;
 import static java.util.Collections.singletonList;
 
+/**
+ * A type of {@code Function} that takes multiple values and extracts a single value out of them. For example, {@code AVG()}.
+ */
 public abstract class AggregateFunction extends Function {
 
     private final Expression field;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/ScalarFunction.java

@@ -23,6 +23,12 @@ import static java.util.Collections.emptyList;
 import static org.elasticsearch.xpack.sql.expression.function.scalar.script.ParamsBuilder.paramsBuilder;
 import static org.elasticsearch.xpack.sql.expression.function.scalar.script.ScriptTemplate.formatTemplate;
 
+/**
+ * A {@code ScalarFunction} is a {@code Function} that takes values from some
+ * operation and converts each to another value. An example would be
+ * {@code ABS()}, which takes one value at a time, applies a function to the
+ * value (abs) and returns a new value.
+ */
 public abstract class ScalarFunction extends Function {
 
     private ScalarFunctionAttribute lazyAttribute = null;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/definition/ProcessorDefinition.java

@@ -14,6 +14,14 @@ import org.elasticsearch.xpack.sql.tree.Node;
 
 import java.util.List;
 
+/**
+ * Contains the tree for processing a function, so for example, the {@code ProcessorDefinition} of:
+ *
+ * ABS(MAX(foo)) + CAST(bar)
+ *
+ * Is an {@code Add} Function with left {@code ABS} over an aggregate (MAX), and
+ * right being a {@code CAST} function.
+ */
 public abstract class ProcessorDefinition extends Node<ProcessorDefinition> implements FieldExtraction {
 
     private final Expression expression;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/expression/function/scalar/processor/runtime/Processor.java

@@ -7,6 +7,12 @@ package org.elasticsearch.xpack.sql.expression.function.scalar.processor.runtime
 
 import org.elasticsearch.common.io.stream.NamedWriteable;
 
+/**
+ * For a scalar function, a {@code Processor} is how we convert the value to convert one value to another value. For instance, ABS(foo).
+ * Aggregate functions are handled by ES but scalars are not.
+ *
+ * This is an opaque class, the computed/compiled result gets saved on the client during scrolling.
+ */
 public interface Processor extends NamedWriteable {
 
     Object process(Object input);

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/QueryPlan.java

@@ -19,6 +19,9 @@ import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.tree.Node;
 import org.elasticsearch.xpack.sql.type.DataType;
 
+/**
+ * There are two main types of plans, {@code LogicalPlan} and {@code PhysicalPlan}
+ */
 public abstract class QueryPlan<PlanType extends QueryPlan<PlanType>> extends Node<PlanType> {
 
     private AttributeSet lazyOutputSet;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Filter.java

@@ -11,6 +11,11 @@ import org.elasticsearch.xpack.sql.expression.Expression;
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.tree.NodeInfo;
 
+/**
+ * A {@code Filter} is a type of Plan that performs filtering of results. In
+ * {@code SELECT x FROM y WHERE z ..} the "WHERE" clause is a Filter. A
+ * {@code Filter} has a "condition" Expression that does the filtering.
+ */
 public class Filter extends UnaryPlan {
 
     private final Expression condition;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/LogicalPlan.java

@@ -12,6 +12,10 @@ import org.elasticsearch.xpack.sql.tree.Location;
 
 import java.util.List;
 
+/**
+ * A LogicalPlan is <b>what</b> (not the "how") a user told us they want to do.
+ * For example, a logical plan in English would be: "I want to get from DEN to SFO".
+ */
 public abstract class LogicalPlan extends QueryPlan<LogicalPlan> implements Resolvable {
 
     /**

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/Project.java

@@ -16,6 +16,9 @@ import org.elasticsearch.xpack.sql.expression.function.Functions;
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.tree.NodeInfo;
 
+/**
+ * A {@code Project} is a {@code Plan} with one child. In {@code SELECT x FROM y}, the "SELECT" statement is a Project.
+ */
 public class Project extends UnaryPlan {
 
     private final List<? extends NamedExpression> projections;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/logical/UnaryPlan.java

@@ -12,6 +12,10 @@ import java.util.Objects;
 import org.elasticsearch.xpack.sql.expression.Attribute;
 import org.elasticsearch.xpack.sql.tree.Location;
 
+/**
+ * A {@code UnaryPlan} is a {@code LogicalPlan} with exactly one child, for example, {@code WHERE x} in a
+ * SQL statement is an {@code UnaryPlan}.
+ */
 public abstract class UnaryPlan extends LogicalPlan {
 
     private final LogicalPlan child;

plugin/sql/src/main/java/org/elasticsearch/xpack/sql/plan/physical/PhysicalPlan.java

@@ -13,6 +13,12 @@ import org.elasticsearch.xpack.sql.session.Rows;
 import org.elasticsearch.xpack.sql.tree.Location;
 import org.elasticsearch.xpack.sql.type.Schema;
 
+/**
+ * A PhysicalPlan is "how" a LogicalPlan (the "what") actually gets translated into one or more queries.
+ *
+ * LogicalPlan = I want to get from DEN to SFO
+ * PhysicalPlan = take Delta, DEN to SJC, then SJC to SFO
+ */
 public abstract class PhysicalPlan extends QueryPlan<PhysicalPlan> implements Executable {
 
     private Schema lazySchema;