Code style: improve Javadoc

* Javadoc paragraphs (starting with '<p>') must have a blank
  line before;
* Javadoc paragraphs must have exactly one space between the
  '*' or '/**' at the start of the line and the first
  non-whitespace character;
* Ensure that '<p>' is not at the end of a line;
* Remove '</p>'; they are not required because Javadoc is
  HTML, not XHTML;
* Require blank line between description and first @param,
  @return, etc.
* Replace all '**/' with '*/'.

babel/src/main/java/org/apache/calcite/sql/babel/postgresql/SqlBegin.java

@@ -36,6 +36,7 @@
 
 /**
  * Parse tree node representing a {@code BEGIN} clause.
+ *
  * @see <a href="https://www.postgresql.org/docs/current/sql-begin.html">BEGIN specification</a>
  */
 public class SqlBegin extends SqlCall {

babel/src/main/java/org/apache/calcite/sql/babel/postgresql/SqlCommit.java

@@ -34,6 +34,7 @@
 
 /**
  * Parse tree node representing a {@code COMMIT} clause.
+ *
  * @see <a href="https://www.postgresql.org/docs/current/sql-commit.html">COMMIT specification</a>
  */
 public class SqlCommit extends SqlCall {

babel/src/main/java/org/apache/calcite/sql/babel/postgresql/SqlDiscard.java

@@ -35,6 +35,7 @@
 
 /**
  * Parse tree node representing a {@code DISCARD} clause.
+ *
  * @see <a href="https://www.postgresql.org/docs/current/sql-discard.html">DISCARD specification</a>
  */
 public class SqlDiscard extends SqlCall {

babel/src/main/java/org/apache/calcite/sql/babel/postgresql/SqlRollback.java

@@ -34,6 +34,7 @@
 
 /**
  * Parse tree node representing a {@code ROLLBACK} clause.
+ *
  * @see <a href="https://www.postgresql.org/docs/current/sql-rollback.html">ROLLBACK specification</a>
  */
 public class SqlRollback extends SqlCall {

babel/src/main/java/org/apache/calcite/sql/babel/postgresql/SqlShow.java

@@ -35,6 +35,7 @@
 
 /**
  * Parse tree node representing a {@code SHOW} clause.
+ *
  * @see <a href="https://www.postgresql.org/docs/current/sql-show.html">SHOW specification</a>
  */
 public class SqlShow extends SqlCall {

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

@@ -228,7 +228,7 @@ private static boolean isEqualityOnKey(RexNode node, List<String> fieldNames,
           scan.cassandraTable.getClusteringOrder());
     }
 
-    /** Deprecated in favor of {@link CassandraFilterRuleConfig}. **/
+    /** Deprecated in favor of {@link CassandraFilterRuleConfig}. */
     @Deprecated
     public interface Config extends CassandraFilterRuleConfig { }
 
@@ -362,7 +362,7 @@ private static boolean collationsCompatible(RelCollation sortCollation,
       call.transformTo(convert(sort, filter));
     }
 
-    /** Deprecated in favor of CassandraSortRuleConfig. **/
+    /** Deprecated in favor of CassandraSortRuleConfig. */
     @Deprecated
     public interface Config extends CassandraSortRuleConfig { }
 
@@ -417,7 +417,7 @@ public RelNode convert(EnumerableLimit limit) {
       call.transformTo(convert(limit));
     }
 
-    /** Deprecated in favor of CassandraLimitRuleConfig. **/
+    /** Deprecated in favor of CassandraLimitRuleConfig. */
     @Deprecated
     public interface Config extends CassandraLimitRuleConfig { }
 

cassandra/src/main/java/org/apache/calcite/adapter/cassandra/package-info.java

@@ -18,6 +18,6 @@
 /**
  * Cassandra query provider.
  *
- * <p>There is one table for each Cassandra column family.</p>
+ * <p>There is one table for each Cassandra column family.
  */
 package org.apache.calcite.adapter.cassandra;

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

@@ -51,13 +51,13 @@
 import java.util.concurrent.ExecutionException;
 
 /**
- * JUnit5 extension to start and stop embedded cassandra server.
+ * JUnit5 extension to start and stop embedded Cassandra server.
  *
  * <p>Note that tests will be skipped if running on JDK11+ or Eclipse OpenJ9 JVM
  * (not supported by cassandra-unit and Cassandra, respectively) see
- *  <a href="/jsevellec/cassandra-unit/issues/294">cassandra-unit issue #294</a>
- *  and <a href="https://issues.apache.org/jira/browse/CASSANDRA-14883">CASSANDRA-14883</a>,
- *  respectively.
+ * <a href="/jsevellec/cassandra-unit/issues/294">cassandra-unit issue #294</a>
+ * and <a href="https://issues.apache.org/jira/browse/CASSANDRA-14883">CASSANDRA-14883</a>,
+ * respectively.
  */
 class CassandraExtension implements ParameterResolver, ExecutionCondition {
 
@@ -102,6 +102,7 @@ private static CassandraResource getOrCreate(ExtensionContext context) {
 
   /**
    * Whether to run this test.
+   *
    * <p>Enabled by default, unless explicitly disabled
    * from command line ({@code -Dcalcite.test.cassandra=false}) or running on incompatible JDK
    * version or JVM (see below).

core/src/main/java/org/apache/calcite/DataContext.java

@@ -63,7 +63,7 @@ public interface DataContext {
    * Returns a context variable.
    *
    * <p>Supported variables include: "sparkContext", "currentTimestamp",
-   * "localTimestamp".</p>
+   * "localTimestamp".
    *
    * @param name Name of variable
    */

core/src/main/java/org/apache/calcite/adapter/clone/ArrayTable.java

@@ -112,7 +112,7 @@ enum RepresentationType {
     /** Constant. Contains only one value.
      *
      * <p>We can't store 0-bit values in
-     * an array: we'd have no way of knowing how many there were.</p>
+     * an array: we'd have no way of knowing how many there were.
      *
      * @see Constant
      */
@@ -156,7 +156,7 @@ enum RepresentationType {
      * values with many duplicates is a win; a column of mostly distinct
      * {@code short} values is likely a loss. The other win is if there are
      * null values; otherwise the best option would be an
-     * {@link #OBJECT_ARRAY}.</p>
+     * {@link #OBJECT_ARRAY}.
      *
      * @see PrimitiveDictionary
      */
@@ -180,7 +180,7 @@ enum RepresentationType {
      * occur very commonly are held in an 'exceptions' array and are
      * recognized by their high offsets. Other strings are created on demand
      * (this reduces the number of objects that need to be created during
-     * deserialization from cache.</p>
+     * deserialization from cache.
      *
      * @see StringDictionary
      */

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

@@ -35,6 +35,7 @@ public interface AggAddContext extends AggResultContext {
    * Returns {@link org.apache.calcite.rex.RexNode} representation of arguments.
    * This can be useful for manual translation of required arguments with
    * different {@link NullPolicy}.
+   *
    * @return {@link org.apache.calcite.rex.RexNode} representation of arguments
    */
   List<RexNode> rexArguments();
@@ -50,6 +51,7 @@ public interface AggAddContext extends AggResultContext {
    * The resulting value is equivalent to
    * {@code rowTranslator().translateList(rexArguments())}.
    * This is handy if you need just operate on argument.
+   *
    * @return Linq4j form of arguments.
    */
   List<Expression> arguments();

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

@@ -31,6 +31,7 @@
 public interface AggContext {
   /**
    * Returns the aggregation being implemented.
+   *
    * @return aggregation being implemented.
    */
   SqlAggFunction aggregation();
@@ -47,6 +48,7 @@ public interface AggContext {
 
   /**
    * Returns the return type of the aggregate as {@link java.lang.reflect.Type}.
+   *
    * @return return type of the aggregate as {@link java.lang.reflect.Type}
    */
   Type returnType();

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

@@ -733,7 +733,7 @@ public static MethodCallExpression call(@Nullable Expression targetExpression,
     return null;
   }
 
-  /** Transforms a JoinRelType to Linq4j JoinType. **/
+  /** Transforms a JoinRelType to Linq4j JoinType. */
   static JoinType toLinq4jJoinType(JoinRelType joinRelType) {
     switch (joinRelType) {
     case INNER:
@@ -755,7 +755,7 @@ static JoinType toLinq4jJoinType(JoinRelType joinRelType) {
         "Unable to convert " + joinRelType + " to Linq4j JoinType");
   }
 
-  /** Returns a predicate expression based on a join condition. **/
+  /** Returns a predicate expression based on a join condition. */
   static Expression generatePredicate(
       EnumerableRelImplementor implementor,
       RexBuilder rexBuilder,

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

@@ -66,7 +66,7 @@ private EnumerableRules() {
       EnumerableBatchNestedLoopJoinRule.Config.DEFAULT.toRule();
 
   /** Rule that converts a
-   *  {@link org.apache.calcite.rel.logical.LogicalProject} to an
+   * {@link org.apache.calcite.rel.logical.LogicalProject} to an
    * {@link EnumerableProject}. */
   public static final EnumerableProjectRule ENUMERABLE_PROJECT_RULE =
       EnumerableProjectRule.DEFAULT_CONFIG.toRule(EnumerableProjectRule.class);
@@ -166,7 +166,7 @@ private EnumerableRules() {
       EnumerableProjectToCalcRule.Config.DEFAULT.toRule();
 
   /** Rule that converts a
-   *  {@link org.apache.calcite.rel.logical.LogicalTableScan} to
+   * {@link org.apache.calcite.rel.logical.LogicalTableScan} to
    * {@link EnumerableConvention enumerable calling convention}. */
   public static final EnumerableTableScanRule ENUMERABLE_TABLE_SCAN_RULE =
       EnumerableTableScanRule.DEFAULT_CONFIG
@@ -180,7 +180,7 @@ private EnumerableRules() {
           .toRule(EnumerableTableFunctionScanRule.class);
 
   /** Rule that converts a {@link LogicalMatch} to an
-   *  {@link EnumerableMatch}. */
+   * {@link EnumerableMatch}. */
   public static final EnumerableMatchRule ENUMERABLE_MATCH_RULE =
       EnumerableMatchRule.DEFAULT_CONFIG.toRule(EnumerableMatchRule.class);
 

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

@@ -119,8 +119,9 @@ public static EnumerableTableScan create(RelOptCluster cluster,
 
   /** Returns whether EnumerableTableScan can generate code to handle a
    * particular variant of the Table SPI.
+   *
    * @deprecated remove before Calcite 2.0
-   **/
+   */
   @Deprecated
   public static boolean canHandle(Table table) {
     if (table instanceof TransientTable) {
@@ -135,8 +136,7 @@ public static boolean canHandle(Table table) {
   }
 
   /** Returns whether EnumerableTableScan can generate code to handle a
-   * particular variant of the Table SPI.
-   **/
+   * particular variant of the Table SPI. */
   public static boolean canHandle(RelOptTable relOptTable) {
     Table table = relOptTable.unwrap(Table.class);
     if (table != null && !canHandle(table)) {

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

@@ -28,6 +28,7 @@ private MatchUtils() {
 
   /**
    * Returns the row with the highest index whose corresponding symbol matches, null otherwise.
+   *
    * @param symbol Target Symbol
    * @param rows List of passed rows
    * @param symbols Corresponding symbols to rows

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

@@ -27,6 +27,7 @@ public interface NestedBlockBuilder {
   /**
    * Starts nested code block. The resulting block can optimize expressions
    * and reuse already calculated values from the parent blocks.
+   *
    * @return new code block that can optimize expressions and reuse already
    * calculated values from the parent blocks.
    */
@@ -35,6 +36,7 @@ public interface NestedBlockBuilder {
   /**
    * Uses given block as the new code context.
    * The current block will be restored after {@link #exitBlock()} call.
+   *
    * @param block new code block
    * @see #exitBlock()
    */
@@ -47,6 +49,7 @@ public interface NestedBlockBuilder {
 
   /**
    * Leaves the current code block.
+   *
    * @see #nestBlock()
    */
   void exitBlock();

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

@@ -31,6 +31,7 @@ public class NestedBlockBuilderImpl implements NestedBlockBuilder {
 
   /**
    * Constructs nested block builders starting of a given code block.
+   *
    * @param block root code block
    */
   @SuppressWarnings("method.invocation.invalid")
@@ -41,6 +42,7 @@ public NestedBlockBuilderImpl(BlockBuilder block) {
   /**
    * Starts nested code block. The resulting block can optimize expressions
    * and reuse already calculated values from the parent blocks.
+   *
    * @return new code block that can optimize expressions and reuse already
    * calculated values from the parent blocks.
    */
@@ -53,6 +55,7 @@ public NestedBlockBuilderImpl(BlockBuilder block) {
   /**
    * Uses given block as the new code context.
    * The current block will be restored after {@link #exitBlock()} call.
+   *
    * @param block new code block
    * @see #exitBlock()
    */
@@ -69,6 +72,7 @@ public NestedBlockBuilderImpl(BlockBuilder block) {
 
   /**
    * Leaves the current code block.
+   *
    * @see #nestBlock()
    */
   @Override public final void exitBlock() {

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

@@ -22,7 +22,7 @@
  * <p>STRICT and ANY are similar. STRICT says f(a0, a1) will NEVER return
  * null if a0 and a1 are not null. This means that we can check whether f
  * returns null just by checking its arguments. Use STRICT in preference to
- * ANY whenever possible.</p>
+ * ANY whenever possible.
  */
 public enum NullPolicy {
   /** Returns null if and only if all of the arguments are null;

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

@@ -36,7 +36,7 @@
  * type of the row (returned by {@link #getJavaRowType()}), and methods to
  * generate expressions to access fields, generate records, and so forth.
  * Together, the records encapsulate how the logical type maps onto the physical
- * type.</p>
+ * type.
  */
 public interface PhysType {
   /** Returns the Java type (often a Class) that represents a row. For
@@ -48,7 +48,7 @@ public interface PhysType {
    * ordinal.
    *
    * <p>For instance, when the java row type is {@code Object[]}, the java
-   * field type is {@code Object} even if the field is not nullable.</p> */
+   * field type is {@code Object} even if the field is not nullable. */
   Type getJavaFieldType(int field);
 
   /** Returns the type factory. */

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

@@ -940,6 +940,7 @@ public static Expression translateCondition(RexProgram program,
   }
 
   /** Returns whether an expression is nullable.
+   *
    * @param e Expression
    * @return Whether expression is nullable
    */

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

@@ -32,6 +32,7 @@
 
 /**
  * The base implementation of strict aggregate function.
+ *
  * @see org.apache.calcite.adapter.enumerable.RexImpTable.CountImplementor
  * @see org.apache.calcite.adapter.enumerable.RexImpTable.SumImplementor
  */

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

@@ -23,6 +23,7 @@
 
 /**
  * The base implementation of strict window aggregate function.
+ *
  * @see org.apache.calcite.adapter.enumerable.RexImpTable.FirstLastValueImplementor
  * @see org.apache.calcite.adapter.enumerable.RexImpTable.RankImplementor
  * @see org.apache.calcite.adapter.enumerable.RexImpTable.RowNumberImplementor

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

@@ -25,6 +25,7 @@
  * <p>{@link WinAggAddContext} is used when implementing windowed aggregate.
  * Typically, the aggregation implementation will use {@link #arguments()}
  * or {@link #rexArguments()} to update aggregate value.
+ *
  * @see AggAddContext
  */
 public interface WinAggAddContext extends AggAddContext, WinAggResultContext {
@@ -34,6 +35,7 @@ public interface WinAggAddContext extends AggAddContext, WinAggResultContext {
    * This is NOT current row as in "rows between current row".
    * If you need to know the relative index of the current row in the partition,
    * use {@link WinAggFrameContext#index()}.
+   *
    * @return current position inside for-loop of window aggregate.
    * @see WinAggFrameContext#index()
    * @see WinAggFrameContext#startIndex()