You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by jh...@apache.org on 2023/06/10 19:18:32 UTC

[calcite] 01/02: Code style: Lint

This is an automated email from the ASF dual-hosted git repository.

jhyde pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/calcite.git

commit cf1454dddae7264d381018f10eaef01328e73703
Author: Julian Hyde <jh...@apache.org>
AuthorDate: Sat Jun 10 11:04:38 2023 -0700

    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>'.
---
 .../test/CassandraAdapterWithoutKeyspaceTest.java  |  3 +-
 .../apache/calcite/test/CassandraExtension.java    |  8 +--
 .../calcite/adapter/enumerable/EnumUtils.java      |  3 +-
 .../adapter/enumerable/EnumerableMergeJoin.java    | 59 +++++++++++++++-------
 .../calcite/config/CalciteSystemProperty.java      | 18 ++++---
 .../plan/visualizer/RuleMatchVisualizer.java       |  7 +--
 .../apache/calcite/plan/volcano/package-info.java  | 37 +++++++-------
 .../java/org/apache/calcite/rel/PhysicalNode.java  | 52 +++++++++----------
 .../org/apache/calcite/rel/RelCollationImpl.java   |  5 +-
 .../main/java/org/apache/calcite/rel/RelNode.java  |  4 +-
 .../metadata/ProxyingMetadataHandlerProvider.java  |  2 +-
 .../calcite/rel/metadata/RelMetadataProvider.java  | 19 ++++---
 .../rel/metadata/janino/CacheGeneratorUtil.java    | 38 ++++++++------
 .../calcite/rel/rel2sql/RelToSqlConverter.java     |  4 +-
 .../apache/calcite/rel/rel2sql/SqlImplementor.java |  2 +-
 .../rel/rules/JoinDeriveIsNotNullFilterRule.java   | 10 ++--
 .../apache/calcite/rel/rules/PruneEmptyRules.java  | 13 +++--
 .../java/org/apache/calcite/rex/RexChecker.java    |  2 +-
 .../java/org/apache/calcite/rex/package-info.java  |  4 +-
 .../java/org/apache/calcite/sql/package-info.java  | 25 ++++-----
 .../calcite/sql/type/SqlTypeCoercionRule.java      |  4 +-
 .../org/apache/calcite/sql/validate/ListScope.java | 10 ++--
 .../calcite/sql/validate/SqlValidatorImpl.java     |  6 +--
 .../sql/validate/implicit/TypeCoercionImpl.java    |  8 +--
 .../calcite/sql2rel/CorrelateProjectExtractor.java | 19 ++++---
 .../apache/calcite/sql2rel/SqlToRelConverter.java  | 20 ++++----
 .../java/org/apache/calcite/tools/RelBuilder.java  |  2 +-
 .../main/java/org/apache/calcite/util/Util.java    | 16 +++---
 .../java/org/apache/calcite/test/LintTest.java     | 28 +++++++++-
 .../org/apache/calcite/test/RelOptRulesTest.java   | 24 ++++-----
 .../calcite/test/concurrent/package-info.java      |  9 ++--
 .../elasticsearch/EmbeddedElasticsearchPolicy.java |  5 +-
 .../apache/calcite/linq4j/EnumerableDefaults.java  | 10 ++--
 .../calcite/linq4j/function/NonDeterministic.java  |  4 +-
 .../calcite/adapter/redis/RedisCaseBase.java       |  6 +--
 .../calcite/benchmarks/MetadataBenchmark.java      |  3 +-
 36 files changed, 284 insertions(+), 205 deletions(-)

