From cc7e11f45e5ff34f940a7648d723fe6b3765bfb6 Mon Sep 17 00:00:00 2001
From: Costin Leau <costin@users.noreply.github.com>
Date: Thu, 28 Dec 2017 11:50:44 +0200
Subject: [PATCH] SQL: document usage of parameterized type on AbstractBuilder
 parser (elastic/x-pack-elasticsearch#3425)

Original commit: elastic/x-pack-elasticsearch@c807f9dd40ea5c89689bb1be139a32269399d45c
---
 .../xpack/sql/parser/AbstractBuilder.java        | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/sql/server/src/main/java/org/elasticsearch/xpack/sql/parser/AbstractBuilder.java b/sql/server/src/main/java/org/elasticsearch/xpack/sql/parser/AbstractBuilder.java
index 2675bef9dfa..392c57c1648 100644
--- a/sql/server/src/main/java/org/elasticsearch/xpack/sql/parser/AbstractBuilder.java
+++ b/sql/server/src/main/java/org/elasticsearch/xpack/sql/parser/AbstractBuilder.java
@@ -16,6 +16,16 @@ import org.elasticsearch.xpack.sql.util.Check;
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Base parsing visitor class offering utility methods.
+ *
+ * Implementation note: ANTLR 4 generates sources with a parameterized signature that isn't really useful for SQL.
+ * That is mainly because it forces <i>each</i> visitor method to return a node inside the generated AST which
+ * might be or not the case.
+ * Since the parser generates two types of trees ({@code LogicalPlan} and {@code Expression}) plus string handling,
+ * the generic signature does not fit and does give any advantage hence why it is <i>erased</i>, each subsequent
+ * child class acting as a layer for parsing and building its respective type
+ */
 abstract class AbstractBuilder extends SqlBaseBaseVisitor<Object> {
 
     @Override
@@ -33,7 +43,7 @@ abstract class AbstractBuilder extends SqlBaseBaseVisitor<Object> {
         }
 
         throw new ParsingException(source(ctx), "Invalid query '%s'[%s] given; expected %s but found %s",
-                        ctx.getText(), ctx.getClass().getSimpleName(), 
+                        ctx.getText(), ctx.getClass().getSimpleName(),
                         type.getSimpleName(), (result != null ? result.getClass().getSimpleName() : "null"));
     }
 
@@ -44,7 +54,7 @@ abstract class AbstractBuilder extends SqlBaseBaseVisitor<Object> {
     protected List<LogicalPlan> plans(List<? extends ParserRuleContext> ctxs) {
         return visitList(ctxs, LogicalPlan.class);
     }
-    
+
     protected <T> List<T> visitList(List<? extends ParserRuleContext> contexts, Class<T> clazz) {
         List<T> results = new ArrayList<>(contexts.size());
         for (ParserRuleContext context : contexts) {
@@ -83,7 +93,7 @@ abstract class AbstractBuilder extends SqlBaseBaseVisitor<Object> {
     }
 
     /**
-     * Extracts the actual unescaped string (literal) value of a token. 
+     * Extracts the actual unescaped string (literal) value of a token.
      */
     static String string(Token token) {
         return token == null ? null : unquoteString(token.getText());