New javadoc and improvement of existing javadoc (#10064)

* 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

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* removing unsupported @ImplNote

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Apply suggestions from code review

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Update CollectionUtils.java

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* fixing javadoc warnings

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* remove useless p tag

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* removing a p tag

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* proper capitalization

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* improvements of existing javadocs

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* javadoc improvement

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* javadoc improvement

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* Fix formatting error after merge conflict resolution in a javadoc

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* fixing an overzealous precommit check error.

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* further improvement of javadoc after review & suggestions

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* fixing unreferenced @link in javadoc (precommit error)

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* removing p tag from internal comment

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* reverting javadoc tag in licence header

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

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

Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

* conflict resolution

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>

---------

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>
Co-authored-by: Andriy Redko <drreta@gmail.com>

Author: ker2x

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 {
@@ -202,7 +202,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());
 
@@ -277,7 +277,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());
 
@@ -312,7 +312,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());
 
@@ -348,7 +348,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());
 
@@ -395,7 +395,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 {