Build: Mostly silence warning about html4 javadoc (#30220)

This *mostly* silences `javadoc`'s warning about defaulting to
generating html4 files by enabling generating html5 file for the
projects for which that works. It didn't work in a half dozen projects,
about half of which I've fixed in this PR, entirely by replacing
`<tt>thing</tt>` with `{@code thing}`.

There are a few remaining projects that contain javadoc with invalid
html5. I'll fix those projects in a followup.

Author: nik9000

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

@@ -549,6 +549,25 @@ class BuildPlugin implements Plugin<Project> {
             javadoc.classpath = javadoc.getClasspath().filter { f ->
                 return classes.contains(f) == false
             }
+            /*
+             * Force html5 on projects that support it to silence the warning
+             * that `javadoc` will change its defaults in the future.
+             *
+             * But not all of our javadoc is actually valid html5. So we
+             * have to become valid incrementally. We only set html5 on the
+             * projects we have converted so that we still get the annoying
+             * warning on the unconverted ones. That will give us an
+             * incentive to convert them....
+             */
+            List html4Projects = [
+                ':server',
+                ':libs:elasticsearch-core',
+                ':test:framework',
+                ':x-pack:plugin:core',
+            ]
+            if (false == html4Projects.contains(project.path)) {
+                javadoc.options.addBooleanOption('html5', true)
+            }
         }
         configureJavadocJar(project)
     }

client/client-benchmark-noop-api-plugin/src/main/java/org/elasticsearch/plugin/noop/action/bulk/NoopBulkRequestBuilder.java

@@ -129,15 +129,17 @@ public NoopBulkRequestBuilder setWaitForActiveShards(final int waitForActiveShar
     }
 
     /**
-     * A timeout to wait if the index operation can't be performed immediately. Defaults to <tt>1m</tt>.
+     * A timeout to wait if the index operation can't be performed immediately.
+     * Defaults to {@code 1m}.
      */
     public final NoopBulkRequestBuilder setTimeout(TimeValue timeout) {
         request.timeout(timeout);
         return this;
     }
 
     /**
-     * A timeout to wait if the index operation can't be performed immediately. Defaults to <tt>1m</tt>.
+     * A timeout to wait if the index operation can't be performed immediately.
+     * Defaults to {@code 1m}.
      */
     public final NoopBulkRequestBuilder setTimeout(String timeout) {
         request.timeout(timeout);
@@ -151,4 +153,3 @@ public int numberOfActions() {
         return request.numberOfActions();
     }
 }
-

client/client-benchmark-noop-api-plugin/src/main/java/org/elasticsearch/plugin/noop/action/search/NoopSearchRequestBuilder.java

