[CALCITE-4137] Checkstyle should ensure that every class has a Javado…

…c comment

Checkstyle should ensure that every class, interface, enum, package has
a Javadoc comment. And that javadoc types (e.g @param and @return) are
not empty.

Following [CALCITE-2905], remove @PackageMarker from Redis adapter.

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/CassandraEnumerator.java

@@ -57,7 +57,7 @@ class CassandraEnumerator implements Enumerator<Object> {
     this.fieldTypes = protoRowType.apply(typeFactory).getFieldList();
   }
 
-  /** Produce the next row from the results
+  /** Produces the next row from the results.
    *
    * @return A new row from the results
    */

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/CassandraRules.java

@@ -205,7 +205,6 @@ private String compareFieldWithLiteral(RexNode left, RexNode right, List<String>
       }
     }
 
-    /** @see org.apache.calcite.rel.convert.ConverterRule */
     @Override public void onMatch(RelOptRuleCall call) {
       LogicalFilter filter = call.rel(0);
       CassandraTableScan scan = call.rel(1);
@@ -370,7 +369,6 @@ private RelFieldCollation.Direction reverseDirection(RelFieldCollation.Direction
       }
     }
 
-    /** @see org.apache.calcite.rel.convert.ConverterRule */
     @Override public void onMatch(RelOptRuleCall call) {
       final Sort sort = call.rel(0);
       CassandraFilter filter = call.rel(2);
@@ -426,7 +424,6 @@ public RelNode convert(EnumerableLimit limit) {
         convert(limit.getInput(), CassandraRel.CONVENTION), limit.offset, limit.fetch);
     }
 