diff --git a/cassandra/src/test/java/org/apache/calcite/test/CassandraAdapterWithoutKeyspaceTest.java b/cassandra/src/test/java/org/apache/calcite/test/CassandraAdapterWithoutKeyspaceTest.java
index 8822e9dbe6..79f1400b6d 100644
--- a/cassandra/src/test/java/org/apache/calcite/test/CassandraAdapterWithoutKeyspaceTest.java
+++ b/cassandra/src/test/java/org/apache/calcite/test/CassandraAdapterWithoutKeyspaceTest.java
@@ -30,8 +30,7 @@ import org.junit.jupiter.api.parallel.ExecutionMode;
 /**
  * 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.
diff --git a/cassandra/src/test/java/org/apache/calcite/test/CassandraExtension.java b/cassandra/src/test/java/org/apache/calcite/test/CassandraExtension.java
index 73f19b49cc..7a55e472da 100644
--- a/cassandra/src/test/java/org/apache/calcite/test/CassandraExtension.java
+++ b/cassandra/src/test/java/org/apache/calcite/test/CassandraExtension.java
@@ -146,10 +146,12 @@ class CassandraExtension implements ParameterResolver, ExecutionCondition {
     }
 
     /**
-     * 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();
diff --git a/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumUtils.java b/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumUtils.java
index 70e99deeb8..c4f97ae9d3 100644
--- a/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumUtils.java
+++ b/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumUtils.java
@@ -794,7 +794,8 @@ public class EnumUtils {
    * 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,
diff --git a/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumerableMergeJoin.java b/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumerableMergeJoin.java
index caa6509921..d3f45d8d31 100644
--- a/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumerableMergeJoin.java
+++ b/core/src/main/java/org/apache/calcite/adapter/enumerable/EnumerableMergeJoin.java
@@ -149,42 +149,66 @@ public class EnumerableMergeJoin extends Join implements EnumerableRel {
 
   /**
    * 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 @@ public class EnumerableMergeJoin extends Join implements EnumerableRel {
    *    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
diff --git a/core/src/main/java/org/apache/calcite/config/CalciteSystemProperty.java b/core/src/main/java/org/apache/calcite/config/CalciteSystemProperty.java
index 964d0cc081..4570cccf93 100644
--- a/core/src/main/java/org/apache/calcite/config/CalciteSystemProperty.java
+++ b/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);
diff --git a/core/src/main/java/org/apache/calcite/plan/visualizer/RuleMatchVisualizer.java b/core/src/main/java/org/apache/calcite/plan/visualizer/RuleMatchVisualizer.java
index d9e795996d..b1bb04f320 100644
--- a/core/src/main/java/org/apache/calcite/plan/visualizer/RuleMatchVisualizer.java
+++ b/core/src/main/java/org/apache/calcite/plan/visualizer/RuleMatchVisualizer.java
@@ -60,9 +60,10 @@ import static org.apache.calcite.util.Util.transform;
 /**
  * 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();
@@ -70,7 +71,7 @@ import static org.apache.calcite.util.Util.transform;
  * // 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 {
 
diff --git a/core/src/main/java/org/apache/calcite/plan/volcano/package-info.java b/core/src/main/java/org/apache/calcite/plan/volcano/package-info.java
index 24232dc9c9..8605f1def8 100644
--- a/core/src/main/java/org/apache/calcite/plan/volcano/package-info.java
+++ b/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>
  *
diff --git a/core/src/main/java/org/apache/calcite/rel/PhysicalNode.java b/core/src/main/java/org/apache/calcite/rel/PhysicalNode.java
index e90cffb04f..50da278f27 100644
--- a/core/src/main/java/org/apache/calcite/rel/PhysicalNode.java
+++ b/core/src/main/java/org/apache/calcite/rel/PhysicalNode.java
@@ -35,38 +35,38 @@ import java.util.List;
  * <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 {
diff --git a/core/src/main/java/org/apache/calcite/rel/RelCollationImpl.java b/core/src/main/java/org/apache/calcite/rel/RelCollationImpl.java
index 44a78ca646..06433cd57c 100644
--- a/core/src/main/java/org/apache/calcite/rel/RelCollationImpl.java
+++ b/core/src/main/java/org/apache/calcite/rel/RelCollationImpl.java
@@ -121,8 +121,9 @@ public class RelCollationImpl implements RelCollation {
   /**
    * 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>
diff --git a/core/src/main/java/org/apache/calcite/rel/RelNode.java b/core/src/main/java/org/apache/calcite/rel/RelNode.java
index bee62a8a31..5eeece9822 100644
--- a/core/src/main/java/org/apache/calcite/rel/RelNode.java
+++ b/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.
    *
diff --git a/core/src/main/java/org/apache/calcite/rel/metadata/ProxyingMetadataHandlerProvider.java b/core/src/main/java/org/apache/calcite/rel/metadata/ProxyingMetadataHandlerProvider.java
index ecba433ac4..92490cdd6d 100644
--- a/core/src/main/java/org/apache/calcite/rel/metadata/ProxyingMetadataHandlerProvider.java
+++ b/core/src/main/java/org/apache/calcite/rel/metadata/ProxyingMetadataHandlerProvider.java
@@ -36,7 +36,7 @@ import static java.util.Objects.requireNonNull;
 /**
  * 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 {
 
diff --git a/core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataProvider.java b/core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataProvider.java
index f9a4e5d1f8..2fd2cbee29 100644
--- a/core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataProvider.java
+++ b/core/src/main/java/org/apache/calcite/rel/metadata/RelMetadataProvider.java
@@ -77,18 +77,21 @@ public interface RelMetadataProvider {
 
   /**
    * 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);
 }
diff --git a/core/src/main/java/org/apache/calcite/rel/metadata/janino/CacheGeneratorUtil.java b/core/src/main/java/org/apache/calcite/rel/metadata/janino/CacheGeneratorUtil.java
index 262a7c7e23..939ad2ce15 100644
--- a/core/src/main/java/org/apache/calcite/rel/metadata/janino/CacheGeneratorUtil.java
+++ b/core/src/main/java/org/apache/calcite/rel/metadata/janino/CacheGeneratorUtil.java
@@ -222,13 +222,15 @@ class CacheGeneratorUtil {
         return buff;
       }
     },
+
     /**
      * Generates an immutable key that is reused across all calls.
      *
-     * Example:
-     * <code>
+     * <p>Example:
+     *
+     * <blockquote><pre><code>
      *     private final Object method_key_0 =
-     *       new org.apache.calcite.rel.metadata.janino.DescriptiveCacheKey("...");
+     *         new org.apache.calcite.rel.metadata.janino.DescriptiveCacheKey("...");
      *
      *   ...
      *
@@ -238,7 +240,7 @@ class CacheGeneratorUtil {
      *     final Object key;
      *     key = method_key_0;
      *     final Object v = mq.map.get(r, key);
-     * </code>
+     * </code></pre></blockquote>
      */
     NO_ARG {
       @Override void cacheProperties(StringBuilder buff, Method method, int methodIndex) {
@@ -257,14 +259,16 @@ class CacheGeneratorUtil {
     /**
      * Generates immutable cache keys for metadata calls with single enum argument.
      *
-     * Example:
-     * <code>
+     * <p>Example:
+     *
+     * <blockquote><pre><code>
      *   private final Object method_key_0Null =
      *       new org.apache.calcite.rel.metadata.janino.DescriptiveCacheKey(
-     *         "Boolean isVisibleInExplain(null)");
+     *           "Boolean isVisibleInExplain(null)");
      *   private final Object[] method_key_0 =
      *       org.apache.calcite.rel.metadata.janino.CacheUtil.generateEnum(
-     *         "Boolean isVisibleInExplain", org.apache.calcite.sql.SqlExplainLevel.values());
+     *           "Boolean isVisibleInExplain",
+     *           org.apache.calcite.sql.SqlExplainLevel.values());
      *
      *   ...
      *
@@ -278,7 +282,7 @@ class CacheGeneratorUtil {
      *     } else {
      *       key = method_key_0[a2.ordinal()];
      *     }
-     * </code>
+     * </code></pre></blockquote>
      */
     ENUM_ARG {
       @Override void cacheKeyBlock(StringBuilder buff, Method method, int methodIndex) {
@@ -315,13 +319,14 @@ class CacheGeneratorUtil {
             .append(".values());\n");
       }
     },
+
     /**
      * Generates 2 immutable keys for functions that only take a single boolean
      * arg.
      *
      * <p>Example:
      *
-     * <blockquote><pre>{@code
+     * <blockquote><pre><code>
      *   private final Object method_key_0True =
      *       new org.apache.calcite.rel.metadata.janino.DescriptiveCacheKey("...");
      *   private final Object method_key_0False =
@@ -336,7 +341,7 @@ class CacheGeneratorUtil {
      *     final Object v = mq.map.get(r, key);
      *     ...
      *   }
-     * }</pre></blockquote>
+     * </code></pre></blockquote>
      */
     BOOLEAN_ARG {
       @Override void cacheKeyBlock(StringBuilder buff, Method method, int methodIndex) {
@@ -360,11 +365,14 @@ class CacheGeneratorUtil {
         newDescriptiveCacheKey(buff, method, "false");
       }
     },
+
     /**
-     * Uses a flyweight for fixed range, otherwise instantiates a new list with the arguement in it.
+     * Uses a flyweight for fixed range, otherwise instantiates a new list with
+     * the argument in it.
+     *
+     * <p>Example:
      *
-     * Example:
-     * <code>
+     * <blockquote><pre><code>
      *   private final Object method_key_0 =
      *         new org.apache.calcite.rel.metadata.janino.DescriptiveCacheKey("...");
      *   private final Object[] method_key_0FlyWeight =
@@ -383,7 +391,7 @@ class CacheGeneratorUtil {
      *     } else {
      *       key = org.apache.calcite.runtime.FlatLists.of(method_key_0, a2);
      *     }
-     * </code>
+     * </code></pre></blockquote>
      */
     INT_ARG {
       private final int min = -256;
diff --git a/core/src/main/java/org/apache/calcite/rel/rel2sql/RelToSqlConverter.java b/core/src/main/java/org/apache/calcite/rel/rel2sql/RelToSqlConverter.java
index d702ff9b7a..3dd420ea27 100644
--- a/core/src/main/java/org/apache/calcite/rel/rel2sql/RelToSqlConverter.java
+++ b/core/src/main/java/org/apache/calcite/rel/rel2sql/RelToSqlConverter.java
@@ -311,7 +311,7 @@ public class RelToSqlConverter extends SqlImplementor
    *
    * <p>For example, the following queries are equivalent:
    *
-   * <pre>{@code
+   * <blockquote><pre>{@code
    * // Comma join
    * SELECT *
    * FROM Emp, Dept
@@ -323,7 +323,7 @@ public class RelToSqlConverter extends SqlImplementor
    * // Inner join
    * SELECT *
    * FROM Emp INNER JOIN Dept ON TRUE
-   * }</pre>
+   * }</pre></blockquote>
    *
    * <p>Examples:
    * <ul>
diff --git a/core/src/main/java/org/apache/calcite/rel/rel2sql/SqlImplementor.java b/core/src/main/java/org/apache/calcite/rel/rel2sql/SqlImplementor.java
index e90e5dacbc..6517440c5b 100644
--- a/core/src/main/java/org/apache/calcite/rel/rel2sql/SqlImplementor.java
+++ b/core/src/main/java/org/apache/calcite/rel/rel2sql/SqlImplementor.java
@@ -505,7 +505,7 @@ public abstract class SqlImplementor {
    *
    * <pre>{@code INSERT INTO t1 SELECT x, y + 1 FROM t2}</pre>
    *
-   * rather than with it:
+   * <p>rather than with it:
    *
    * <pre>{@code INSERT INTO t1 SELECT x, y + 1 AS EXPR$0 FROM t2}</pre>
    *
diff --git a/core/src/main/java/org/apache/calcite/rel/rules/JoinDeriveIsNotNullFilterRule.java b/core/src/main/java/org/apache/calcite/rel/rules/JoinDeriveIsNotNullFilterRule.java
index 24074afddb..aec3cb34fb 100644
--- a/core/src/main/java/org/apache/calcite/rel/rules/JoinDeriveIsNotNullFilterRule.java
+++ b/core/src/main/java/org/apache/calcite/rel/rules/JoinDeriveIsNotNullFilterRule.java
@@ -41,11 +41,13 @@ import java.util.stream.Collectors;
  * {@link org.apache.calcite.rel.core.Join} and creates
  * {@link org.apache.calcite.rel.core.Filter}s with those predicates as new inputs of the join.
  *
- * Since the Null value can never match in the inner join and it can lead to skewness due to
- * too many Null values, a not-null filter can be created and pushed down into the input of join.
+ * <p>Since the Null value can never match in the inner join, and it can lead to
+ * skewness due to too many Null values, a not-null filter can be created and
+ * pushed down into the input of join.
  *
- * Similar to {@link CoreRules#FILTER_INTO_JOIN}, it would try to create filters and push them into
- * the inputs of the join to filter data as much as possible before join.
+ * <p>Similar to {@link CoreRules#FILTER_INTO_JOIN}, it would try to create
+ * filters and push them into the inputs of the join to filter data as much as
+ * possible before join.
  *
  */
 @Value.Enclosing
diff --git a/core/src/main/java/org/apache/calcite/rel/rules/PruneEmptyRules.java b/core/src/main/java/org/apache/calcite/rel/rules/PruneEmptyRules.java
index ff208a9ccd..48b37ca74f 100644
--- a/core/src/main/java/org/apache/calcite/rel/rules/PruneEmptyRules.java
+++ b/core/src/main/java/org/apache/calcite/rel/rules/PruneEmptyRules.java
@@ -152,8 +152,9 @@ public abstract class PruneEmptyRules {
    * Rule that converts a {@link org.apache.calcite.rel.core.TableScan}
    * to empty if the table has no rows in it.
    *
-   * The rule exploits the {@link org.apache.calcite.rel.metadata.RelMdMaxRowCount} to derive if
-   * the table is empty or not.
+   * <p>The rule exploits the
+   * {@link org.apache.calcite.rel.metadata.RelMdMaxRowCount} to derive if the
+   * table is empty or not.
    */
   public static final RelOptRule EMPTY_TABLE_INSTANCE =
       ImmutableZeroMaxRowsRuleConfig.DEFAULT.toRule();
@@ -628,10 +629,12 @@ public abstract class PruneEmptyRules {
     }
   }
 
-  /** Configuration for rule that transforms an empty relational expression into an empty values.
+  /** Configuration for rule that transforms an empty relational expression into
+   * an empty values.
    *
-   * It relies on {@link org.apache.calcite.rel.metadata.RelMdMaxRowCount} to derive if the relation
-   * is empty or not. If the stats are not available then the rule is a noop. */
+   * <p>It relies on {@link org.apache.calcite.rel.metadata.RelMdMaxRowCount} to
+   * derive if the relation is empty or not. If the stats are not available then
+   * the rule is a noop. */
   @Value.Immutable
   public interface ZeroMaxRowsRuleConfig extends PruneEmptyRule.Config {
     ZeroMaxRowsRuleConfig DEFAULT = ImmutableZeroMaxRowsRuleConfig.of()
diff --git a/core/src/main/java/org/apache/calcite/rex/RexChecker.java b/core/src/main/java/org/apache/calcite/rex/RexChecker.java
index 66a70588f9..edf9b2bc63 100644
--- a/core/src/main/java/org/apache/calcite/rex/RexChecker.java
+++ b/core/src/main/java/org/apache/calcite/rex/RexChecker.java
@@ -41,7 +41,7 @@ import static java.util.Objects.requireNonNull;
  * RelDataType rowType;<br>
  * assert new RexChecker(rowType, true).isValid(node);</code></blockquote>
  *
- * This mode requires that assertions are enabled.</li>
+ * <p>This mode requires that assertions are enabled.</li>
  *
  * <li>Use <code>fail=false</code> to test for validity without throwing an
  * error.
diff --git a/core/src/main/java/org/apache/calcite/rex/package-info.java b/core/src/main/java/org/apache/calcite/rex/package-info.java
index 57bd7f4c39..351f21ce47 100644
--- a/core/src/main/java/org/apache/calcite/rex/package-info.java
+++ b/core/src/main/java/org/apache/calcite/rex/package-info.java
@@ -71,9 +71,9 @@
  *
  * <h2>Related packages</h2>
  * <ul>
- *     <li>{@link org.apache.calcite.sql} SQL object model</li>
+ * <li>{@link org.apache.calcite.sql} SQL object model</li>
  *
- *     <li>{@link org.apache.calcite.plan} Core classes, including
+ * <li>{@link org.apache.calcite.plan} Core classes, including
  * {@link org.apache.calcite.rel.type.RelDataType} and
  * {@link org.apache.calcite.rel.type.RelDataTypeFactory}.</li>
  *
diff --git a/core/src/main/java/org/apache/calcite/sql/package-info.java b/core/src/main/java/org/apache/calcite/sql/package-info.java
index eb1e52b367..27a8d137dd 100644
--- a/core/src/main/java/org/apache/calcite/sql/package-info.java
+++ b/core/src/main/java/org/apache/calcite/sql/package-info.java
@@ -31,23 +31,24 @@
  *
  * <p>Every node in the parse tree is a {@link org.apache.calcite.sql.SqlNode}.
  *     Sub-types are:
+ *
  * <ul>
  *
- *     <li>{@link org.apache.calcite.sql.SqlLiteral} represents a boolean,
- *         numeric, string, or date constant, or the value <code>NULL</code>.
- *         </li>
+ * <li>{@link org.apache.calcite.sql.SqlLiteral} represents a boolean,
+ *     numeric, string, or date constant, or the value <code>NULL</code>.
+ *     </li>
  *
- *     <li>{@link org.apache.calcite.sql.SqlIdentifier} represents an
- *         identifier, such as <code> EMPNO</code> or <code>emp.deptno</code>.
- *         </li>
+ * <li>{@link org.apache.calcite.sql.SqlIdentifier} represents an
+ *     identifier, such as <code> EMPNO</code> or <code>emp.deptno</code>.
+ *     </li>
  *
- *     <li>{@link org.apache.calcite.sql.SqlCall} is a call to an operator or
- *         function.  By means of special operators, we can use this construct
- *         to represent virtually every non-leaf node in the tree. For example,
- *         a <code>select</code> statement is a call to the 'select'
- *         operator.</li>
+ * <li>{@link org.apache.calcite.sql.SqlCall} is a call to an operator or
+ *     function.  By means of special operators, we can use this construct
+ *     to represent virtually every non-leaf node in the tree. For example,
+ *     a <code>select</code> statement is a call to the 'select'
+ *     operator.</li>
  *
- *     <li>{@link org.apache.calcite.sql.SqlNodeList} is a list of nodes.</li>
+ * <li>{@link org.apache.calcite.sql.SqlNodeList} is a list of nodes.</li>
  *
  * </ul>
  *
diff --git a/core/src/main/java/org/apache/calcite/sql/type/SqlTypeCoercionRule.java b/core/src/main/java/org/apache/calcite/sql/type/SqlTypeCoercionRule.java
index c54a7949bd..7370c1db9e 100644
--- a/core/src/main/java/org/apache/calcite/sql/type/SqlTypeCoercionRule.java
+++ b/core/src/main/java/org/apache/calcite/sql/type/SqlTypeCoercionRule.java
@@ -50,7 +50,7 @@ import java.util.Set;
  *
  * <p>The code snippet below illustrates how to implement a customized instance.
  *
- * <pre>
+ * <blockquote><pre>{@code
  *     // Initialize a Builder instance with the default mappings.
  *     Builder builder = SqlTypeMappingRules.builder();
  *     builder.addAll(SqlTypeCoercionRules.instance().getTypeMapping());
@@ -68,7 +68,7 @@ import java.util.Set;
  *     SqlValidator.Config validatorConf ...;
  *     validatorConf.withTypeCoercionRules(typeCoercionRules);
  *     // Use this conf to initialize the SqlValidator.
- * </pre>
+ * }</pre></blockquote>
  */
 public class SqlTypeCoercionRule implements SqlTypeMappingRule {
   //~ Static fields/initializers ---------------------------------------------
diff --git a/core/src/main/java/org/apache/calcite/sql/validate/ListScope.java b/core/src/main/java/org/apache/calcite/sql/validate/ListScope.java
index b86472d5b4..8c49a4a427 100644
--- a/core/src/main/java/org/apache/calcite/sql/validate/ListScope.java
+++ b/core/src/main/java/org/apache/calcite/sql/validate/ListScope.java
@@ -83,13 +83,15 @@ public abstract class ListScope extends DelegatingScope {
   /**
    * Whether the ith child namespace produces nullable result.
    *
-   * For example, in below query,
-   * <pre>
+   * <p>For example, in below query,
+   *
+   * <blockquote><pre>{@code
    *   SELECT *
    *   FROM EMPS
    *   LEFT OUTER JOIN DEPT
-   * </pre>
-   * the namespace which corresponding to 'DEPT' is nullable.
+   * }</pre></blockquote>
+   *
+   * <p>the namespace which corresponding to 'DEPT' is nullable.
    *
    * @param i The child index.
    * @return Whether it's nullable.
diff --git a/core/src/main/java/org/apache/calcite/sql/validate/SqlValidatorImpl.java b/core/src/main/java/org/apache/calcite/sql/validate/SqlValidatorImpl.java
index 387a36d33b..c65123c81f 100644
--- a/core/src/main/java/org/apache/calcite/sql/validate/SqlValidatorImpl.java
+++ b/core/src/main/java/org/apache/calcite/sql/validate/SqlValidatorImpl.java
@@ -7068,10 +7068,10 @@ public class SqlValidatorImpl implements SqlValidatorWithHints {
    * <p>Examples:
    *
    * <ul>
-   *   <li>{@code PREV(A.price + A.amount)} &rarr;
-   *   {@code PREV(A.price) + PREV(A.amount)}
+   * <li>{@code PREV(A.price + A.amount)} &rarr;
+   * {@code PREV(A.price) + PREV(A.amount)}
    *
-   *   <li>{@code FIRST(A.price * 2)} &rarr; {@code FIRST(A.PRICE) * 2}
+   * <li>{@code FIRST(A.price * 2)} &rarr; {@code FIRST(A.PRICE) * 2}
    * </ul>
    */
   private static class NavigationExpander extends NavigationModifier {
diff --git a/core/src/main/java/org/apache/calcite/sql/validate/implicit/TypeCoercionImpl.java b/core/src/main/java/org/apache/calcite/sql/validate/implicit/TypeCoercionImpl.java
index 23ae94f7ff..73de170e5c 100644
--- a/core/src/main/java/org/apache/calcite/sql/validate/implicit/TypeCoercionImpl.java
+++ b/core/src/main/java/org/apache/calcite/sql/validate/implicit/TypeCoercionImpl.java
@@ -72,15 +72,15 @@ public class TypeCoercionImpl extends AbstractTypeCoercion {
    * mainly used for set operations like UNION, INTERSECT and EXCEPT.
    *
    * <p>Rules:
-   * <pre>
-   *
+   * <blockquote><pre>
    *       type1, type2  type3       select a, b, c from t1
    *          \      \      \
    *         type4  type5  type6              UNION
    *          /      /      /
    *       type7  type8  type9       select d, e, f from t2
-   * </pre>
-   * For struct type (type1, type2, type3) union type (type4, type5, type6),
+   * </pre></blockquote>
+   *
+   * <p>For struct type (type1, type2, type3) union type (type4, type5, type6),
    * infer the first result column type type7 as the wider type of type1 and type4,
    * the second column type as the wider type of type2 and type5 and so on.
    *
diff --git a/core/src/main/java/org/apache/calcite/sql2rel/CorrelateProjectExtractor.java b/core/src/main/java/org/apache/calcite/sql2rel/CorrelateProjectExtractor.java
index 2e8029ba3c..50d255c331 100644
--- a/core/src/main/java/org/apache/calcite/sql2rel/CorrelateProjectExtractor.java
+++ b/core/src/main/java/org/apache/calcite/sql2rel/CorrelateProjectExtractor.java
@@ -204,9 +204,10 @@ public final class CorrelateProjectExtractor extends RelHomogeneousShuttle {
   /**
    * A collector of simply correlated row expressions.
    *
-   * The shuttle traverses the tree and collects all calls and field accesses that are classified
-   * as simply correlated expressions. Multiple nodes in a call hierarchy may satisfy the criteria
-   * of a simple correlation so we peek the expressions closest to the root.
+   * <p>The shuttle traverses the tree and collects all calls and field accesses
+   * that are classified as simply correlated expressions. Multiple nodes in a
+   * call hierarchy may satisfy the criteria of a simple correlation so we peek
+   * the expressions closest to the root.
    *
    * @see SimpleCorrelationDetector
    */
@@ -248,24 +249,26 @@ public final class CorrelateProjectExtractor extends RelHomogeneousShuttle {
   }
 
   /**
-   * A visitor classifying row expressions as simply correlated if they satisfy the conditions
-   * below.
+   * A visitor classifying row expressions as simply correlated if they satisfy
+   * the conditions below.
+   *
    * <ul>
    * <li>all correlated variables have the specified correlation id</li>
    * <li>all leafs are either correlated variables, dynamic parameters, or literals</li>
    * <li>intermediate nodes are either calls or field access expressions</li>
    * </ul>
    *
-   * Examples:
+   * <p>Examples:
+   *
    * <pre>{@code
    * +(10, $cor0.DEPTNO) -> TRUE
    * /(100,+(10, $cor0.DEPTNO)) -> TRUE
    * CAST(+(10, $cor0.DEPTNO)):INTEGER NOT NULL -> TRUE
    * +($0, $cor0.DEPTNO) -> FALSE
    * }</pre>
-   *
    */
-  private static class SimpleCorrelationDetector extends RexVisitorImpl<@Nullable Boolean> {
+  private static class SimpleCorrelationDetector
+      extends RexVisitorImpl<@Nullable Boolean> {
     private final CorrelationId corrId;
 
     private SimpleCorrelationDetector(CorrelationId corrId) {
diff --git a/core/src/main/java/org/apache/calcite/sql2rel/SqlToRelConverter.java b/core/src/main/java/org/apache/calcite/sql2rel/SqlToRelConverter.java
index f1360507ee..d45c987a92 100644
--- a/core/src/main/java/org/apache/calcite/sql2rel/SqlToRelConverter.java
+++ b/core/src/main/java/org/apache/calcite/sql2rel/SqlToRelConverter.java
@@ -2292,16 +2292,16 @@ public class SqlToRelConverter {
    * @param bb   Scope within which to resolve identifiers
    * @param from FROM clause of a query. Examples include:
    *
-   *             <ul>
-   *             <li>a single table ("SALES.EMP"),
-   *             <li>an aliased table ("EMP AS E"),
-   *             <li>a list of tables ("EMP, DEPT"),
-   *             <li>an ANSI Join expression ("EMP JOIN DEPT ON EMP.DEPTNO =
-   *             DEPT.DEPTNO"),
-   *             <li>a VALUES clause ("VALUES ('Fred', 20)"),
-   *             <li>a query ("(SELECT * FROM EMP WHERE GENDER = 'F')"),
-   *             <li>or any combination of the above.
-   *             </ul>
+   * <ul>
+   * <li>a single table ("SALES.EMP"),
+   * <li>an aliased table ("EMP AS E"),
+   * <li>a list of tables ("EMP, DEPT"),
+   * <li>an ANSI Join expression ("EMP JOIN DEPT ON EMP.DEPTNO = DEPT.DEPTNO"),
+   * <li>a VALUES clause ("VALUES ('Fred', 20)"),
+   * <li>a query ("(SELECT * FROM EMP WHERE GENDER = 'F')"),
+   * <li>or any combination of the above.
+   * </ul>
+   *
    * @param fieldNames Field aliases, usually come from AS clause, or null
    */
   protected void convertFrom(
diff --git a/core/src/main/java/org/apache/calcite/tools/RelBuilder.java b/core/src/main/java/org/apache/calcite/tools/RelBuilder.java
index d745488cb3..7c014d490c 100644
--- a/core/src/main/java/org/apache/calcite/tools/RelBuilder.java
+++ b/core/src/main/java/org/apache/calcite/tools/RelBuilder.java
@@ -4765,7 +4765,7 @@ public class RelBuilder {
      *            (a+b+c)-(d+e+f)-(g+h+i) AS t)        # complexity 34
      * </pre>
      *
-     * The complexity of an expression is the number of nodes (leaves and
+     * <p>The complexity of an expression is the number of nodes (leaves and
      * operators). For example, {@code a+b+c} has complexity 5 (3 field
      * references and 2 calls):
      *
diff --git a/core/src/main/java/org/apache/calcite/util/Util.java b/core/src/main/java/org/apache/calcite/util/Util.java
index 864a394476..4134e903cb 100644
--- a/core/src/main/java/org/apache/calcite/util/Util.java
+++ b/core/src/main/java/org/apache/calcite/util/Util.java
@@ -1469,15 +1469,13 @@ public class Util {
    * time
    * <li>The second offset is how many hours changed during DST. Default=1
    * <li>'start' and 'end' are the dates when DST goes into (and out of)
-   *     effect.<br>
-   *     <br>
-   *     They can each be one of three forms:
-   *
-   *     <ol>
-   *     <li>Mm.w.d {month=1-12, week=1-5 (5 is always last), day=0-6}
-   *     <li>Jn {n=1-365 Feb29 is never counted}
-   *     <li>n {n=0-365 Feb29 is counted in leap years}
-   *     </ol>
+   *     effect. They can each be one of three forms:
+   *
+   * <ol>
+   * <li>Mm.w.d {month=1-12, week=1-5 (5 is always last), day=0-6}
+   * <li>Jn {n=1-365 Feb29 is never counted}
+   * <li>n {n=0-365 Feb29 is counted in leap years}
+   * </ol>
    * </li>
    *
    * <li>'time' has the same format as 'offset', and defaults to 02:00:00.</li>
diff --git a/core/src/test/java/org/apache/calcite/test/LintTest.java b/core/src/test/java/org/apache/calcite/test/LintTest.java
index d84ea99dc0..8e65856dac 100644
--- a/core/src/test/java/org/apache/calcite/test/LintTest.java
+++ b/core/src/test/java/org/apache/calcite/test/LintTest.java
@@ -76,10 +76,24 @@ class LintTest {
                 line.state().message("<p> must be preceded by blank line",
                     line))
 
+        // A non-blank line following a blank line must have a '<p>'
+        .add(line -> line.state().inJavadoc()
+                && line.state().ulCount == 0
+                && line.state().blockquoteCount == 0
+                && line.contains("* ")
+                && line.fnr() - 1 == line.state().starLine
+                && line.matches("^ *\\* [^<@].*"),
+            line -> line.state().message("missing '<p>'", line))
+
         // The first "@param" of a javadoc block must be preceded by a blank
         // line.
         .add(line -> line.matches("^ */\\*\\*.*"),
-            line -> line.state().javadocStartLine = line.fnr())
+            line -> {
+              final FileState f = line.state();
+              f.javadocStartLine = line.fnr();
+              f.blockquoteCount = 0;
+              f.ulCount = 0;
+            })
         .add(line -> line.matches(".*\\*/"),
             line -> line.state().javadocEndLine = line.fnr())
         .add(line -> line.matches("^ *\\* @.*"),
@@ -93,6 +107,14 @@ class LintTest {
               }
               line.state().atLine = line.fnr();
             })
+        .add(line -> line.contains("<blockquote>"),
+            line -> line.state().blockquoteCount++)
+        .add(line -> line.contains("</blockquote>"),
+            line -> line.state().blockquoteCount--)
+        .add(line -> line.contains("<ul>"),
+            line -> line.state().ulCount++)
+        .add(line -> line.contains("</ul>"),
+            line -> line.state().ulCount--)
         .build();
   }
 
@@ -111,6 +133,8 @@ class LintTest {
         + "  String x = \"ok because it's not in javadoc:</p>\";\n"
         + "}\n";
     final String expectedMessages = "["
+        + "GuavaCharSource{memory}:4:"
+        + "missing '<p>'\n"
         + "GuavaCharSource{memory}:6:"
         + "<p> must not be on its own line\n"
         + "GuavaCharSource{memory}:7:"
@@ -267,6 +291,8 @@ class LintTest {
     int atLine;
     int javadocStartLine;
     int javadocEndLine;
+    int blockquoteCount;
+    int ulCount;
 
     FileState(GlobalState global) {
       this.global = global;
diff --git a/core/src/test/java/org/apache/calcite/test/RelOptRulesTest.java b/core/src/test/java/org/apache/calcite/test/RelOptRulesTest.java
index 150fa85f25..1fc25ab75f 100644
--- a/core/src/test/java/org/apache/calcite/test/RelOptRulesTest.java
+++ b/core/src/test/java/org/apache/calcite/test/RelOptRulesTest.java
@@ -7660,13 +7660,13 @@ class RelOptRulesTest extends RelOptTestBase {
         .checkUnchanged();
   }
 
-  /**
-   * Test case for <a href="https://issues.apache.org/jira/browse/CALCITE-5247">[CALCITE-5247]
-   *    * FilterJoinRule cannot simplify left join to inner join for `WHERE RHS.C1 IS NOT NULL OR
-   *    RHS.C2 IS NOT NULL`</a>.
+  /** Test case for
+   * <a href="https://issues.apache.org/jira/browse/CALCITE-5247">[CALCITE-5247]
+   * FilterJoinRule cannot simplify left join to inner join for `WHERE
+   * RHS.C1 IS NOT NULL OR RHS.C2 IS NOT NULL`</a>.
    *
-   *    This tests the case where the condition contains an OR between the IS NOT NULL filters
-   */
+   * <p>This tests the case where the condition contains an OR between
+   * the IS NOT NULL filters. */
   @Test void testFilterJoinRuleOrIsNotNull() {
     final String sql = "select * from\n"
         + "emp LHS\n"
@@ -7680,13 +7680,13 @@ class RelOptRulesTest extends RelOptTestBase {
         .check();
   }
 
-  /**
-   * Test case for <a href="https://issues.apache.org/jira/browse/CALCITE-5247">[CALCITE-5247]
-   *    * FilterJoinRule cannot simplify left join to inner join for `WHERE RHS.C1 IS NOT NULL OR
-   *    RHS.C2 IS NOT NULL`</a>.
+  /** Test case for
+   * <a href="https://issues.apache.org/jira/browse/CALCITE-5247">[CALCITE-5247]
+   * FilterJoinRule cannot simplify left join to inner join for `WHERE
+   * RHS.C1 IS NOT NULL OR RHS.C2 IS NOT NULL`</a>.
    *
-   *    This tests the case where the condition contains an AND between the IS NOT NULL filters
-   */
+   * <p>This tests the case where the condition contains an AND
+   * between the IS NOT NULL filters. */
   @Test void testFilterJoinRuleAndIsNotNull() {
     final String sql = "select * from\n"
         + "emp LHS\n"
diff --git a/core/src/test/java/org/apache/calcite/test/concurrent/package-info.java b/core/src/test/java/org/apache/calcite/test/concurrent/package-info.java
index c00e80a859..524e6d6d93 100644
--- a/core/src/test/java/org/apache/calcite/test/concurrent/package-info.java
+++ b/core/src/test/java/org/apache/calcite/test/concurrent/package-info.java
@@ -306,11 +306,10 @@
  *
  * <p>(Yes the results of the select statements are obviously wrong.)
  *
- *         <h3>Open Issues</h3>
- *
- *         <ul>
- *             <li>Repeating tests for a period of time isn't supported.</li>
- *         </ul>
+ * <h3>Open Issues</h3>
  *
+ * <ul>
+ * <li>Repeating tests for a period of time isn't supported.</li>
+ * </ul>
  */
 package org.apache.calcite.test.concurrent;
diff --git a/elasticsearch/src/test/java/org/apache/calcite/adapter/elasticsearch/EmbeddedElasticsearchPolicy.java b/elasticsearch/src/test/java/org/apache/calcite/adapter/elasticsearch/EmbeddedElasticsearchPolicy.java
index 38029c32fc..fb84809443 100644
--- a/elasticsearch/src/test/java/org/apache/calcite/adapter/elasticsearch/EmbeddedElasticsearchPolicy.java
+++ b/elasticsearch/src/test/java/org/apache/calcite/adapter/elasticsearch/EmbeddedElasticsearchPolicy.java
@@ -43,7 +43,8 @@ import java.util.Objects;
  * does not allow multiple instances per JVM).
  *
  * <p>This rule should be used as follows:
- * <pre>
+ *
+ * <blockquote><pre><code>
  * public class MyTest {
  *   public static final EmbeddedElasticsearchPolicy RULE =
  *       EmbeddedElasticsearchPolicy.create();
@@ -61,7 +62,7 @@ import java.util.Objects;
  *     // ....
  *   }
  * }
- * </pre>
+ * </code></pre></blockquote>
  */
 class EmbeddedElasticsearchPolicy {
 
diff --git a/linq4j/src/main/java/org/apache/calcite/linq4j/EnumerableDefaults.java b/linq4j/src/main/java/org/apache/calcite/linq4j/EnumerableDefaults.java
index ae92498dc2..8494dd531d 100644
--- a/linq4j/src/main/java/org/apache/calcite/linq4j/EnumerableDefaults.java
+++ b/linq4j/src/main/java/org/apache/calcite/linq4j/EnumerableDefaults.java
@@ -2206,9 +2206,10 @@ public abstract class EnumerableDefaults {
   }
 
   /**
-   * Joins two inputs that are sorted on the key, with an extra predicate for non equi-join
-   * conditions.
-   * Inputs must sorted in ascending order, nulls last.
+   * Joins two inputs that are sorted on the key, with an extra predicate for
+   * non equi-join conditions.
+   *
+   * <p>Inputs be must sorted in ascending order, nulls last.
    *
    * @param extraPredicate predicate for non equi-join conditions. In case of equi-join,
    *                       it will be null. In case of non-equi join, the non-equi conditions
@@ -2219,7 +2220,8 @@ public abstract class EnumerableDefaults {
    * @param comparator key comparator, possibly null (in which case {@link Comparable#compareTo}
    *                   will be used).
    *
-   * NOTE: The current API is experimental and subject to change without notice.
+   * <p>NOTE: The current API is experimental and subject to change without
+   * notice.
    */
   @API(since = "1.23", status = API.Status.EXPERIMENTAL)
   public static <TSource, TInner, TKey extends Comparable<TKey>, TResult> Enumerable<TResult>
diff --git a/linq4j/src/main/java/org/apache/calcite/linq4j/function/NonDeterministic.java b/linq4j/src/main/java/org/apache/calcite/linq4j/function/NonDeterministic.java
index 0de4c53847..6c9569847e 100644
--- a/linq4j/src/main/java/org/apache/calcite/linq4j/function/NonDeterministic.java
+++ b/linq4j/src/main/java/org/apache/calcite/linq4j/function/NonDeterministic.java
@@ -25,8 +25,8 @@ import java.lang.annotation.Target;
  * Specifies that function is NOT deterministic (i.e. it can return
  * different output given the same inputs).
  *
- * The function is treated as non-deterministic even if {@code @Deterministic}
- * annotation is present at class level.
+ * <p>The function is treated as non-deterministic even if
+ * {@code @Deterministic} annotation is present at class level.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE })
diff --git a/redis/src/test/java/org/apache/calcite/adapter/redis/RedisCaseBase.java b/redis/src/test/java/org/apache/calcite/adapter/redis/RedisCaseBase.java
index 1459a00cbc..bf54157249 100644
--- a/redis/src/test/java/org/apache/calcite/adapter/redis/RedisCaseBase.java
+++ b/redis/src/test/java/org/apache/calcite/adapter/redis/RedisCaseBase.java
@@ -46,7 +46,7 @@ public abstract class RedisCaseBase {
   /**
    * The Redis Docker container.
    *
-   * Uses the Redis 2.8.19 version to be aligned with the embedded server.
+   * <p>Uses the Redis 2.8.19 version to be aligned with the embedded server.
    */
   private static final GenericContainer<?> REDIS_CONTAINER =
       new GenericContainer<>("redis:2.8.19").withExposedPorts(6379);
@@ -54,8 +54,8 @@ public abstract class RedisCaseBase {
   /**
    * The embedded Redis server.
    *
-   * With the existing dependencies (com.github.kstyrc:embedded-redis:0.6) it uses by default
-   * Redis 2.8.19 version.
+   * <p>With the existing dependencies (com.github.kstyrc:embedded-redis:0.6) it
+   * uses by default Redis 2.8.19 version.
    */
   private static RedisServer redisServer;
 
diff --git a/ubenchmark/src/jmh/java/org/apache/calcite/benchmarks/MetadataBenchmark.java b/ubenchmark/src/jmh/java/org/apache/calcite/benchmarks/MetadataBenchmark.java
index a78c79eb15..dece4c9aff 100644
--- a/ubenchmark/src/jmh/java/org/apache/calcite/benchmarks/MetadataBenchmark.java
+++ b/ubenchmark/src/jmh/java/org/apache/calcite/benchmarks/MetadataBenchmark.java
@@ -46,8 +46,7 @@ import java.util.function.Supplier;
 /**
  * A benchmark to compare metadata retrieval time for a complex query.
  *
- * Compares metadata retrieval performance on a large query
- *
+ * <p>Compares metadata retrieval performance on a large query.
  */
 @Fork(value = 1, jvmArgsPrepend = "-Xmx2048m")
 @State(Scope.Benchmark)