Fixing java doc comments.

Signed-off-by: Mitchell Gale <[email protected]>

core/src/main/java/org/opensearch/sql/executor/execution/StreamingQueryPlan.java

@@ -72,8 +72,11 @@ interface ExecutionStrategy {
   }
 
   /**
-   * execute task with fixed interval. if task run time < interval, trigger next task on next
-   * interval. if task run time >= interval, trigger next task immediately.
+   * <pre>
+   * execute task with fixed interval.
+   * if task run time < interval, trigger next task on next interval.
+   * if task run time >= interval, trigger next task immediately.
+   * </pre>
    */
   @RequiredArgsConstructor
   public static class IntervalTriggerExecution implements ExecutionStrategy {

core/src/main/java/org/opensearch/sql/executor/pagination/CanPaginateVisitor.java

@@ -41,16 +41,21 @@
 import org.opensearch.sql.expression.function.BuiltinFunctionName;
 
 /**
- * Use this unresolved plan visitor to check if a plan can be serialized by PaginatedPlanCache. If
- *
- * <pre>plan.accept(new CanPaginateVisitor(...))</pre>
- *
- * returns <em>true</em>, then PaginatedPlanCache.convertToCursor will succeed. Otherwise, it will
- * fail. The purpose of this visitor is to activate legacy engine fallback mechanism. Currently, V2
- * engine does not support queries with: - aggregation (GROUP BY clause or aggregation functions
- * like min/max) - in memory aggregation (window function) - LIMIT/OFFSET clause(s) - without FROM
- * clause - JOIN - a subquery V2 also requires that the table being queried should be an OpenSearch
- * index. See PaginatedPlanCache.canConvertToCursor for usage.
+ * <pre>
+ * Use this unresolved plan visitor to check if a plan can be serialized by PaginatedPlanCache.
+ * If <pre>plan.accept(new CanPaginateVisitor(...))</pre> returns <em>true</em>,
+ * then PaginatedPlanCache.convertToCursor will succeed. Otherwise, it will fail.
+ * The purpose of this visitor is to activate legacy engine fallback mechanism.
+ * Currently, V2 engine does not support queries with:
+ * - aggregation (GROUP BY clause or aggregation functions like min/max)
+ * - in memory aggregation (window function)
+ * - LIMIT/OFFSET clause(s)
+ * - without FROM clause
+ * - JOIN
+ * - a subquery
+ * V2 also requires that the table being queried should be an OpenSearch index.
+ * See PaginatedPlanCache.canConvertToCursor for usage.
+ * </pre>
  */
 public class CanPaginateVisitor extends AbstractNodeVisitor<Boolean, Object> {
 

core/src/main/java/org/opensearch/sql/expression/ExpressionNodeVisitor.java

@@ -81,11 +81,14 @@ public T visitNamedAggregator(NamedAggregator node, C context) {
     return visitChildren(node, context);
   }
 
-  /**
-   * Call visitFunction() by default rather than visitChildren(). This makes CASE/WHEN able to be
-   * handled: 1) by visitFunction() if not overwritten: ex. FilterQueryBuilder 2) by
-   * visitCase/When() otherwise if any special logic: ex. ExprReferenceOptimizer
-   */
+ /**
+ * Call visitFunction() by default rather than visitChildren().
+ * This makes CASE/WHEN able to be handled:
+ *   *  <ol>
+ *  *   <li>by visitFunction() if not overwritten: ex. FilterQueryBuilder</li>
+ *  *   <li>by visitCase/When() otherwise if any special logic: ex. ExprReferenceOptimizer</li>
+ *  * </ol>
+ */
   public T visitCase(CaseClause node, C context) {
     return visitFunction(node, context);
   }

core/src/main/java/org/opensearch/sql/expression/NamedExpression.java

@@ -15,8 +15,9 @@
 import org.opensearch.sql.expression.env.Environment;
 
 /**
- * Named expression that represents expression with name. Please see more details in associated
- * unresolved expression operator {@link org.opensearch.sql.ast.expression.Alias}.
+ * Named expression that represents expression with name.<br>
+ * Please see more details in associated unresolved expression operator<br>
+ * {@link org.opensearch.sql.ast.expression.Alias}.
  */
 @AllArgsConstructor
 @EqualsAndHashCode

core/src/main/java/org/opensearch/sql/expression/ReferenceExpression.java

@@ -61,21 +61,39 @@ public String toString() {
   }
 
   /**
-   * Resolve the ExprValue from {@link ExprTupleValue} using paths. Considering the following sample
-   * data. { "name": "bob smith" "project.year": 1990, "project": { "year": "2020" } "address": {
-   * "state": "WA", "city": "seattle", "project.year": 1990 } "address.local": { "state": "WA", } }
-   * The paths could be 1. top level, e.g. "name", which will be resolved as "bob smith" 2. multiple
-   * paths, e.g. "name.address.state", which will be resolved as "WA" 3. special case, the "." is
-   * the path separator, but it is possible that the path include ".", for handling this use case,
-   * we define the resolve rule as bellow, e.g. "project.year" is resolved as 1990 instead of 2020.
-   * Note. This logic only applied top level none object field. e.g. "address.local.state" been
-   * resolved to Missing. but "address.project.year" could been resolved as 1990.
+   * <pre>
+   * Resolve the ExprValue from {@link ExprTupleValue} using paths.
+   * Considering the following sample data.
+   * {
+   *   "name": "bob smith"
+   *   "project.year": 1990,
+   *   "project": {
+   *     "year": "2020"
+   *   }
+   *   "address": {
+   *     "state": "WA",
+   *     "city": "seattle",
+   *     "project.year": 1990
+   *   }
+   *   "address.local": {
+   *     "state": "WA",
+   *   }
+   * }
+   * The paths could be
+   * 1. top level, e.g. "name", which will be resolved as "bob smith"
+   * 2. multiple paths, e.g. "name.address.state", which will be resolved as "WA"
+   * 3. special case, the "." is the path separator, but it is possible that the path include
+   * ".", for handling this use case, we define the resolve rule as bellow, e.g. "project.year" is
+   * resolved as 1990 instead of 2020. Note. This logic only applied top level none object field.
+   * e.g. "address.local.state" been resolved to Missing. but "address.project.year" could been
+   * resolved as 1990.
    *
    * <p>Resolve Rule 1. Resolve the full name by combine the paths("x"."y"."z") as whole ("x.y.z").
    * 2. Resolve the path recursively through ExprValue.
    *
    * @param value {@link ExprTupleValue}.
    * @return {@link ExprTupleValue}.
+   * </pre>
    */
   public ExprValue resolve(ExprTupleValue value) {
     return resolve(value, paths);

core/src/main/java/org/opensearch/sql/expression/aggregation/AggregatorFunction.java

@@ -34,9 +34,14 @@
 import org.opensearch.sql.expression.function.FunctionSignature;
 
 /**
- * The definition of aggregator function avg, Accepts two numbers and produces a number. sum,
- * Accepts two numbers and produces a number. max, Accepts two numbers and produces a number. min,
- * Accepts two numbers and produces a number. count, Accepts two numbers and produces a number.
+ * <pre>
+ * The definition of aggregator function
+ * avg, Accepts two numbers and produces a number.
+ * sum, Accepts two numbers and produces a number.
+ * max, Accepts two numbers and produces a number.
+ * min, Accepts two numbers and produces a number.
+ * count, Accepts two numbers and produces a number.
+ * </pre>
  */
 @UtilityClass
 public class AggregatorFunction {

core/src/main/java/org/opensearch/sql/expression/datetime/DateTimeFunction.java

@@ -98,8 +98,9 @@
 import org.opensearch.sql.utils.DateTimeUtils;
 
 /**
- * The definition of date and time functions. 1) have the clear interface for function define. 2)
- * the implementation should rely on ExprValue.
+ * The definition of date and time functions.
+ * 1) have the clear interface for function define.
+ * 2) the implementation should rely on ExprValue.
  */
 @UtilityClass
 @SuppressWarnings("unchecked")
@@ -325,12 +326,17 @@ private FunctionResolver current_date() {
   }
 
   /**
-   * A common signature for `date_add` and `date_sub`. Specify a start date and add/subtract a
-   * temporal amount to/from the date. The return type depends on the date type and the interval
-   * unit. Detailed supported signatures: (DATE/DATETIME/TIMESTAMP/TIME, INTERVAL) -> DATETIME MySQL
-   * has these signatures too (DATE, INTERVAL) -> DATE // when interval has no time part (TIME,
-   * INTERVAL) -> TIME // when interval has no date part (STRING, INTERVAL) -> STRING // when
-   * argument has date or datetime string, // result has date or datetime depending on interval type
+   * <pre>
+   * A common signature for `date_add` and `date_sub`.
+   * Specify a start date and add/subtract a temporal amount to/from the date.
+   * The return type depends on the date type and the interval unit. Detailed supported signatures:
+   * (DATE/DATETIME/TIMESTAMP/TIME, INTERVAL) -> DATETIME
+   * MySQL has these signatures too
+   * (DATE, INTERVAL) -> DATE                                     // when interval has no time part
+   * (TIME, INTERVAL) -> TIME                                     // when interval has no date part
+   * (STRING, INTERVAL) -> STRING         // when argument has date or datetime string,
+   *                                      // result has date or datetime depending on interval type
+   * </pre>
    */
   private Stream<SerializableFunction<?, ?>> get_date_add_date_sub_signatures(
       SerializableTriFunction<FunctionProperties, ExprValue, ExprValue, ExprValue> function) {
@@ -344,8 +350,12 @@ private FunctionResolver current_date() {
   }
 
   /**
-   * A common signature for `adddate` and `subdate`. Adds/subtracts an integer number of days
-   * to/from the first argument. (DATE, LONG) -> DATE (TIME/DATETIME/TIMESTAMP, LONG) -> DATETIME
+   * <pre>
+   * A common signature for `adddate` and `subdate`.
+   * Adds/subtracts an integer number of days to/from the first argument.
+   * (DATE, LONG) -> DATE
+   * (TIME/DATETIME/TIMESTAMP, LONG) -> DATETIME
+   * </pre>
    */
   private Stream<SerializableFunction<?, ?>> get_adddate_subdate_signatures(
       SerializableTriFunction<FunctionProperties, ExprValue, ExprValue, ExprValue> function) {
@@ -367,11 +377,15 @@ private DefaultFunctionResolver adddate() {
   }
 
   /**
-   * Adds expr2 to expr1 and returns the result. (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
-   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME TODO: MySQL has these
-   * signatures too (STRING, STRING/TIME) -> STRING // second arg - string with time only (x,
-   * STRING) -> NULL // second arg - string with timestamp (x, STRING/DATE) -> x // second arg -
-   * string with date only
+   * <pre>
+   * Adds expr2 to expr1 and returns the result.
+   * (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
+   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME
+   * TODO: MySQL has these signatures too
+   * (STRING, STRING/TIME) -> STRING               // second arg - string with time only
+   * (x, STRING) -> NULL                           // second arg - string with timestamp
+   * (x, STRING/DATE) -> x                         // second arg - string with date only
+   * </pre>
    */
   private DefaultFunctionResolver addtime() {
     return define(
@@ -444,8 +458,12 @@ private DefaultFunctionResolver addtime() {
   }
 
   /**
-   * Converts date/time from a specified timezone to another specified timezone. The supported
-   * signatures: (DATETIME, STRING, STRING) -> DATETIME (STRING, STRING, STRING) -> DATETIME
+   * <pre>
+   * Converts date/time from a specified timezone to another specified timezone.
+   * The supported signatures:
+   * (DATETIME, STRING, STRING) -> DATETIME
+   * (STRING, STRING, STRING) -> DATETIME
+   * </pre>
    */
   private DefaultFunctionResolver convert_tz() {
     return define(
@@ -465,8 +483,11 @@ private DefaultFunctionResolver convert_tz() {
   }
 
   /**
-   * Extracts the date part of a date and time value. Also to construct a date type. The supported
-   * signatures: STRING/DATE/DATETIME/TIMESTAMP -> DATE
+   * <pre>
+   * Extracts the date part of a date and time value.
+   * Also to construct a date type. The supported signatures:
+   * STRING/DATE/DATETIME/TIMESTAMP -> DATE
+   * </pre>
    */
   private DefaultFunctionResolver date() {
     return define(
@@ -555,8 +576,12 @@ private DefaultFunctionResolver datediff() {
   }
 
   /**
-   * Specify a datetime with time zone field and a time zone to convert to. Returns a local date
-   * time. (STRING, STRING) -> DATETIME (STRING) -> DATETIME
+   * <pre>
+   * Specify a datetime with time zone field and a time zone to convert to.
+   * Returns a local date time.
+   * (STRING, STRING) -> DATETIME
+   * (STRING) -> DATETIME
+   * </pre>
    */
   private FunctionResolver datetime() {
     return define(
@@ -847,11 +872,15 @@ private DefaultFunctionResolver subdate() {
   }
 
   /**
-   * Subtracts expr2 from expr1 and returns the result. (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
-   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME TODO: MySQL has these
-   * signatures too (STRING, STRING/TIME) -> STRING // second arg - string with time only (x,
-   * STRING) -> NULL // second arg - string with timestamp (x, STRING/DATE) -> x // second arg -
-   * string with date only
+   * <pre>
+   * Subtracts expr2 from expr1 and returns the result.
+   * (TIME, TIME/DATE/DATETIME/TIMESTAMP) -> TIME
+   * (DATE/DATETIME/TIMESTAMP, TIME/DATE/DATETIME/TIMESTAMP) -> DATETIME
+   * TODO: MySQL has these signatures too
+   * (STRING, STRING/TIME) -> STRING               // second arg - string with time only
+   * (x, STRING) -> NULL                           // second arg - string with timestamp
+   * (x, STRING/DATE) -> x                         // second arg - string with date only
+   * </pre>
    */
   private DefaultFunctionResolver subtime() {
     return define(
@@ -954,11 +983,17 @@ private DefaultFunctionResolver time() {
   }
 
   /**
-   * Returns different between two times as a time. (TIME, TIME) -> TIME MySQL has these signatures
-   * too (DATE, DATE) -> TIME // result is > 24 hours (DATETIME, DATETIME) -> TIME // result is > 24
-   * hours (TIMESTAMP, TIMESTAMP) -> TIME // result is > 24 hours (x, x) -> NULL // when args have
-   * different types (STRING, STRING) -> TIME // argument strings contain same types only (STRING,
-   * STRING) -> NULL // argument strings are different types
+   * <pre>
+   * Returns different between two times as a time.
+   * (TIME, TIME) -> TIME
+   * MySQL has these signatures too
+   * (DATE, DATE) -> TIME                      // result is > 24 hours
+   * (DATETIME, DATETIME) -> TIME              // result is > 24 hours
+   * (TIMESTAMP, TIMESTAMP) -> TIME            // result is > 24 hours
+   * (x, x) -> NULL                            // when args have different types
+   * (STRING, STRING) -> TIME                  // argument strings contain same types only
+   * (STRING, STRING) -> NULL                  // argument strings are different types
+   * </pre>
    */
   private DefaultFunctionResolver timediff() {
     return define(
@@ -979,11 +1014,14 @@ private DefaultFunctionResolver time_to_sec() {
   }
 
   /**
-   * Extracts the timestamp of a date and time value. Input strings may contain a timestamp only in
-   * format 'yyyy-MM-dd HH:mm:ss[.SSSSSSSSS]' STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
-   * STRING/DATE/TIME/DATETIME/TIMESTAMP, STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP All types
-   * are converted to TIMESTAMP actually before the function call - it is responsibility of the
-   * automatic cast mechanism defined in `ExprCoreType` and performed by `TypeCastOperator`.
+   * <pre>
+   * Extracts the timestamp of a date and time value.
+   * Input strings may contain a timestamp only in format 'yyyy-MM-dd HH:mm:ss[.SSSSSSSSS]'
+   * STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
+   * STRING/DATE/TIME/DATETIME/TIMESTAMP, STRING/DATE/TIME/DATETIME/TIMESTAMP -> TIMESTAMP
+   * All types are converted to TIMESTAMP actually before the function call - it is responsibility
+   * of the automatic cast mechanism defined in `ExprCoreType` and performed by `TypeCastOperator`.
+   * </pre>
    */
   private DefaultFunctionResolver timestamp() {
     return define(
@@ -1221,9 +1259,15 @@ private DefaultFunctionResolver yearweek() {
   }
 
   /**
-   * Formats date according to format specifier. First argument is date, second is format. Detailed
-   * supported signatures: (STRING, STRING) -> STRING (DATE, STRING) -> STRING (DATETIME, STRING) ->
-   * STRING (TIME, STRING) -> STRING (TIMESTAMP, STRING) -> STRING
+   * <pre>
+   * Formats date according to format specifier. First argument is date, second is format.
+   * Detailed supported signatures:
+   * (STRING, STRING) -> STRING
+   * (DATE, STRING) -> STRING
+   * (DATETIME, STRING) -> STRING
+   * (TIME, STRING) -> STRING
+   * (TIMESTAMP, STRING) -> STRING
+   * </pre>
    */
   private DefaultFunctionResolver date_format() {
     return define(
@@ -1302,9 +1346,15 @@ private ExprValue exprDateApplyInterval(
   }
 
   /**
-   * Formats date according to format specifier. First argument is time, second is format. Detailed
-   * supported signatures: (STRING, STRING) -> STRING (DATE, STRING) -> STRING (DATETIME, STRING) ->
-   * STRING (TIME, STRING) -> STRING (TIMESTAMP, STRING) -> STRING
+   * <pre>
+   * Formats date according to format specifier. First argument is time, second is format.
+   * Detailed supported signatures:
+   * (STRING, STRING) -> STRING
+   * (DATE, STRING) -> STRING
+   * (DATETIME, STRING) -> STRING
+   * (TIME, STRING) -> STRING
+   * (TIMESTAMP, STRING) -> STRING
+   * </pre>
    */
   private DefaultFunctionResolver time_format() {
     return define(
@@ -1683,14 +1733,18 @@ private ExprValue exprLastDayToday(Clock clock) {
   }
 
   /**
+   * <pre>
    * Following MySQL, function receives arguments of type double and rounds them before use.
-   * Furthermore: - zero year interpreted as 2000 - negative year is not accepted - @dayOfYear
-   * should be greater than 1 - if @dayOfYear is greater than 365/366, calculation goes to the next
-   * year(s)
+   * Furthermore:
+   *  - zero year interpreted as 2000
+   *  - negative year is not accepted
+   *  - @dayOfYear should be greater than 1
+   *  - if @dayOfYear is greater than 365/366, calculation goes to the next year(s)
    *
    * @param yearExpr year
    * @param dayOfYearExp day of the @year, starting from 1
    * @return Date - ExprDateValue object with LocalDate
+   * </pre>
    */
   private ExprValue exprMakeDate(ExprValue yearExpr, ExprValue dayOfYearExp) {
     var year = Math.round(yearExpr.doubleValue());