New javadoc and improvement of existing javadoc (#10064) (#10563)

* Fixing javadoc error
fixing javadoc error and warning
javadoc for org.opensearch.core.indices.breaker
javadoc for org.opensearch.core.index.shard.ShardId
javadoc for org.opensearch.core.index.Index
fixing a mishap in formatting rule
fixing javadoc of org.opensearch.cli.Terminal



* removing unsupported @ImplNote



* Update libs/common/src/main/java/org/opensearch/common/collect/Iterators.java




* Update libs/compress/src/main/java/org/opensearch/compress/ZstdCompressor.java




* Apply suggestions from code review




* Apply suggestions from code review




* Apply suggestions from code review




* Apply suggestions from code review




* Update CollectionUtils.java



* fixing javadoc warnings



* remove useless p tag



* removing a p tag




* proper capitalization




* improvements of existing javadocs



* javadoc improvement



* javadoc improvement



* Fix formatting error after merge conflict resolution in a javadoc



* "code" tag ignore carriage return & "p", switching to a "pre" tag



* fixing an overzealous precommit check error.



* Update distribution/tools/launchers/src/main/java/org/opensearch/tools/launchers/SystemJvmOptions.java




* Update server/src/internalClusterTest/java/org/opensearch/search/sort/GeoDistanceSortBuilderIT.java




* Update server/src/main/java/org/opensearch/action/admin/cluster/repositories/get/GetRepositoriesRequest.java




* Update server/src/main/java/org/opensearch/action/admin/cluster/snapshots/create/CreateSnapshotRequest.java




* Update server/src/main/java/org/opensearch/action/admin/indices/replication/SegmentReplicationStatsRequest.java




* Update server/src/main/java/org/opensearch/cluster/RestoreInProgress.java




* Update test/framework/src/main/java/org/opensearch/test/AbstractDiffableWireSerializationTestCase.java




* Update test/framework/src/main/java/org/opensearch/test/AbstractDiffableSerializationTestCase.java




* further improvement of javadoc after review & suggestions



* fixing unreferenced @link in javadoc (precommit error)



* removing p tag from internal comment



* reverting javadoc tag in licence header



* Update server/src/main/java/org/opensearch/search/aggregations/metrics/AbstractPercentilesAggregationBuilder.java




* conflict resolution



---------



(cherry picked from commit c0852f8)

Signed-off-by: Laurent Laborde <[email protected]>
Signed-off-by: Andriy Redko <[email protected]>
Co-authored-by: Laurent Laborde <[email protected]>

buildSrc/reaper/src/main/java/org/opensearch/gradle/reaper/Reaper.java

@@ -45,17 +45,16 @@
 
 /**
  * A standalone process that will reap external services after a build dies.
- *
  * <h2>Input</h2>
  * Since how to reap a given service is platform and service dependent, this tool
  * operates on system commands to execute. It takes a single argument, a directory
  * that will contain files with reaping commands. Each line in each file will be
  * executed with {@link Runtime#exec(String)}.
- *
+ * <p>
  * The main method will wait indefinitely on the parent process (Gradle) by
  * reading from stdin. When Gradle shuts down, whether normally or abruptly, the
  * pipe will be broken and read will return.
- *
+ * <p>
  * The reaper will then iterate over the files in the configured directory,
  * and execute the given commands. If any commands fail, a failure message is
  * written to stderr. Otherwise, the input file will be deleted. If no inputs

buildSrc/src/main/java/org/opensearch/gradle/BwcVersions.java

@@ -52,15 +52,15 @@
 
 /**
  * A container for opensearch supported version information used in BWC testing.
- *
+ * <p>
  * Parse the Java source file containing the versions declarations and use the known rules to figure out which are all
  * the version the current one is wire and index compatible with.
  * On top of this, figure out which of these are unreleased and provide the branch they can be built from.
- *
+ * <p>
  * Note that in this context, currentVersion is the unreleased version this build operates on.
  * At any point in time there will surely be four such unreleased versions being worked on,
  * thus currentVersion will be one of these.
- *
+ * <p>
  * Considering:
  * <dl>
  *     <dt>M, M &gt; 0</dt>
@@ -84,7 +84,7 @@
  * Each build is only concerned with versions before it, as those are the ones that need to be tested
  * for backwards compatibility. We never look forward, and don't add forward facing version number to branches of previous
  * version.
- *
+ * <p>
  * Each branch has a current version, and expected compatible versions are parsed from the server code's Version` class.
  * We can reliably figure out which the unreleased versions are due to the convention of always adding the next unreleased
  * version number to server in all branches when a version is released.

buildSrc/src/main/java/org/opensearch/gradle/LoggingOutputStream.java

@@ -38,7 +38,7 @@
 
 /**
  * Writes data passed to this stream as log messages.
- *
+ * <p>
  * The stream will be flushed whenever a newline is detected.
  * Allows setting an optional prefix before each line of output.
  */

buildSrc/src/main/java/org/opensearch/gradle/precommit/TestingConventionRule.java

@@ -40,7 +40,7 @@
 
 /**
  * Represent rules for tests enforced by the @{link {@link TestingConventionsTasks}}
- *
+ * <p>
  * Rules are identified by name, tests must have this name as a suffix and implement one of the base classes
  * and be part of all the specified tasks.
  */

buildSrc/src/main/java/org/opensearch/gradle/tar/SymbolicLinkPreservingTar.java

@@ -61,7 +61,7 @@
 
 /**
  * A custom archive task that assembles a tar archive that preserves symbolic links.
- *
+ * <p>
  * This task is necessary because the built-in task {@link org.gradle.api.tasks.bundling.Tar} does not preserve symbolic links.
  */
 public class SymbolicLinkPreservingTar extends Tar {

buildSrc/src/main/java/org/opensearch/gradle/test/rest/RestResourcesPlugin.java

@@ -65,7 +65,7 @@
  * <strong>Rest YAML tests :</strong> <br>
  * When the {@link RestResourcesPlugin} has been applied the {@link CopyRestTestsTask} will copy the Rest YAML tests if explicitly
  * configured with `includeCore` through the `restResources.restTests` extension.
- *
+ * <p>
  * Additionally you can specify which sourceSetName resources should be copied to. The default is the yamlRestTest source set.
  * @see CopyRestApiTask
  * @see CopyRestTestsTask

buildSrc/src/main/java/org/opensearch/gradle/vagrant/VagrantMachine.java

@@ -53,7 +53,7 @@
 
 /**
  * An helper to manage a vagrant box.
- *
+ * <p>
  * This is created alongside a {@link VagrantExtension} for a project to manage starting and
  * stopping a single vagrant box.
  */
@@ -185,7 +185,7 @@ public void setArgs(String... args) {
 
         /**
          * A function to translate output from the vagrant command execution to the progress line.
-         *
+         * <p>
          * The function takes the current line of output from vagrant, and returns a new
          * progress line, or {@code null} if there is no update.
          */

buildSrc/src/main/java/org/opensearch/gradle/vagrant/VagrantShellTask.java

@@ -47,7 +47,7 @@
 
 /**
  * A shell script to run within a vagrant VM.
- *
+ * <p>
  * The script is run as root within the VM.
  */
 public abstract class VagrantShellTask extends DefaultTask {

buildSrc/src/test/java/org/opensearch/gradle/pluginzip/PublishTests.java

@@ -58,7 +58,7 @@ public void tearDown() {
      * This test is used to verify that adding the 'opensearch.pluginzip' to the project
      * adds some other transitive plugins and tasks under the hood. This is basically
      * a behavioral test of the {@link Publish#apply(Project)} method.
-     *
+     * <p>
      * This is equivalent of having a build.gradle script with just the following section:
      * <pre>
      *     plugins {
@@ -233,7 +233,7 @@ public void useDefaultValues() throws IOException, URISyntaxException, XmlPullPa
         GradleRunner runner = prepareGradleRunnerFromTemplate("useDefaultValues.gradle", "build", ZIP_PUBLISH_TASK);
         BuildResult result = runner.build();
 
-        /** Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
+        /* Check if build and ZIP_PUBLISH_TASK tasks have run well */
         assertEquals(SUCCESS, result.task(":" + "build").getOutcome());
         assertEquals(SUCCESS, result.task(":" + ZIP_PUBLISH_TASK).getOutcome());
 
@@ -308,7 +308,7 @@ public void allProjectsGroup() throws IOException, URISyntaxException, XmlPullPa
         GradleRunner runner = prepareGradleRunnerFromTemplate("allProjectsGroup.gradle", "build", ZIP_PUBLISH_TASK);
         BuildResult result = runner.build();
 
-        /** Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
+        /* Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
         assertEquals(SUCCESS, result.task(":" + "build").getOutcome());
         assertEquals(SUCCESS, result.task(":" + ZIP_PUBLISH_TASK).getOutcome());
 
@@ -343,7 +343,7 @@ public void groupPriorityLevel() throws IOException, URISyntaxException, XmlPull
         GradleRunner runner = prepareGradleRunnerFromTemplate("groupPriorityLevel.gradle", "build", ZIP_PUBLISH_TASK);
         BuildResult result = runner.build();
 
-        /** Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
+        /* Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
         assertEquals(SUCCESS, result.task(":" + "build").getOutcome());
         assertEquals(SUCCESS, result.task(":" + ZIP_PUBLISH_TASK).getOutcome());
 
@@ -379,7 +379,7 @@ public void missingPOMEntity() throws IOException, URISyntaxException, XmlPullPa
         GradleRunner runner = prepareGradleRunnerFromTemplate("missingPOMEntity.gradle", "build", ZIP_PUBLISH_TASK);
         BuildResult result = runner.build();
 
-        /** Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
+        /* Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
         assertEquals(SUCCESS, result.task(":" + "build").getOutcome());
         assertEquals(SUCCESS, result.task(":" + ZIP_PUBLISH_TASK).getOutcome());
 
@@ -426,7 +426,7 @@ public void customizedGroupValue() throws IOException, URISyntaxException, XmlPu
         GradleRunner runner = prepareGradleRunnerFromTemplate("customizedGroupValue.gradle", "build", ZIP_PUBLISH_TASK);
         BuildResult result = runner.build();
 
-        /** Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
+        /* Check if build and {@value ZIP_PUBLISH_TASK} tasks have run well */
         assertEquals(SUCCESS, result.task(":" + "build").getOutcome());
         assertEquals(SUCCESS, result.task(":" + ZIP_PUBLISH_TASK).getOutcome());
 

buildSrc/src/testFixtures/java/org/opensearch/gradle/test/GradleThreadsFilter.java

@@ -36,7 +36,7 @@
 
 /**
  * Filter out threads controlled by gradle that may be created during unit tests.
- *
+ * <p>
  * Currently this includes pooled threads for Exec as well as file system event watcher threads.
  */
 public class GradleThreadsFilter implements ThreadFilter {

buildSrc/src/testFixtures/java/org/opensearch/gradle/test/JUnit3MethodProvider.java

@@ -43,7 +43,7 @@
 
 /**
  * Backwards compatible test* method provider (public, non-static).
- *
+ * <p>
  * copy of org.apache.lucene.util.LuceneJUnit3MethodProvider to avoid a dependency between build and test fw.
  */
 public final class JUnit3MethodProvider implements TestMethodProvider {

client/benchmark/src/main/java/org/opensearch/client/benchmark/metrics/SampleRecorder.java

@@ -37,7 +37,7 @@
 
 /**
  * Stores measurement samples.
- *
+ * <p>
  * This class is NOT threadsafe.
  */
 public final class SampleRecorder {

client/rest-high-level/src/main/java/org/opensearch/client/ClusterClient.java

@@ -170,8 +170,8 @@ public ClusterHealthResponse health(ClusterHealthRequest healthRequest, RequestO
 
     /**
      * Asynchronously get cluster health using the Cluster Health API.
-     *
      * If timeout occurred, {@link ClusterHealthResponse} will have isTimedOut() == true and status() == RestStatus.REQUEST_TIMEOUT
+     *
      * @param healthRequest the request
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
      * @param listener the listener to be notified upon request completion

client/rest-high-level/src/main/java/org/opensearch/client/RequestConverters.java

@@ -451,9 +451,9 @@ static void addSearchRequestParams(Params params, SearchRequest searchRequest) {
             params.withIndicesOptions(searchRequest.indicesOptions());
         }
         params.withSearchType(searchRequest.searchType().name().toLowerCase(Locale.ROOT));
-        /**
-         * Merging search responses as part of CCS flow to reduce roundtrips is not supported for point in time -
-         * refer to org.opensearch.action.search.SearchResponseMerger
+        /*
+          Merging search responses as part of CCS flow to reduce roundtrips is not supported for point in time -
+          refer to org.opensearch.action.search.SearchResponseMerger
          */
         if (searchRequest.pointInTimeBuilder() != null) {
             params.putParam("ccs_minimize_roundtrips", "false");

client/rest-high-level/src/main/java/org/opensearch/client/TimedRequest.java

@@ -37,7 +37,7 @@
 
 /**
  * A base request for any requests that supply timeouts.
- *
+ * <p>
  * Please note, any requests that use a ackTimeout should set timeout as they
  * represent the same backing field on the server.
  */

client/rest-high-level/src/main/java/org/opensearch/client/indices/CreateIndexRequest.java

@@ -156,7 +156,7 @@ public MediaType mappingsMediaType() {
 
     /**
      * Adds mapping that will be added when the index gets created.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      *
      * @param source The mapping source
@@ -168,7 +168,7 @@ public CreateIndexRequest mapping(String source, MediaType mediaType) {
 
     /**
      * Adds mapping that will be added when the index gets created.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      *
      * @param source The mapping source
@@ -179,7 +179,7 @@ public CreateIndexRequest mapping(XContentBuilder source) {
 
     /**
      * Adds mapping that will be added when the index gets created.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      *
      * @param source The mapping source
@@ -196,7 +196,7 @@ public CreateIndexRequest mapping(Map<String, ?> source) {
 
     /**
      * Adds mapping that will be added when the index gets created.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      *
      * @param source The mapping source
@@ -282,7 +282,7 @@ public CreateIndexRequest aliases(Collection<Alias> aliases) {
 
     /**
      * Sets the settings and mappings as a single source.
-     *
+     * <p>
      * Note that the mapping definition should *not* be nested under a type name.
      */
     public CreateIndexRequest source(String source, MediaType mediaType) {
@@ -291,7 +291,7 @@ public CreateIndexRequest source(String source, MediaType mediaType) {
 
     /**
      * Sets the settings and mappings as a single source.
-     *
+     * <p>
      * Note that the mapping definition should *not* be nested under a type name.
      */
     public CreateIndexRequest source(XContentBuilder source) {
@@ -300,7 +300,7 @@ public CreateIndexRequest source(XContentBuilder source) {
 
     /**
      * Sets the settings and mappings as a single source.
-     *
+     * <p>
      * Note that the mapping definition should *not* be nested under a type name.
      */
     public CreateIndexRequest source(BytesReference source, MediaType mediaType) {
@@ -311,7 +311,7 @@ public CreateIndexRequest source(BytesReference source, MediaType mediaType) {
 
     /**
      * Sets the settings and mappings as a single source.
-     *
+     * <p>
      * Note that the mapping definition should *not* be nested under a type name.
      */
     @SuppressWarnings("unchecked")

client/rest-high-level/src/main/java/org/opensearch/client/indices/PutMappingRequest.java

@@ -105,7 +105,7 @@ public MediaType mediaType() {
 
     /**
      * The mapping source definition.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      */
     public PutMappingRequest source(Map<String, ?> mappingSource) {
@@ -120,7 +120,7 @@ public PutMappingRequest source(Map<String, ?> mappingSource) {
 
     /**
      * The mapping source definition.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      */
     public PutMappingRequest source(String mappingSource, MediaType mediaType) {
@@ -131,7 +131,7 @@ public PutMappingRequest source(String mappingSource, MediaType mediaType) {
 
     /**
      * The mapping source definition.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      */
     public PutMappingRequest source(XContentBuilder builder) {
@@ -142,7 +142,7 @@ public PutMappingRequest source(XContentBuilder builder) {
 
     /**
      * The mapping source definition.
-     *
+     * <p>
      * Note that the definition should *not* be nested under a type name.
      */
     public PutMappingRequest source(BytesReference source, MediaType mediaType) {

client/rest-high-level/src/main/java/org/opensearch/client/tasks/TaskGroup.java

@@ -38,7 +38,6 @@
 
 /**
  * Client side counterpart of server side version.
- *
  * {@link org.opensearch.action.admin.cluster.node.tasks.list.TaskGroup}
  */
 public class TaskGroup {

client/rest-high-level/src/test/java/org/opensearch/client/AbstractRequestTestCase.java

@@ -44,7 +44,7 @@
 
 /**
  * Base class for HLRC request parsing tests.
- *
+ * <p>
  * This case class facilitates generating client side request test instances and
  * verifies that they are correctly parsed into server side request instances.
  *

client/rest-high-level/src/test/java/org/opensearch/client/AbstractResponseTestCase.java

@@ -44,7 +44,7 @@
 
 /**
  * Base class for HLRC response parsing tests.
- *
+ * <p>
  * This case class facilitates generating server side response test instances and
  * verifies that they are correctly parsed into HLRC response instances.
  *

client/rest-high-level/src/test/java/org/opensearch/client/BulkProcessorRetryIT.java

@@ -180,7 +180,7 @@ private static MultiGetRequest indexDocs(BulkProcessor processor, int numDocs) {
     /**
      * Internal helper class to correlate backoff states with bulk responses. This is needed to check whether we maxed out the number
      * of retries but still got rejected (which is perfectly fine and can also happen from time to time under heavy load).
-     *
+     * <p>
      * This implementation relies on an implementation detail in Retry, namely that the bulk listener is notified on the same thread
      * as the last call to the backoff policy's iterator. The advantage is that this is non-invasive to the rest of the production code.
      */

client/rest-high-level/src/test/java/org/opensearch/client/documentation/IndicesClientDocumentationIT.java

@@ -137,15 +137,15 @@
  * You need to wrap your code between two tags like:
  * // tag::example
  * // end::example
- *
+ * <p>
  * Where example is your tag name.
- *
+ * <p>
  * Then in the documentation, you can extract what is between tag and end tags with
  * ["source","java",subs="attributes,callouts,macros"]
  * --------------------------------------------------
  * include-tagged::{doc-tests}/IndicesClientDocumentationIT.java[example]
  * --------------------------------------------------
- *
+ * <p>
  * The column width of the code block is 84. If the code contains a line longer
  * than 84, the line will be cut and a horizontal scroll bar will be displayed.
  * (the code indentation of the tag is not included in the width)