@@ -142,7 +142,7 @@ public NoopSearchRequestBuilder setRouting(String... routing) {
 
     /**
      * Sets the preference to execute the search. Defaults to randomize across shards. Can be set to
-     * <tt>_local</tt> to prefer local shards, <tt>_primary</tt> to execute only on primary shards, or
+     * {@code _local} to prefer local shards, {@code _primary} to execute only on primary shards, or
      * a custom value, which guarantees that the same order will be used across different requests.
      */
     public NoopSearchRequestBuilder setPreference(String preference) {
@@ -188,15 +188,15 @@ public NoopSearchRequestBuilder setMinScore(float minScore) {
     }
 
     /**
-     * From index to start the search from. Defaults to <tt>0</tt>.
+     * From index to start the search from. Defaults to {@code 0}.
      */
     public NoopSearchRequestBuilder setFrom(int from) {
         sourceBuilder().from(from);
         return this;
     }
 
     /**
-     * The number of search hits to return. Defaults to <tt>10</tt>.
+     * The number of search hits to return. Defaults to {@code 10}.
      */
     public NoopSearchRequestBuilder setSize(int size) {
         sourceBuilder().size(size);
@@ -349,7 +349,7 @@ public NoopSearchRequestBuilder slice(SliceBuilder builder) {
 
     /**
      * Applies when sorting, and controls if scores will be tracked as well. Defaults to
-     * <tt>false</tt>.
+     * {@code false}.
      */
     public NoopSearchRequestBuilder setTrackScores(boolean trackScores) {
         sourceBuilder().trackScores(trackScores);

modules/parent-join/src/main/java/org/elasticsearch/join/query/HasChildQueryBuilder.java

@@ -57,7 +57,7 @@
 import java.util.Objects;
 
 /**
- * A query builder for <tt>has_child</tt> query.
+ * A query builder for {@code has_child} query.
  */
 public class HasChildQueryBuilder extends AbstractQueryBuilder<HasChildQueryBuilder> {
     public static final String NAME = "has_child";

modules/rank-eval/src/main/java/org/elasticsearch/index/rankeval/DiscountedCumulativeGain.java

@@ -41,7 +41,7 @@
 
 /**
  * Metric implementing Discounted Cumulative Gain.
- * The `normalize` parameter can be set to calculate the normalized NDCG (set to <tt>false</tt> by default).<br>
+ * The `normalize` parameter can be set to calculate the normalized NDCG (set to {@code false} by default).<br>
  * The optional `unknown_doc_rating` parameter can be used to specify a default rating for unlabeled documents.
  * @see <a href="https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Discounted_Cumulative_Gain">Discounted Cumulative Gain</a><br>
  */

modules/rank-eval/src/main/java/org/elasticsearch/index/rankeval/RatedRequest.java

@@ -192,7 +192,7 @@ public Map<String, Object> getParams() {
         return Collections.unmodifiableMap(this.params);
     }
 
-    /** return the parameters if this request uses a template, otherwise this will be <tt>null</tt>. */
+    /** return the parameters if this request uses a template, otherwise this will be {@code null}. */
     public String getTemplateId() {
         return this.templateId;
     }

plugins/analysis-icu/src/main/java/org/elasticsearch/index/analysis/IcuCollationTokenFilterFactory.java

@@ -36,12 +36,12 @@
 
 /**
  * An ICU based collation token filter. There are two ways to configure collation:
- * <p>The first is simply specifying the locale (defaults to the default locale). The <tt>language</tt>
- * parameter is the lowercase two-letter ISO-639 code. An additional <tt>country</tt> and <tt>variant</tt>
+ * <p>The first is simply specifying the locale (defaults to the default locale). The {@code language}
+ * parameter is the lowercase two-letter ISO-639 code. An additional {@code country} and {@code variant}
  * can be provided.
  * <p>The second option is to specify collation rules as defined in the <a href="http://www.icu-project.org/userguide/Collate_Customization.html">
- * Collation customization</a> chapter in icu docs. The <tt>rules</tt> parameter can either embed the rules definition
- * in the settings or refer to an external location (preferable located under the <tt>config</tt> location, relative to it).
+ * Collation customization</a> chapter in icu docs. The {@code rules} parameter can either embed the rules definition
+ * in the settings or refer to an external location (preferable located under the {@code config} location, relative to it).
  */
 public class IcuCollationTokenFilterFactory extends AbstractTokenFilterFactory {
 

plugins/analysis-icu/src/main/java/org/elasticsearch/index/analysis/IcuFoldingTokenFilterFactory.java

@@ -35,7 +35,7 @@
  * Can be filtered to handle certain characters in a specified way (see http://icu-project.org/apiref/icu4j/com/ibm/icu/text/UnicodeSet.html)
  * E.g national chars that should be retained (filter : "[^åäöÅÄÖ]").
  *
- * <p>The <tt>unicodeSetFilter</tt> attribute can be used to provide the UniCodeSet for filtering.
+ * <p>The {@code unicodeSetFilter} attribute can be used to provide the UniCodeSet for filtering.
  *
  * @author kimchy (shay.banon)
  */

plugins/analysis-icu/src/main/java/org/elasticsearch/index/analysis/IcuNormalizerCharFilterFactory.java

@@ -32,9 +32,9 @@
 
 /**
  * Uses the {@link org.apache.lucene.analysis.icu.ICUNormalizer2CharFilter} to normalize character.
- * <p>The <tt>name</tt> can be used to provide the type of normalization to perform.</p>
- * <p>The <tt>mode</tt> can be used to provide 'compose' or 'decompose'. Default is compose.</p>
- * <p>The <tt>unicodeSetFilter</tt> attribute can be used to provide the UniCodeSet for filtering.</p>
+ * <p>The {@code name} can be used to provide the type of normalization to perform.</p>
+ * <p>The {@code mode} can be used to provide 'compose' or 'decompose'. Default is compose.</p>
+ * <p>The {@code unicodeSetFilter} attribute can be used to provide the UniCodeSet for filtering.</p>
  */
 public class IcuNormalizerCharFilterFactory extends AbstractCharFilterFactory implements MultiTermAwareComponent {
 

plugins/analysis-icu/src/main/java/org/elasticsearch/index/analysis/IcuNormalizerTokenFilterFactory.java

@@ -31,10 +31,8 @@
 
 /**
  * Uses the {@link org.apache.lucene.analysis.icu.ICUNormalizer2Filter} to normalize tokens.
- * <p>The <tt>name</tt> can be used to provide the type of normalization to perform.</p>
- * <p>The <tt>unicodeSetFilter</tt> attribute can be used to provide the UniCodeSet for filtering.</p>
- *
- *
+ * <p>The {@code name} can be used to provide the type of normalization to perform.</p>
+ * <p>The {@code unicodeSetFilter} attribute can be used to provide the UniCodeSet for filtering.</p>
  */
 public class IcuNormalizerTokenFilterFactory extends AbstractTokenFilterFactory implements MultiTermAwareComponent {