fix: make javadoc:javadoc succeed on the forked OpenSearch tree

pom.xml

@@ -45,6 +45,37 @@
 		<testcontainers.version>1.21.4</testcontainers.version>
 	</properties>
 	<build>
+		<pluginManagement>
+			<plugins>
+				<plugin>
+					<artifactId>maven-javadoc-plugin</artifactId>
+					<version>3.12.0</version>
+					<configuration>
+						<encoding>UTF-8</encoding>
+						<docencoding>UTF-8</docencoding>
+						<charset>UTF-8</charset>
+						<!-- Block tags the forked OpenSearch sources carry; javadoc rejects them unless declared. -->
+						<tags>
+							<tag>
+								<name>opensearch.api</name>
+								<placement>a</placement>
+								<head>OpenSearch API:</head>
+							</tag>
+							<tag>
+								<name>opensearch.internal</name>
+								<placement>a</placement>
+								<head>OpenSearch internal:</head>
+							</tag>
+							<tag>
+								<name>opensearch.experimental</name>
+								<placement>a</placement>
+								<head>OpenSearch experimental:</head>
+							</tag>
+						</tags>
+					</configuration>
+				</plugin>
+			</plugins>
+		</pluginManagement>
 		<plugins>
 			<plugin>
 				<artifactId>maven-compiler-plugin</artifactId>
@@ -160,12 +191,6 @@
 					</plugin>
 					<plugin>
 						<artifactId>maven-javadoc-plugin</artifactId>
-						<version>3.12.0</version>
-						<configuration>
-							<encoding>UTF-8</encoding>
-							<docencoding>UTF-8</docencoding>
-							<charset>UTF-8</charset>
-						</configuration>
 						<executions>
 							<execution>
 								<id>attach-javadocs</id>

src/main/java/org/codelibs/fesen/opensearch/ExceptionsHelper.java