-    /** @see org.apache.calcite.rel.convert.ConverterRule */
     @Override public void onMatch(RelOptRuleCall call) {
       final EnumerableLimit limit = call.rel(0);
       final RelNode converted = convert(limit);

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/CassandraSchema.java

@@ -65,7 +65,7 @@
 import java.util.stream.IntStream;
 
 /**
- * Schema mapped onto a Cassandra column family
+ * Schema mapped onto a Cassandra column family.
  */
 public class CassandraSchema extends AbstractSchema {
   final Session session;
@@ -243,7 +243,7 @@ RelProtoDataType getRelDataType(String columnFamily, boolean view) {
   }
 
   /**
-   * Get all primary key columns from the underlying CQL table
+   * Returns all primary key columns from the underlying CQL table.
    *
    * @return A list of field names that are part of the partition and clustering keys
    */
@@ -305,8 +305,7 @@ public List<RelFieldCollation> getClusteringOrder(String columnFamily, boolean v
     return keyCollations;
   }
 
-  /** Add all materialized views defined in the schema to this column family
-   */
+  /** Adds all materialized views defined in the schema to this column family. */
   private void addMaterializedViews() {
     // Close the hook use to get us here
     hook.close();

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/CassandraSchemaFactory.java

@@ -23,7 +23,7 @@
 import java.util.Map;
 
 /**
- * Factory that creates a {@link CassandraSchema}
+ * Factory that creates a {@link CassandraSchema}.
  */
 @SuppressWarnings("UnusedDeclaration")
 public class CassandraSchemaFactory implements SchemaFactory {

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/CassandraTable.java

@@ -48,7 +48,7 @@
 import java.util.Map;
 
 /**
- * Table based on a Cassandra column family
+ * Table based on a Cassandra column family.
  */
 public class CassandraTable extends AbstractQueryableTable
     implements TranslatableTable {

cassandra/src/test/java/org/apache/calcite/test/CassandraExtension.java

@@ -93,9 +93,8 @@ static ImmutableMap<String, String> getDataset(String resourcePath) {
             .file().getAbsolutePath());
   }
 
-  /**
-   * Register cassandra resource in root context so it can be shared with other tests
-   */
+  /** Registers a Cassandra resource in root context so it can be shared with
+   * other tests. */
   private static CassandraResource getOrCreate(ExtensionContext context) {
     // same cassandra instance should be shared across all extension instances
     return context.getRoot()
@@ -128,7 +127,9 @@ private static CassandraResource getOrCreate(ExtensionContext context) {
     return ConditionEvaluationResult.disabled("Cassandra tests disabled");
   }
 
-  private static class CassandraResource implements ExtensionContext.Store.CloseableResource {
+  /** Cassandra resource. */
+  private static class CassandraResource
+      implements ExtensionContext.Store.CloseableResource {
     private final Session session;
     private final Cluster cluster;
 

core/src/main/java/org/apache/calcite/adapter/enumerable/EnumUtils.java

@@ -593,7 +593,7 @@ static List<Expression> convertAssignableTypes(Class<?>[] targetTypes,
   }
 
   /**
-   * Handle decimal type specifically with explicit type conversion
+   * Handles decimal type specifically with explicit type conversion.
    */
   private static Expression convertAssignableType(
       Expression argument, Type targetType) {
@@ -671,7 +671,8 @@ private static List<? extends Expression> matchMethodParameterTypes(boolean varA
   }
 
   /**
-   * Match an argument expression to method parameter type with best effort
+   * Matches an argument expression to method parameter type with best effort.
+   *
    * @param argument Argument Expression
    * @param parameter Parameter type
    * @return Converted argument expression that matches the parameter type.
@@ -832,6 +833,7 @@ public static Enumerable<Object[]> sessionize(Enumerator<Object[]> inputEnumerat
     };
   }
 
+  /** Enumerator that converts rows into sessions separated by gaps. */
   private static class SessionizationEnumerator implements Enumerator<Object[]> {
     private final Enumerator<Object[]> inputEnumerator;
     private final int indexOfWatermarkedColumn;
@@ -972,6 +974,7 @@ public static Enumerable<Object[]> hopping(Enumerator<Object[]> inputEnumerator,
     };
   }
 
+  /** Enumerator that computes HOP. */
   private static class HopEnumerator implements Enumerator<Object[]> {
     private final Enumerator<Object[]> inputEnumerator;
     private final int indexOfWatermarkedColumn;

core/src/main/java/org/apache/calcite/adapter/enumerable/JavaRowFormat.java

@@ -189,7 +189,7 @@ public Expression field(Expression expression, int field, Type fromType,
   },
 
   /**
-   * See {@link org.apache.calcite.interpreter.Row}
+   * See {@link org.apache.calcite.interpreter.Row}.
    */
   ROW {
     @Override Type javaRowClass(JavaTypeFactory typeFactory, RelDataType type) {

core/src/main/java/org/apache/calcite/adapter/enumerable/NestedBlockBuilder.java

@@ -41,8 +41,7 @@ public interface NestedBlockBuilder {
   void nestBlock(BlockBuilder block);
 
   /**
-   * Returns the current code block
-   * @return current code block
+   * Returns the current code block.
    */
   BlockBuilder currentBlock();
 

core/src/main/java/org/apache/calcite/adapter/enumerable/NestedBlockBuilderImpl.java

@@ -60,8 +60,7 @@ public final void nestBlock(BlockBuilder block) {
   }
 
   /**
-   * Returns the current code block
-   * @return current code block
+   * Returns the current code block.
    */
   public final BlockBuilder currentBlock() {
     return blocks.get(blocks.size() - 1);

core/src/main/java/org/apache/calcite/adapter/enumerable/ReflectiveCallNotNullImplementor.java

@@ -36,8 +36,9 @@ public class ReflectiveCallNotNullImplementor implements NotNullImplementor {
   protected final Method method;
 
   /**
-   * Constructor of {@link ReflectiveCallNotNullImplementor}
-   * @param method method that is used to implement the call
+   * Constructor of {@link ReflectiveCallNotNullImplementor}.
+   *
+   * @param method Method that is used to implement the call
    */
   public ReflectiveCallNotNullImplementor(Method method) {
     this.method = method;

core/src/main/java/org/apache/calcite/adapter/enumerable/RexToLixTranslator.java

@@ -1097,7 +1097,7 @@ private static Expression implementCallOperand2(final RexNode operand,
 
   /**
    * For {@code PREV} operator, the offset of {@code inputGetter}
-   * should be set first
+   * should be set first.
    */
   private Result implementPrev(RexCall call) {
     final RexNode node = call.getOperands().get(0);

core/src/main/java/org/apache/calcite/adapter/enumerable/impl/AggResetContextImpl.java

@@ -26,7 +26,7 @@
 
 /**
  * Implementation of
- * {@link org.apache.calcite.adapter.enumerable.AggResetContext}
+ * {@link org.apache.calcite.adapter.enumerable.AggResetContext}.
  */
 public abstract class AggResetContextImpl extends NestedBlockBuilderImpl
     implements AggResetContext {

core/src/main/java/org/apache/calcite/adapter/enumerable/impl/AggResultContextImpl.java

@@ -27,7 +27,7 @@
 
 /**
  * Implementation of
- * {@link org.apache.calcite.adapter.enumerable.AggResultContext}
+ * {@link org.apache.calcite.adapter.enumerable.AggResultContext}.
  */
 public class AggResultContextImpl extends AggResetContextImpl
     implements AggResultContext {

core/src/main/java/org/apache/calcite/adapter/java/ReflectiveSchema.java

@@ -196,7 +196,7 @@ private <T> Table fieldRelation(final Field field) {
   }
 
   /** Deduces the element type of a collection;
-   * same logic as {@link #toEnumerable} */
+   * same logic as {@link #toEnumerable}. */
   private static Type getElementType(Class clazz) {
     if (clazz.isArray()) {
       return clazz.getComponentType();

core/src/main/java/org/apache/calcite/adapter/jdbc/JdbcImplementor.java

@@ -33,6 +33,7 @@ public JdbcImplementor(SqlDialect dialect, JavaTypeFactory typeFactory) {
     Util.discard(typeFactory);
   }
 
+  // CHECKSTYLE: IGNORE 1
   /** @see #dispatch */
   public Result visit(JdbcTableScan scan) {
     return result(scan.jdbcTable.tableName(),

core/src/main/java/org/apache/calcite/adapter/jdbc/JdbcRules.java

@@ -1088,10 +1088,10 @@ public JdbcImplementor.Result implement(JdbcImplementor implementor) {
     }
   }
 
-  /**
-   * Visitor for checking whether part of projection is a user defined function or not
-   */
-  private static class CheckingUserDefinedFunctionVisitor extends RexVisitorImpl<Void> {
+  /** Visitor that checks whether part of a projection is a user-defined
+   * function (UDF). */
+  private static class CheckingUserDefinedFunctionVisitor
+      extends RexVisitorImpl<Void> {
 
     private boolean containsUsedDefinedFunction = false;
 

core/src/main/java/org/apache/calcite/adapter/jdbc/JdbcSchema.java

@@ -561,7 +561,7 @@ public Schema create(
     }
   }
 
-  /** Do not use */
+  /** Do not use. */
   @Experimental
   public interface Foo
       extends BiFunction<String, String, Iterable<MetaImpl.MetaTable>> {

core/src/main/java/org/apache/calcite/config/CalciteConnectionConfig.java

@@ -29,59 +29,70 @@
  * classes for system and statement properties. */
 public interface CalciteConnectionConfig extends ConnectionConfig {
   /** Default configuration. */
-  CalciteConnectionConfigImpl DEFAULT = new CalciteConnectionConfigImpl(new Properties());
-  /** @see CalciteConnectionProperty#APPROXIMATE_DISTINCT_COUNT */
+  CalciteConnectionConfigImpl DEFAULT =
+      new CalciteConnectionConfigImpl(new Properties());
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#APPROXIMATE_DISTINCT_COUNT}. */
   boolean approximateDistinctCount();
-  /** @see CalciteConnectionProperty#APPROXIMATE_TOP_N */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#APPROXIMATE_TOP_N}. */
   boolean approximateTopN();
-  /** @see CalciteConnectionProperty#APPROXIMATE_DECIMAL */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#APPROXIMATE_DECIMAL}. */
   boolean approximateDecimal();
-  /** @see CalciteConnectionProperty#NULL_EQUAL_TO_EMPTY */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#NULL_EQUAL_TO_EMPTY}. */
   boolean nullEqualToEmpty();
-  /** @see CalciteConnectionProperty#AUTO_TEMP */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#AUTO_TEMP}. */
   boolean autoTemp();
-  /** @see CalciteConnectionProperty#MATERIALIZATIONS_ENABLED */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#MATERIALIZATIONS_ENABLED}. */
   boolean materializationsEnabled();
-  /** @see CalciteConnectionProperty#CREATE_MATERIALIZATIONS */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#CREATE_MATERIALIZATIONS}. */
   boolean createMaterializations();
-  /** @see CalciteConnectionProperty#DEFAULT_NULL_COLLATION */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#DEFAULT_NULL_COLLATION}. */
   NullCollation defaultNullCollation();
-  /** @see CalciteConnectionProperty#FUN */
+  /** Returns the value of {@link CalciteConnectionProperty#FUN}. */
   <T> T fun(Class<T> operatorTableClass, T defaultOperatorTable);
-  /** @see CalciteConnectionProperty#MODEL */
+  /** Returns the value of {@link CalciteConnectionProperty#MODEL}. */
   String model();
-  /** @see CalciteConnectionProperty#LEX */
+  /** Returns the value of {@link CalciteConnectionProperty#LEX}. */
   Lex lex();
-  /** @see CalciteConnectionProperty#QUOTING */
+  /** Returns the value of {@link CalciteConnectionProperty#QUOTING}. */
   Quoting quoting();
-  /** @see CalciteConnectionProperty#UNQUOTED_CASING */
+  /** Returns the value of {@link CalciteConnectionProperty#UNQUOTED_CASING}. */
   Casing unquotedCasing();
-  /** @see CalciteConnectionProperty#QUOTED_CASING */
+  /** Returns the value of {@link CalciteConnectionProperty#QUOTED_CASING}. */
   Casing quotedCasing();
-  /** @see CalciteConnectionProperty#CASE_SENSITIVE */
+  /** Returns the value of {@link CalciteConnectionProperty#CASE_SENSITIVE}. */
   boolean caseSensitive();
-  /** @see CalciteConnectionProperty#PARSER_FACTORY */
+  /** Returns the value of {@link CalciteConnectionProperty#PARSER_FACTORY}. */
   <T> T parserFactory(Class<T> parserFactoryClass, T defaultParserFactory);
-  /** @see CalciteConnectionProperty#SCHEMA_FACTORY */
+  /** Returns the value of {@link CalciteConnectionProperty#SCHEMA_FACTORY}. */
   <T> T schemaFactory(Class<T> schemaFactoryClass, T defaultSchemaFactory);
-  /** @see CalciteConnectionProperty#SCHEMA_TYPE */
+  /** Returns the value of {@link CalciteConnectionProperty#SCHEMA_TYPE}. */
   JsonSchema.Type schemaType();
-  /** @see CalciteConnectionProperty#SPARK */
+  /** Returns the value of {@link CalciteConnectionProperty#SPARK}. */
   boolean spark();
-  /** @see CalciteConnectionProperty#FORCE_DECORRELATE */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#FORCE_DECORRELATE}. */
   boolean forceDecorrelate();
-  /** @see CalciteConnectionProperty#TYPE_SYSTEM */
+  /** Returns the value of {@link CalciteConnectionProperty#TYPE_SYSTEM}. */
   <T> T typeSystem(Class<T> typeSystemClass, T defaultTypeSystem);
-  /** @see CalciteConnectionProperty#CONFORMANCE */
+  /** Returns the value of {@link CalciteConnectionProperty#CONFORMANCE}. */
   SqlConformance conformance();
-  /** @see CalciteConnectionProperty#TIME_ZONE */
+  /** Returns the value of {@link CalciteConnectionProperty#TIME_ZONE}. */
   @Override String timeZone();
-  /** @see CalciteConnectionProperty#LOCALE */
+  /** Returns the value of {@link CalciteConnectionProperty#LOCALE}. */
   String locale();
-  /** @see CalciteConnectionProperty#TYPE_COERCION */
+  /** Returns the value of {@link CalciteConnectionProperty#TYPE_COERCION}. */
   boolean typeCoercion();
-  /** @see CalciteConnectionProperty#LENIENT_OPERATOR_LOOKUP */
+  /** Returns the value of
+   * {@link CalciteConnectionProperty#LENIENT_OPERATOR_LOOKUP}. */
   boolean lenientOperatorLookup();
-  /** @see CalciteConnectionProperty#TOPDOWN_OPT */
+  /** Returns the value of {@link CalciteConnectionProperty#TOPDOWN_OPT}. */
   boolean topDownOpt();
 }

core/src/main/java/org/apache/calcite/config/CalciteSystemProperty.java

@@ -357,8 +357,9 @@ private static CalciteSystemProperty<Integer> intProperty(String key, int defaul
   }
 
   /**
-   * Returns the value of the system property with the specified name as int, or
-   * the <code>defaultValue</code> if any of the conditions below hold:
+   * Returns the value of the system property with the specified name as {@code
+   * int}. If any of the conditions below hold, returns the
+   * <code>defaultValue</code>:
    *
    * <ol>
    * <li>the property is not defined;

core/src/main/java/org/apache/calcite/interpreter/Bindables.java

@@ -109,6 +109,7 @@ private Bindables() {}
   public static final RelOptRule BINDABLE_SET_OP_RULE =
       BindableSetOpRule.DEFAULT_CONFIG.toRule(BindableSetOpRule.class);
 
+  // CHECKSTYLE: IGNORE 1
   /** @deprecated Use {@link #BINDABLE_SET_OP_RULE}. */
   public static final RelOptRule BINDABLE_SETOP_RULE =
       BINDABLE_SET_OP_RULE;

core/src/main/java/org/apache/calcite/interpreter/Row.java

@@ -113,15 +113,16 @@ private RowBuilder(int size) {
     }
 
     /**
-     * Set the value of a particular column.
+     * Sets the value of a particular column.
+     *
      * @param index Zero-indexed position of value.
      * @param value Desired column value.
      */
     public void set(int index, Object value) {
       values[index] = value;
     }
 
-    /** Return a Row object **/
+    /** Returns a Row. */
     public Row build() {
       return new Row(values);
     }

core/src/main/java/org/apache/calcite/model/ModelHandler.java

@@ -100,6 +100,7 @@ public ModelHandler(CalciteConnection connection, String uri)
     visit(root);
   }
 
+  // CHECKSTYLE: IGNORE 1
   /** @deprecated Use {@link #addFunctions}. */
   @Deprecated
   public static void create(SchemaPlus schema, String functionName,