Code style: Lint

If a block of text in javadoc is preceded by a blank line, and is not
inside '<blockquote>' or '<ul>', the block must start with '<p>'.

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

@@ -30,8 +30,7 @@
 /**
  * Tests for the {@code org.apache.calcite.adapter.cassandra} package.
  *
- *
- * Instantiates a CQL session without keyspace, but passes it to
+ * <p>Instantiates a CQL session without keyspace, but passes it to
  * {@code org.apache.calcite.adapter.cassandra.CassandraTable}.
  * All generated CQL queries should still succeed and explicitly
  * reference the keyspace.

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

@@ -146,10 +146,12 @@ private CassandraResource() {
     }
 
     /**
-     * Best effort to gracefully shutdown <strong>embedded</strong> cassandra cluster.
+     * Best effort to gracefully shutdown <strong>embedded</strong> cassandra
+     * cluster.
      *
-     * Since it uses many static variables as well as {@link System#exit(int)} during close,
-     * clean shutdown (as part of unit test) is not straightforward.
+     * <p>Since it uses many static variables as well as {@link System#exit(int)}
+     * during close, clean shutdown (as part of unit test) is not
+     * straightforward.
      */
     @Override public void close() throws IOException {
       session.close();

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

@@ -794,7 +794,8 @@ static Expression generatePredicate(
    * Generates a window selector which appends attribute of the window based on
    * the parameters.
    *
-   * Note that it only works for batch scenario. E.g. all data is known and there is no late data.
+   * <p>Note that it only works for batch scenario. E.g. all data is known and
+   * there is no late data.
    */
   static Expression tumblingWindowSelector(
       PhysType inputPhysType,

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

@@ -149,42 +149,66 @@ private static List<RelCollation> getCollations(RelTraitSet traits) {
 
   /**
    * Pass collations through can have three cases:
-   * 1. If sort keys are equal to either left join keys, or right join keys,
+   *
+   * <p>1. If sort keys are equal to either left join keys, or right join keys,
    * collations can be pushed to both join sides with correct mappings.
    * For example, for the query
-   *    select * from foo join bar on foo.a=bar.b order by foo.a desc
-   * after traits pass through it will be equivalent to
+   *
+   * <blockquote><pre>{@code
+   *    select * from foo join bar
+   *        on foo.a=bar.b
+   *    order by foo.a desc
+   * }</pre></blockquote>
+   *
+   * <p>after traits pass through it will be equivalent to
+   *
+   * <blockquote><pre>{@code
    *    select * from
    *        (select * from foo order by foo.a desc)
    *        join
    *        (select * from bar order by bar.b desc)
+   * }</pre></blockquote>
    *
-   * 2. If sort keys are sub-set of either left join keys, or right join keys,
-   * collations have to be extended to cover all joins keys before passing through,
-   * because merge join requires all join keys are sorted.
+   * <p>2. If sort keys are sub-set of either left join keys, or right join
+   * keys, collations have to be extended to cover all joins keys before
+   * passing through, because merge join requires all join keys are sorted.
    * For example, for the query
+   *
+   * <blockquote><pre>{@code
    *    select * from foo join bar
    *        on foo.a=bar.b and foo.c=bar.d
-   *        order by foo.a desc
-   * after traits pass through it will be equivalent to
+   *    order by foo.a desc
+   * }</pre></blockquote>
+   *
+   * <p>after traits pass through it will be equivalent to
+   *
+   * <blockquote><pre>{@code
    *    select * from
    *        (select * from foo order by foo.a desc, foo.c)
    *        join
    *        (select * from bar order by bar.b desc, bar.d)
+   * }</pre></blockquote>
    *
-   * 3. If sort keys are super-set of either left join keys, or right join keys,
-   * but not both, collations can be completely passed to the join key whose join
-   * keys match the prefix of collations. Meanwhile, partial mapped collations can
-   * be passed to another join side to make sure join keys are sorted.
-   * For example, for the query
+   * <p>3. If sort keys are super-set of either left join keys, or right join
+   * keys, but not both, collations can be completely passed to the join key
+   * whose join keys match the prefix of collations. Meanwhile, partial mapped
+   * collations can be passed to another join side to make sure join keys are
+   * sorted. For example, for the query
+
+   * <blockquote><pre>{@code
    *    select * from foo join bar
    *        on foo.a=bar.b and foo.c=bar.d
    *        order by foo.a desc, foo.c desc, foo.e
-   * after traits pass through it will be equivalent to
+   * }</pre></blockquote>
+   *
+   * <p>after traits pass through it will be equivalent to
+   *
+   * <blockquote><pre>{@code
    *    select * from
    *        (select * from foo order by foo.a desc, foo.c desc, foo.e)
    *        join
    *        (select * from bar order by bar.b desc, bar.d desc)
+   * }</pre></blockquote>
    */
   @Override public @Nullable Pair<RelTraitSet, List<RelTraitSet>> passThroughTraits(
       final RelTraitSet required) {
@@ -354,9 +378,10 @@ private static RelCollation extendCollation(RelCollation collation, List<Integer
    *    on foo.a = bar.a and foo.c=bar.c
    *    order by bar.a, bar.c, bar.b;
    *
-   * The collation [bar.a, bar.c, bar.b] can be pushed down to bar. However, only
-   * [a, c] can be pushed down to foo. This function will help create [a, c] for foo by removing
-   * b from the required collation, because b is not defined on join keys.
+   * <p>The collation [bar.a, bar.c, bar.b] can be pushed down to bar. However,
+   * only [a, c] can be pushed down to foo. This function will help create [a,
+   * c] for foo by removing b from the required collation, because b is not
+   * defined on join keys.
    *
    * @param collation collation defined on the JOIN
    * @param joinKeys  the join keys

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

@@ -251,16 +251,18 @@ public final class CalciteSystemProperty<T> {
   /**
    * Whether to use Docker containers (https://www.testcontainers.org/) in tests.
    *
-   * If the property is set to <code>true</code>, affected tests will attempt to start Docker
-   * containers; when Docker is not available tests fallback to other execution modes and if it's
-   * not possible they are skipped entirely.
+   * <p>If the property is set to <code>true</code>, affected tests will attempt
+   * to start Docker containers; when Docker is not available tests fallback to
+   * other execution modes and if it's not possible they are skipped entirely.
    *
-   * If the property is set to <code>false</code>, Docker containers are not used at all and
-   * affected tests either fallback to other execution modes or skipped entirely.
+   * <p>If the property is set to <code>false</code>, Docker containers are not
+   * used at all and affected tests either fallback to other execution modes or
+   * skipped entirely.
    *
-   * Users can override the default behavior to force non-Dockerized execution even when Docker
-   * is installed on the machine; this can be useful for replicating an issue that appears only in
-   * non-docker test mode or for running tests both with and without containers in CI.
+   * <p>Users can override the default behavior to force non-Dockerized
+   * execution even when Docker is installed on the machine; this can be useful
+   * for replicating an issue that appears only in non-docker test mode or for
+   * running tests both with and without containers in CI.
    */
   public static final CalciteSystemProperty<Boolean> TEST_WITH_DOCKER_CONTAINER =
       booleanProperty("calcite.test.docker", true);

core/src/main/java/org/apache/calcite/plan/visualizer/RuleMatchVisualizer.java

@@ -60,17 +60,18 @@
 /**
  * This is a tool to visualize the rule match process of a RelOptPlanner.
  *
- * <pre>{@code
+ * <blockquote><pre>{@code
  * // create the visualizer
- * RuleMatchVisualizer viz = new RuleMatchVisualizer("/path/to/output/dir", "file-name-suffix");
+ * RuleMatchVisualizer viz =
+ *     new RuleMatchVisualizer("/path/to/output/dir", "file-name-suffix");
  * viz.attachTo(planner)
  *
  * planner.findBestExpr();
  *
  * // extra step for HepPlanner: write the output to files
  * // a VolcanoPlanner will call it automatically
  * viz.writeToFile();
- * }</pre>
+ * }</pre></blockquote>
  */
 public class RuleMatchVisualizer implements RelOptListener {
 

core/src/main/java/org/apache/calcite/plan/volcano/package-info.java

@@ -210,29 +210,29 @@
  *
  * <ul>
  *
- *     <li>Registering exp 5 triggers <code>CombineProjectsRule</code>(exp 1,
- *         exp 5), which creates
+ * <li>Registering exp 5 triggers <code>CombineProjectsRule</code>(exp 1,
+ *     exp 5), which creates
  *
- *         <blockquote>
+ * <blockquote>
  *     <pre>Project (deptno)                              [exp 7, subset A]
  *   Filter (gender='F')                         [exp 6, subset E]
  *     Project (deptno, gender, empno, salary)   [exp 4, subset D]
  *       TableScan (emp)                         [exp 0, subset X]</pre>
- *         </blockquote>
- *     </li>
+ * </blockquote>
+ * </li>
  *
- *     <li>Registering exp 6 triggers
- *         <code>PushFilterThroughProjectRule</code>(exp 6, exp 4), which
- *         creates
+ * <li>Registering exp 6 triggers
+ *     <code>PushFilterThroughProjectRule</code>(exp 6, exp 4), which
+ *     creates
  *
- *         <blockquote>
+ * <blockquote>
  *     <pre>Project (deptno)                              [exp 1, subset A]
  *   Project (deptno, gender, empno)             [exp 5, subset B]
  *     Project (deptno, gender, empno, salary)   [exp 8, subset E]
  *       Filter (gender='F')                     [exp 9, subset F]
  *         TableScan (emp)                       [exp 0, subset X]</pre>
- *         </blockquote>
- *     </li>
+ * </blockquote>
+ * </li>
  * </ul>
  *
  * <p>Each rule application adds additional members to existing subsets. The
@@ -250,16 +250,17 @@
  * <p>Todo: show how rules can cause subsets to merge.
  *
  * <p>Conclusion:
+ *
  * <ol>
- *     <li>A rule can be triggered by any of its operands.</li>
- *     <li>If a subset is a child of more than one parent, it can trigger rule
- *         matches for any of its parents.
- *     </li>
+ * <li>A rule can be triggered by any of its operands.</li>
+ * <li>If a subset is a child of more than one parent, it can trigger rule
+ *     matches for any of its parents.
+ * </li>
  *
- *     <li>Registering one relexp can trigger several rules (and even the same
- *         rule several times).</li>
+ * <li>Registering one relexp can trigger several rules (and even the same
+ *     rule several times).</li>
  *
- *     <li>Firing rules can cause subsets to merge.</li>
+ * <li>Firing rules can cause subsets to merge.</li>
  * </ol>
  * <h2>References</h2>
  *

core/src/main/java/org/apache/calcite/rel/PhysicalNode.java

@@ -35,38 +35,38 @@
  * <p>How to use?
  *
  * <ol>
- *   <li>Enable top-down optimization by setting
- *   {@link org.apache.calcite.plan.volcano.VolcanoPlanner#setTopDownOpt(boolean)}.
- *   </li>
+ * <li>Enable top-down optimization by setting
+ * {@link org.apache.calcite.plan.volcano.VolcanoPlanner#setTopDownOpt(boolean)}.
+ * </li>
  *
- *   <li>Let your convention's rel interface extends {@link PhysicalNode},
- *   see {@link org.apache.calcite.adapter.enumerable.EnumerableRel} as
- *   an example.</li>
+ * <li>Let your convention's rel interface extends {@link PhysicalNode},
+ * see {@link org.apache.calcite.adapter.enumerable.EnumerableRel} as
+ * an example.</li>
  *
- *   <li>Each physical operator overrides any one of the two methods:
- *   {@link PhysicalNode#passThrough(RelTraitSet)} or
- *   {@link PhysicalNode#passThroughTraits(RelTraitSet)} depending on
- *   your needs.</li>
+ * <li>Each physical operator overrides any one of the two methods:
+ * {@link PhysicalNode#passThrough(RelTraitSet)} or
+ * {@link PhysicalNode#passThroughTraits(RelTraitSet)} depending on
+ * your needs.</li>
  *
- *   <li>Choose derive mode for each physical operator by overriding
- *   {@link PhysicalNode#getDeriveMode()}.</li>
+ * <li>Choose derive mode for each physical operator by overriding
+ * {@link PhysicalNode#getDeriveMode()}.</li>
  *
- *   <li>If the derive mode is {@link DeriveMode#OMAKASE}, override
- *   method {@link PhysicalNode#derive(List)} in the physical operator,
- *   otherwise, override {@link PhysicalNode#derive(RelTraitSet, int)}
- *   or {@link PhysicalNode#deriveTraits(RelTraitSet, int)}.</li>
+ * <li>If the derive mode is {@link DeriveMode#OMAKASE}, override
+ * method {@link PhysicalNode#derive(List)} in the physical operator,
+ * otherwise, override {@link PhysicalNode#derive(RelTraitSet, int)}
+ * or {@link PhysicalNode#deriveTraits(RelTraitSet, int)}.</li>
  *
- *   <li>Mark your enforcer operator by overriding {@link RelNode#isEnforcer()},
- *   see {@link Sort#isEnforcer()} as an example. This is important,
- *   because it can help {@code VolcanoPlanner} avoid unnecessary
- *   trait propagation and derivation, therefore improve optimization
- *   efficiency.</li>
+ * <li>Mark your enforcer operator by overriding {@link RelNode#isEnforcer()},
+ * see {@link Sort#isEnforcer()} as an example. This is important,
+ * because it can help {@code VolcanoPlanner} avoid unnecessary
+ * trait propagation and derivation, therefore improve optimization
+ * efficiency.</li>
  *
- *   <li>Implement {@link Convention#enforce(RelNode, RelTraitSet)}
- *   in your convention, which generates appropriate physical enforcer.
- *   See {@link org.apache.calcite.adapter.enumerable.EnumerableConvention}
- *   as example. Simply return {@code null} if you don't want physical
- *   trait enforcement.</li>
+ * <li>Implement {@link Convention#enforce(RelNode, RelTraitSet)}
+ * in your convention, which generates appropriate physical enforcer.
+ * See {@link org.apache.calcite.adapter.enumerable.EnumerableConvention}
+ * as example. Simply return {@code null} if you don't want physical
+ * trait enforcement.</li>
  * </ol>
  */
 public interface PhysicalNode extends RelNode {

core/src/main/java/org/apache/calcite/rel/RelCollationImpl.java

@@ -121,8 +121,9 @@ public static RelCollation of(List<RelFieldCollation> fieldCollations) {
   /**
    * Applies mapping to a given collation.
    *
-   * If mapping destroys the collation prefix, this method returns an empty collation.
-   * Examples of applying mappings to collation [0, 1]:
+   * <p>If mapping destroys the collation prefix, this method returns an empty
+   * collation.  Examples of applying mappings to collation [0, 1]:
+   *
    * <ul>
    *   <li>mapping(0, 1) =&gt; [0, 1]</li>
    *   <li>mapping(1, 0) =&gt; [1, 0]</li>

core/src/main/java/org/apache/calcite/rel/RelNode.java

@@ -232,8 +232,8 @@ public interface RelNode extends RelOptNode, Cloneable {
    * The string returned is the same as
    * {@link RelOptUtil#toString(org.apache.calcite.rel.RelNode)}.
    *
-   * This method is intended mainly for use while debugging in an IDE,
-   * as a convenient short-hand for RelOptUtil.toString.
+   * <p>This method is intended mainly for use while debugging in an IDE,
+   * as a convenient shorthand for {@link RelOptUtil#toString}.
    * We recommend that classes implementing this interface
    * do not override this method.
    *

core/src/main/java/org/apache/calcite/rel/metadata/ProxyingMetadataHandlerProvider.java

@@ -36,7 +36,7 @@
 /**
  * A MetadataHandlerProvider built on a RelMetadataProvider.
  *
- * Uses proxies to call the underlying metadata provider.
+ * <p>Uses proxies to call the underlying metadata provider.
  */
 public class ProxyingMetadataHandlerProvider implements MetadataHandlerProvider {
 

core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataProvider.java

@@ -77,18 +77,21 @@ <M extends Metadata> Multimap<Method, MetadataHandler<M>> handlers(
 
   /**
    * Retrieves a list of {@link MetadataHandler} for implements a particular
-   * {@link MetadataHandler}.class.  The resolution order is specificity of the relNode class,
-   * with preference given to handlers that occur earlier in the list.
+   * {@link MetadataHandler}.class.  The resolution order is specificity of the
+   * relNode class, with preference given to handlers that occur earlier in the
+   * list.
    *
-   * For instance, given a return list of {A, B, C} where A implements RelNode and Scan,
-   * B implements Scan, and C implements LogicalScan and Filter.
+   * <p>For instance, given a return list of {A, B, C} where A implements
+   * RelNode and Scan, B implements Scan, and C implements LogicalScan and
+   * Filter.
    *
-   * Scan dispatches to a.method(Scan)
-   * LogicalFilter dispatches to c.method(Filter).
-   * LogicalScan dispatches to c.method(LogicalScan).
+   * <p>Scan dispatches to a.method(Scan);
+   * LogicalFilter dispatches to c.method(Filter);
+   * LogicalScan dispatches to c.method(LogicalScan);
    * Aggregate dispatches to a.method(RelNode).
    *
-   * The behavior is undefined if the class hierarchy for dispatching is not a tree.
+   * <p>The behavior is undefined if the class hierarchy for dispatching is not
+   * a tree.
    */
   List<MetadataHandler<?>> handlers(Class<? extends MetadataHandler<?>> handlerClass);
 }