@@ -243,7 +243,7 @@ public static <T extends Throwable> T useOrSuppress(T first, T second) {
 
     /**
      * Looks at the given Throwable and its cause(s) and returns the first Throwable that is of one of the given classes or {@code null}
-     * if no matching Throwable is found. Unlike {@link #unwrapCorruption} this method does only check the given Throwable and its causes
+     * if no matching Throwable is found. Unlike {@code #unwrapCorruption} this method does only check the given Throwable and its causes
      * but does not look at any suppressed exceptions.
      * @param t Throwable
      * @param clazzes Classes to look for

src/main/java/org/codelibs/fesen/opensearch/action/CompositeIndicesRequest.java

@@ -35,8 +35,8 @@
 /**
  * Marker interface that needs to be implemented by all {@link org.codelibs.fesen.opensearch.action.ActionRequest} subclasses that are composed of
  * multiple sub-requests which relate to one or more indices.  A composite request is executed by its own transport action class
- * (e.g. {@link org.codelibs.fesen.opensearch.action.search.TransportMultiSearchAction}), which goes through all sub-requests and delegates their
- * execution to the appropriate transport action (e.g. {@link org.codelibs.fesen.opensearch.action.search.TransportSearchAction}) for each single item.
+ * (e.g. {@code org.codelibs.fesen.opensearch.action.search.TransportMultiSearchAction}), which goes through all sub-requests and delegates their
+ * execution to the appropriate transport action (e.g. {@code org.codelibs.fesen.opensearch.action.search.TransportSearchAction}) for each single item.
  *
  * @opensearch.internal
  */

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/alias/IndicesAliasesRequest.java

@@ -150,21 +150,21 @@ public static Type fromValue(byte value) {
         }
 
         /**
-         * Build a new {@link AliasAction} to add aliases.
+         * Build a new {@code AliasAction} to add aliases.
          */
         public static AliasActions add() {
             return new AliasActions(AliasActions.Type.ADD);
         }
 
         /**
-         * Build a new {@link AliasAction} to remove aliases.
+         * Build a new {@code AliasAction} to remove aliases.
          */
         public static AliasActions remove() {
             return new AliasActions(AliasActions.Type.REMOVE);
         }
 
         /**
-         * Build a new {@link AliasAction} to remove an index.
+         * Build a new {@code AliasAction} to remove an index.
          */
         public static AliasActions removeIndex() {
             return new AliasActions(AliasActions.Type.REMOVE_INDEX);
@@ -225,7 +225,7 @@ private static ObjectParser<AliasActions, Void> parser(String name, Supplier<Ali
         );
 
         /**
-         * Parser for any one {@link AliasAction}.
+         * Parser for any one {@code AliasAction}.
          */
         public static final ConstructingObjectParser<AliasActions, Void> PARSER = new ConstructingObjectParser<>("alias_action", a -> {
             // Take the first action and complain if there are more than one actions

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/create/CreateIndexRequest.java

@@ -75,12 +75,11 @@
 import static org.codelibs.fesen.opensearch.common.settings.Settings.writeSettingsToStream;
 
 /**
- * A request to create an index. Best created with {@link Requests#createIndexRequest(String)}.
+ * A request to create an index. Best created with {@code Requests#createIndexRequest(String)}.
  * <p>
  * The index created can optionally be created with {@link #settings(org.codelibs.fesen.opensearch.common.settings.Settings)}.
  *
  * @see IndicesAdminClient#create(CreateIndexRequest)
- * @see Requests#createIndexRequest(String)
  * @see CreateIndexResponse
  *
  * @opensearch.api

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/delete/DeleteIndexRequest.java

@@ -46,7 +46,7 @@
 import static org.codelibs.fesen.opensearch.action.ValidateActions.addValidationError;
 
 /**
- * A request to delete an index. Best created with {@link Requests#deleteIndexRequest(String)}.
+ * A request to delete an index. Best created with {@code Requests#deleteIndexRequest(String)}.
  *
  * @opensearch.api
  */

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/flush/FlushRequest.java

@@ -48,9 +48,8 @@
  * by flushing data to the index storage and clearing the internal transaction log. By default, OpenSearch uses
  * memory heuristics in order to automatically trigger flush operations as required in order to clear memory.
  * <p>
- * Best created with {@link Requests#flushRequest(String...)}.
+ * Best created with {@code Requests#flushRequest(String...)}.
  *
- * @see Requests#flushRequest(String...)
  * @see IndicesAdminClient#flush(FlushRequest)
  * @see FlushResponse
  *

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/forcemerge/ForceMergeRequest.java

@@ -47,11 +47,10 @@
  * A request to force merging the segments of one or more indices. In order to
  * run a merge on all the indices, pass an empty array or {@code null} for the
  * indices.
- * {@link #maxNumSegments(int)} allows to control the number of segments
+ * {@code #maxNumSegments(int)} allows to control the number of segments
  * to force merge down to. Defaults to simply checking if a merge needs
  * to execute, and if so, executes it
  *
- * @see Requests#forceMergeRequest(String...)
  * @see IndicesAdminClient#forceMerge(ForceMergeRequest)
  * @see ForceMergeResponse
  *

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/forcemerge/ForceMergeRequestBuilder.java

@@ -39,7 +39,7 @@
 /**
  * A request to force merge one or more indices. In order to force merge all
  * indices, pass an empty array or {@code null} for the indices.
- * {@link #setMaxNumSegments(int)} allows to control the number of segments to force
+ * {@code #setMaxNumSegments(int)} allows to control the number of segments to force
  * merge down to. By default, will cause the force merge process to merge down
  * to half the configured number of segments.
  *

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/mapping/put/PutMappingRequest.java

@@ -68,12 +68,11 @@
 
 /**
  * Puts mapping definition into one or more indices. Best created with
- * {@link Requests#putMappingRequest(String...)}.
+ * {@code Requests#putMappingRequest(String...)}.
  * <p>
  * If the mappings already exists, the new mappings will be merged with the new one. If there are elements
  * that can't be merged are detected, the request will be rejected.
  *
- * @see Requests#putMappingRequest(String...)
  * @see IndicesAdminClient#putMapping(PutMappingRequest)
  * @see AcknowledgedResponse
  *

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/refresh/RefreshRequest.java

@@ -44,7 +44,6 @@
  * capabilities depends on the index engine used. For example, the internal one requires refresh to be called, but by
  * default a refresh is scheduled periodically.
  *
- * @see Requests#refreshRequest(String...)
  * @see IndicesAdminClient#refresh(RefreshRequest)
  * @see RefreshResponse
  *

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/settings/get/GetSettingsResponse.java

@@ -76,7 +76,7 @@ public GetSettingsResponse(StreamInput in) throws IOException {
     /**
      * Returns a map of index name to {@link Settings} object.  The returned {@link Settings}
      * objects contain only those settings explicitly set on a given index.  Any settings
-     * taking effect as defaults must be accessed via {@link #getIndexToDefaultSettings()}.
+     * taking effect as defaults must be accessed via {@code #getIndexToDefaultSettings()}.
      */
     public Map<String, Settings> getIndexToSettings() {
         return indexToSettings;

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/shards/IndicesShardStoresAction.java

@@ -35,7 +35,7 @@
 import org.codelibs.fesen.opensearch.action.ActionType;
 
 /**
- * ActionType for {@link TransportIndicesShardStoresAction}
+ * ActionType for {@code TransportIndicesShardStoresAction}
  *
  * Exposes shard store information for requested indices.
  * Shard store information reports which nodes hold shard copies, how recent they are

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/stats/IndicesStatsRequest.java

@@ -44,7 +44,7 @@
  * <p>
  * By default, all statistics are enabled.
  * <p>
- * All the stats to be returned can be cleared using {@link #clear()}, at which point, specific
+ * All the stats to be returned can be cleared using {@code #clear()}, at which point, specific
  * stats can be enabled.
  *
  * @opensearch.api

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/stats/IndicesStatsRequestBuilder.java

@@ -40,10 +40,10 @@
 /**
  * A request to get indices level stats. Allow to enable different stats to be returned.
  * <p>
- * By default, the {@link #setDocs(boolean)}, {@link #setStore(boolean)}, {@link #setIndexing(boolean)}
+ * By default, the {@code #setDocs(boolean)}, {@code #setStore(boolean)}, {@code #setIndexing(boolean)}
  * are enabled. Other stats can be enabled as well.
  * <p>
- * All the stats to be returned can be cleared using {@link #clear()}, at which point, specific
+ * All the stats to be returned can be cleared using {@code #clear()}, at which point, specific
  * stats can be enabled.
  *
  * @opensearch.api

src/main/java/org/codelibs/fesen/opensearch/action/admin/indices/upgrade/post/UpgradeRequest.java

@@ -43,7 +43,6 @@
 /**
  * A request to upgrade one or more indices. In order to update all indices, pass an empty array or
  * {@code null} for the indices.
- * @see Requests#upgradeRequest(String...)
  * @see IndicesAdminClient#upgrade(UpgradeRequest)
  * @see UpgradeResponse
  *

src/main/java/org/codelibs/fesen/opensearch/action/bulk/BulkRequest.java

@@ -202,9 +202,9 @@ public RefreshPolicy getRefreshPolicy() {
      * <p>
      * - {@link BulkRequest#add(IndexRequest)}
      * - {@link BulkRequest#add(UpdateRequest)}
-     * - {@link BulkRequest#add(DocWriteRequest)}
-     * - {@link BulkRequest#add(DocWriteRequest[])} )}
-     * - {@link BulkRequest#add(Iterable)}
+     * - {@code BulkRequest#add(DocWriteRequest)}
+     * - {@code BulkRequest#add(DocWriteRequest[])} )}
+     * - {@code BulkRequest#add(Iterable)}
      * @param globalPipeline the global default setting
      * @return Bulk request with global setting set
      */
@@ -219,9 +219,9 @@ public final BulkRequest pipeline(String globalPipeline) {
      * <p>
       - {@link BulkRequest#add(IndexRequest)}
       - {@link BulkRequest#add(UpdateRequest)}
-      - {@link BulkRequest#add(DocWriteRequest)}
-      - {@link BulkRequest#add(DocWriteRequest[])} )}
-      - {@link BulkRequest#add(Iterable)}
+      - {@code BulkRequest#add(DocWriteRequest)}
+      - {@code BulkRequest#add(DocWriteRequest[])} )}
+      - {@code BulkRequest#add(Iterable)}
      * @param globalRouting the global default setting
      * @return Bulk request with global setting set
      */
@@ -252,9 +252,9 @@ public Boolean requireAlias() {
      * <p>
      * - {@link BulkRequest#add(IndexRequest)}
      * - {@link BulkRequest#add(UpdateRequest)}
-     * - {@link BulkRequest#add(DocWriteRequest)}
-     * - {@link BulkRequest#add(DocWriteRequest[])} )}
-     * - {@link BulkRequest#add(Iterable)}
+     * - {@code BulkRequest#add(DocWriteRequest)}
+     * - {@code BulkRequest#add(DocWriteRequest[])} )}
+     * - {@code BulkRequest#add(Iterable)}
      * @param globalRequireAlias the global default setting
      * @return Bulk request with global setting set
      */

src/main/java/org/codelibs/fesen/opensearch/action/delete/DeleteRequest.java

@@ -57,14 +57,13 @@
 
 /**
  * A request to delete a document from an index based on its type and id. Best created using
- * {@link Requests#deleteRequest(String)}.
+ * {@code Requests#deleteRequest(String)}.
  * <p>
  * The operation requires the {@link #index()}, and {@link #id(String)} to
  * be set.
  *
  * @see DeleteResponse
  * @see Client#delete(DeleteRequest)
- * @see Requests#deleteRequest(String)
  *
  * @opensearch.api
  */

src/main/java/org/codelibs/fesen/opensearch/action/fieldcaps/FieldCapabilitiesIndexResponse.java

@@ -42,7 +42,7 @@
 import java.util.Objects;
 
 /**
- * Response for {@link TransportFieldCapabilitiesIndexAction}.
+ * Response for {@code TransportFieldCapabilitiesIndexAction}.
  *
  * @opensearch.internal
  */

src/main/java/org/codelibs/fesen/opensearch/action/get/GetRequest.java

@@ -55,13 +55,12 @@
 
 /**
  * A request to get a document (its source) from an index based on its id. Best created using
- * {@link Requests#getRequest(String)}.
+ * {@code Requests#getRequest(String)}.
  * <p>
  * The operation requires the {@link #index()}} and {@link #id(String)}
  * to be set.
  *
  * @see GetResponse
- * @see Requests#getRequest(String)
  * @see Client#get(GetRequest)
  *
  * @opensearch.api

src/main/java/org/codelibs/fesen/opensearch/action/index/IndexRequest.java

@@ -75,19 +75,18 @@
 
 /**
  * Index request to index a typed JSON document into a specific index and make it searchable. Best
- * created using {@link Requests#indexRequest(String)}.
+ * created using {@code Requests#indexRequest(String)}.
  * <p>
  * The index requires the {@link #index()}, {@link #id(String)} and
- * {@link #source(byte[], MediaType)} to be set.
+ * {@code #source(byte[], MediaType)} to be set.
  * <p>
- * The source (content to index) can be set in its bytes form using ({@link #source(byte[], MediaType)}),
+ * The source (content to index) can be set in its bytes form using ({@code #source(byte[], MediaType)}),
  * its string form ({@link #source(String, MediaType)}) or using a {@link XContentBuilder}
  * ({@link #source(XContentBuilder)}).
  * <p>
  * If the {@link #id(String)} is not set, it will be automatically generated.
  *
  * @see IndexResponse
- * @see Requests#indexRequest(String)
  * @see Client#index(IndexRequest)
  *
  * @opensearch.api
@@ -128,7 +127,7 @@ public class IndexRequest extends ReplicatedWriteRequest<IndexRequest> implement
     private boolean requireAlias;
 
     /**
-     * Value for {@link #getAutoGeneratedTimestamp()} if the document has an external
+     * Value for {@code #getAutoGeneratedTimestamp()} if the document has an external
      * provided ID.
      */
     public static final long UNSET_AUTO_GENERATED_TIMESTAMP = -1L;
@@ -183,7 +182,7 @@ public IndexRequest() {
 
     /**
      * Constructs a new index request against the specific index. The
-     * {@link #source(byte[], MediaType)} must be set.
+     * {@code #source(byte[], MediaType)} must be set.
      */
     public IndexRequest(String index) {
         super(NO_SHARD_ID);
@@ -324,7 +323,7 @@ public BytesReference source() {
     }
 
     /**
-     * Index the Map in {@link Requests#INDEX_CONTENT_TYPE} format
+     * Index the Map in {@code Requests#INDEX_CONTENT_TYPE} format
      *
      * @param source The map to index
      */
@@ -351,7 +350,7 @@ public IndexRequest source(Map<String, ?> source, MediaType contentType) throws
      * Sets the document source to index.
      * <p>
      * Note, its preferable to either set it using {@link #source(XContentBuilder)}
-     * or using the {@link #source(byte[], MediaType)}.
+     * or using the {@code #source(byte[], MediaType)}.
      */
     public IndexRequest source(String source, MediaType mediaType) {
         return source(new BytesArray(source), mediaType);
@@ -365,7 +364,7 @@ public IndexRequest source(XContentBuilder sourceBuilder) {
     }
 
     /**
-     * Sets the content source to index using the default content type ({@link Requests#INDEX_CONTENT_TYPE})
+     * Sets the content source to index using the default content type ({@code Requests#INDEX_CONTENT_TYPE})
      * <p>
      * <b>Note: the number of objects passed to this method must be an even
      * number. Also the first argument in each pair (the field name) must have a

src/main/java/org/codelibs/fesen/opensearch/action/index/IndexRequestBuilder.java

@@ -96,7 +96,7 @@ public IndexRequestBuilder setSource(Map<String, ?> source, MediaType contentTyp
      * Sets the document source to index.
      * <p>
      * Note, its preferable to either set it using {@link #setSource(XContentBuilder)}
-     * or using the {@link #setSource(byte[], MediaType)}.
+     * or using the {@code #setSource(byte[], MediaType)}.
      */
     public IndexRequestBuilder setSource(String source, MediaType mediaType) {
         request.source(source, mediaType);