HTML5ify Javadoc for core and test framework (#30234)

`javadoc` will switch from detaulting to html4 to html5 in "a future
release". We should get ahead of it so we're not surprised. Also, HTML5
is the future! Er, the present. Anyway, this follows up from #30220 to
make the Javadoc for two of the four remaining projects HTML5
compatible.

buildSrc/src/main/groovy/org/elasticsearch/gradle/BuildPlugin.groovy

@@ -561,8 +561,6 @@ class BuildPlugin implements Plugin<Project> {
              */
             List html4Projects = [
                 ':server',
-                ':libs:elasticsearch-core',
-                ':test:framework',
                 ':x-pack:plugin:core',
             ]
             if (false == html4Projects.contains(project.path)) {

libs/elasticsearch-core/src/main/java/org/elasticsearch/common/Booleans.java

@@ -107,7 +107,7 @@ public final class Booleans {
     }
 
     /**
-     * Returns <code>false</code> if text is in <tt>false</tt>, <tt>0</tt>, <tt>off</tt>, <tt>no</tt>; else, true
+     * Returns {@code false} if text is in "false", "0", "off", "no"; else, {@code true}.
      *
      * @deprecated Only kept to provide automatic upgrades for pre 6.0 indices. Use {@link #parseBoolean(String, Boolean)} instead.
      */
@@ -119,9 +119,7 @@ public final class Booleans {
         return parseBooleanLenient(value, false);
     }
     /**
-     * Returns <code>true</code> iff the value is neither of the following:
-     *   <tt>false</tt>, <tt>0</tt>, <tt>off</tt>, <tt>no</tt>
-     *   otherwise <code>false</code>
+     * Returns {@code false} if text is in "false", "0", "off", "no"; else, {@code true}.
      *
      * @deprecated Only kept to provide automatic upgrades for pre 6.0 indices. Use {@link #parseBoolean(String, boolean)} instead.
      */
@@ -134,21 +132,21 @@ public final class Booleans {
     }
 
     /**
-     * @return <code>true</code> iff the value is <tt>false</tt>, otherwise <code>false</code>.
+     * @return {@code true} iff the value is "false", otherwise {@code false}.
      */
     public static boolean isFalse(String value) {
         return "false".equals(value);
     }
 
     /**
-     * @return <code>true</code> iff the value is <tt>true</tt>, otherwise <code>false</code>
+     * @return {@code true} iff the value is "true", otherwise {@code false}.
      */
     public static boolean isTrue(String value) {
         return "true".equals(value);
     }
 
     /**
-     * Returns <code>false</code> if text is in <tt>false</tt>, <tt>0</tt>, <tt>off</tt>, <tt>no</tt>; else, true
+     * Returns {@code false} if text is in "false", "0", "off", "no"; else, {@code true}.
      *
      * @deprecated Only kept to provide automatic upgrades for pre 6.0 indices. Use {@link #parseBoolean(char[], int, int, boolean)} instead
      */

libs/elasticsearch-core/src/main/java/org/elasticsearch/core/internal/io/IOUtils.java

@@ -37,11 +37,11 @@ import java.util.Map;
 public final class IOUtils {
 
     private IOUtils() {
-
+        // Static utils methods
     }
 
     /**
-     * Closes all given <tt>Closeable</tt>s. Some of the <tt>Closeable</tt>s may be null; they are
+     * Closes all given {@link Closeable}s. Some of the {@linkplain Closeable}s may be null; they are
      * ignored. After everything is closed, the method either throws the first exception it hit
      * while closing with other exceptions added as suppressed, or completes normally if there were
      * no exceptions.
@@ -53,7 +53,7 @@ public final class IOUtils {
     }
 
     /**
-     * Closes all given <tt>Closeable</tt>s. Some of the <tt>Closeable</tt>s may be null; they are
+     * Closes all given {@link Closeable}s. Some of the {@linkplain Closeable}s may be null; they are
      * ignored. After everything is closed, the method adds any exceptions as suppressed to the
      * original exception, or throws the first exception it hit if {@code Exception} is null. If
      * no exceptions are encountered and the passed in exception is null, it completes normally.
@@ -65,7 +65,7 @@ public final class IOUtils {
     }
 
     /**
-     * Closes all given <tt>Closeable</tt>s. Some of the <tt>Closeable</tt>s may be null; they are
+     * Closes all given {@link Closeable}s. Some of the {@linkplain Closeable}s may be null; they are
      * ignored. After everything is closed, the method either throws the first exception it hit
      * while closing with other exceptions added as suppressed, or completes normally if there were
      * no exceptions.

test/framework/src/main/java/org/elasticsearch/test/ESIntegTestCase.java

@@ -1352,7 +1352,7 @@ public abstract class ESIntegTestCase extends ESTestCase {
      * segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index
      * layout.
      *
-     * @param forceRefresh if <tt>true</tt> all involved indices are refreshed once the documents are indexed. Additionally if <tt>true</tt>
+     * @param forceRefresh if {@code true} all involved indices are refreshed once the documents are indexed. Additionally if {@code true}
      *                     some empty dummy documents are may be randomly inserted into the document list and deleted once all documents are indexed.
      *                     This is useful to produce deleted documents on the server side.
      * @param builders     the documents to index.
@@ -1369,8 +1369,8 @@ public abstract class ESIntegTestCase extends ESTestCase {
      * segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index
      * layout.
      *
-     * @param forceRefresh   if <tt>true</tt> all involved indices are refreshed once the documents are indexed.
-     * @param dummyDocuments if <tt>true</tt> some empty dummy documents may be randomly inserted into the document list and deleted once
+     * @param forceRefresh   if {@code true} all involved indices are refreshed once the documents are indexed.
+     * @param dummyDocuments if {@code true} some empty dummy documents may be randomly inserted into the document list and deleted once
      *                       all documents are indexed. This is useful to produce deleted documents on the server side.
      * @param builders       the documents to index.
      */
@@ -1385,10 +1385,10 @@ public abstract class ESIntegTestCase extends ESTestCase {
      * segment or if only one document is in a segment etc. This method prevents issues like this by randomizing the index
      * layout.
      *
-     * @param forceRefresh   if <tt>true</tt> all involved indices are refreshed once the documents are indexed.
-     * @param dummyDocuments if <tt>true</tt> some empty dummy documents may be randomly inserted into the document list and deleted once
+     * @param forceRefresh   if {@code true} all involved indices are refreshed once the documents are indexed.
+     * @param dummyDocuments if {@code true} some empty dummy documents may be randomly inserted into the document list and deleted once
      *                       all documents are indexed. This is useful to produce deleted documents on the server side.
-     * @param maybeFlush     if <tt>true</tt> this method may randomly execute full flushes after index operations.
+     * @param maybeFlush     if {@code true} this method may randomly execute full flushes after index operations.
      * @param builders       the documents to index.
      */
     public void indexRandom(boolean forceRefresh, boolean dummyDocuments, boolean maybeFlush, List<IndexRequestBuilder> builders) throws InterruptedException, ExecutionException {
@@ -1554,27 +1554,27 @@ public abstract class ESIntegTestCase extends ESTestCase {
         Scope scope() default Scope.SUITE;
 
         /**
-         * Returns the number of nodes in the cluster. Default is <tt>-1</tt> which means
+         * Returns the number of nodes in the cluster. Default is {@code -1} which means
          * a random number of nodes is used, where the minimum and maximum number of nodes
          * are either the specified ones or the default ones if not specified.
          */
         int numDataNodes() default -1;
 
         /**
-         * Returns the minimum number of data nodes in the cluster. Default is <tt>-1</tt>.
+         * Returns the minimum number of data nodes in the cluster. Default is {@code -1}.
          * Ignored when {@link ClusterScope#numDataNodes()} is set.
          */
         int minNumDataNodes() default -1;
 
         /**
-         * Returns the maximum number of data nodes in the cluster.  Default is <tt>-1</tt>.
+         * Returns the maximum number of data nodes in the cluster.  Default is {@code -1}.
          * Ignored when {@link ClusterScope#numDataNodes()} is set.
          */
         int maxNumDataNodes() default -1;
 
         /**
-         * Indicates whether the cluster can have dedicated master nodes. If <tt>false</tt> means data nodes will serve as master nodes
-         * and there will be no dedicated master (and data) nodes. Default is <tt>true</tt> which means
+         * Indicates whether the cluster can have dedicated master nodes. If {@code false} means data nodes will serve as master nodes
+         * and there will be no dedicated master (and data) nodes. Default is {@code false} which means
          * dedicated master nodes will be randomly used.
          */
         boolean supportsDedicatedMasters() default true;
@@ -1703,7 +1703,7 @@ public abstract class ESIntegTestCase extends ESTestCase {
     }
 
     /**
-     * This method is used to obtain settings for the <tt>Nth</tt> node in the cluster.
+     * This method is used to obtain settings for the {@code N}th node in the cluster.
      * Nodes in this cluster are associated with an ordinal number such that nodes can
      * be started with specific configurations. This method might be called multiple
      * times with the same ordinal and is expected to return the same value for each invocation.
@@ -1878,7 +1878,7 @@ public abstract class ESIntegTestCase extends ESTestCase {
 
     /**
      * Iff this returns true mock transport implementations are used for the test runs. Otherwise not mock transport impls are used.
-     * The default is <tt>true</tt>
+     * The default is {@code true}.
      */
     protected boolean addMockTransportService() {
         return true;
@@ -1886,7 +1886,7 @@ public abstract class ESIntegTestCase extends ESTestCase {
 
     /**
      * Iff this returns true test zen discovery implementations is used for the test runs.
-     * The default is <tt>true</tt>
+     * The default is {@code true}.
      */
     protected boolean addTestZenDiscovery() {
         return true;
@@ -1957,7 +1957,7 @@ public abstract class ESIntegTestCase extends ESTestCase {
     /**
      * Returns the transport client ratio from the class level annotation or via
      * {@link System#getProperty(String)} if available. If both are not available this will
-     * return a random ratio in the interval <tt>[0..1]</tt>
+     * return a random ratio in the interval {@code [0..1]}.
      */
     protected double getPerTestTransportClientRatio() {
         final ClusterScope annotation = getAnnotation(this.getClass(), ClusterScope.class);

test/framework/src/main/java/org/elasticsearch/test/InternalTestCluster.java

@@ -1978,7 +1978,7 @@ public final class InternalTestCluster extends TestCluster {
         }
 
         /**
-         * Executed for each node before the <tt>n+1</tt> node is restarted. The given client is
+         * Executed for each node before the {@code n + 1} node is restarted. The given client is
          * an active client to the node that will be restarted next.
          */
         public void doAfterNodes(int n, Client client) throws Exception {

test/framework/src/main/java/org/elasticsearch/test/XContentTestUtils.java

@@ -145,7 +145,7 @@ public final class XContentTestUtils {
      * If the xContent output contains objects that should be skipped of such treatment, an optional filtering
      * {@link Predicate} can be supplied that checks xContent paths that should be excluded from this treatment.
      *
-     * This predicate should check the xContent path that we want to insert to and return <tt>true</tt> if the
+     * This predicate should check the xContent path that we want to insert to and return {@code true} if the
      * path should be excluded. Paths are string concatenating field names and array indices, so e.g. in:
      *
      * <pre>

test/framework/src/main/java/org/elasticsearch/test/engine/MockEngineSupport.java

@@ -19,14 +19,13 @@
 package org.elasticsearch.test.engine;
 
 import org.apache.logging.log4j.Logger;
+import org.apache.lucene.index.AssertingDirectoryReader;
 import org.apache.lucene.index.DirectoryReader;
 import org.apache.lucene.index.FilterDirectoryReader;
 import org.apache.lucene.index.IndexReader;
 import org.apache.lucene.search.AssertingIndexSearcher;
-import org.apache.lucene.search.IndexSearcher;
 import org.apache.lucene.search.QueryCache;
 import org.apache.lucene.search.QueryCachingPolicy;
-import org.apache.lucene.search.ReferenceManager;
 import org.apache.lucene.util.LuceneTestCase;
 import org.elasticsearch.ElasticsearchException;
 import org.elasticsearch.common.logging.Loggers;
@@ -38,6 +37,7 @@ import org.elasticsearch.index.engine.EngineConfig;
 import org.elasticsearch.index.engine.EngineException;
 import org.elasticsearch.index.shard.ShardId;
 import org.elasticsearch.test.ESIntegTestCase;
+import org.elasticsearch.test.engine.MockInternalEngine;
 
 import java.io.Closeable;
 import java.io.IOException;
@@ -47,14 +47,15 @@ import java.util.Random;
 import java.util.concurrent.atomic.AtomicBoolean;
 
 /**
- * Support class to build MockEngines like {@link org.elasticsearch.test.engine.MockInternalEngine}
+ * Support class to build MockEngines like {@link MockInternalEngine}
  * since they need to subclass the actual engine
  */
 public final class MockEngineSupport {
 
     /**
-     * Allows tests to wrap an index reader randomly with a given ratio. This is disabled by default ie. <tt>0.0d</tt> since reader wrapping is insanely
-     * slow if {@link org.apache.lucene.index.AssertingDirectoryReader} is used.
+     * Allows tests to wrap an index reader randomly with a given ratio. This
+     * is disabled by default ie. {@code 0.0d} since reader wrapping is insanely
+     * slow if {@link AssertingDirectoryReader} is used.
      */
     public static final Setting<Double> WRAP_READER_RATIO =
         Setting.doubleSetting("index.engine.mock.random.wrap_reader_ratio", 0.0d, 0.0d, Property.IndexScope);

test/framework/src/main/java/org/elasticsearch/test/transport/MockTransportService.java

@@ -474,7 +474,7 @@ public final class MockTransportService extends TransportService {
     /**
      * Adds a new delegate transport that is used for communication with the given transport service.
      *
-     * @return <tt>true</tt> iff no other delegate was registered for any of the addresses bound by transport service.
+     * @return {@code true} iff no other delegate was registered for any of the addresses bound by transport service.
      */
     public boolean addDelegate(TransportService transportService, DelegateTransport transport) {
         boolean noRegistered = true;
@@ -487,7 +487,7 @@ public final class MockTransportService extends TransportService {
     /**
      * Adds a new delegate transport that is used for communication with the given transport address.
      *
-     * @return <tt>true</tt> iff no other delegate was registered for this address before.
+     * @return {@code true} iff no other delegate was registered for this address before.
      */
     public boolean addDelegate(TransportAddress transportAddress, DelegateTransport transport) {
         return transport().transports.put(transportAddress, transport) == null;