Fixing javadoc error (opensearch-project#9976)

* 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>

---------

Signed-off-by: Laurent Laborde <kerdezixe@gmail.com>
Co-authored-by: Andriy Redko <drreta@gmail.com>
Signed-off-by: Ivan Brusic <ivan.brusic@flocksafety.com>

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

@@ -41,6 +41,15 @@
  * @opensearch.internal
  */
 public class Iterators {
+
+    /**
+     * Concat iterators
+     *
+     * @param iterators the iterators to concat
+     * @param <T> the type of iterator
+     * @return a new {@link ConcatenatedIterator}
+     * @throws NullPointerException if iterators is null
+     */
     public static <T> Iterator<T> concat(Iterator<? extends T>... iterators) {
         if (iterators == null) {
             throw new NullPointerException("iterators");
@@ -71,6 +80,11 @@ static class ConcatenatedIterator<T> implements Iterator<T> {
             this.iterators = iterators;
         }
 
+        /**
+         * Returns {@code true} if the iteration has more elements. (In other words, returns {@code true} if {@link #next} would return an
+         * element rather than throwing an exception.)
+         * @return {@code true} if the iteration has more elements
+         */
         @Override
         public boolean hasNext() {
             boolean hasNext = false;
@@ -81,6 +95,11 @@ public boolean hasNext() {
             return hasNext;
         }
 
+        /**
+         * Returns the next element in the iteration.
+         * @return the next element in the iteration
+         * @throws NoSuchElementException if the iteration has no more elements
+         */
         @Override
         public T next() {
             if (!hasNext()) {

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

@@ -30,10 +30,13 @@
  * @opensearch.experimental - class methods might change
  */
 public class ZstdCompressor implements Compressor {
-    // An arbitrary header that we use to identify compressed streams
-    // It needs to be different from other compressors and to not be specific
-    // enough so that no stream starting with these bytes could be detected as
-    // a XContent
+
+    /**
+     * An arbitrary header that we use to identify compressed streams
+     * It needs to be different from other compressors and to not be specific
+     * enough so that no stream starting with these bytes could be detected as
+     * a XContent
+     * */
     private static final byte[] HEADER = new byte[] { 'Z', 'S', 'T', 'D', '\0' };
 
     /**
@@ -44,10 +47,20 @@ public class ZstdCompressor implements Compressor {
     @PublicApi(since = "2.10.0")
     public static final String NAME = "ZSTD";
 
+    /**
+     * The compression level for {@link ZstdOutputStreamNoFinalizer}
+     */
     private static final int LEVEL = 3;
 
+    /** The buffer size for {@link BufferedInputStream} and {@link BufferedOutputStream}
+     */
     private static final int BUFFER_SIZE = 4096;
 
+    /**
+     * Compares the given bytes with the {@link ZstdCompressor#HEADER} of a compressed stream
+     * @param bytes the bytes to compare to ({@link ZstdCompressor#HEADER})
+     * @return true if the bytes are the {@link ZstdCompressor#HEADER}, false otherwise
+     */
     @Override
     public boolean isCompressed(BytesReference bytes) {
         if (bytes.length() < HEADER.length) {
@@ -61,11 +74,22 @@ public boolean isCompressed(BytesReference bytes) {
         return true;
     }
 
+    /**
+     * Returns the length of the {@link ZstdCompressor#HEADER}
+     * @return the {@link ZstdCompressor#HEADER} length
+     */
     @Override
     public int headerLength() {
         return HEADER.length;
     }
 
+    /**
+     * Returns a new {@link ZstdInputStreamNoFinalizer} from the given compressed {@link InputStream}
+     * @param in the compressed {@link InputStream}
+     * @return a new {@link ZstdInputStreamNoFinalizer} from the given compressed {@link InputStream}
+     * @throws IOException if an I/O error occurs
+     * @throws IllegalArgumentException if the input stream is not compressed with ZSTD
+     */
     @Override
     public InputStream threadLocalInputStream(InputStream in) throws IOException {
         final byte[] header = in.readNBytes(HEADER.length);
@@ -75,17 +99,36 @@ public InputStream threadLocalInputStream(InputStream in) throws IOException {
         return new ZstdInputStreamNoFinalizer(new BufferedInputStream(in, BUFFER_SIZE), RecyclingBufferPool.INSTANCE);
     }
 
+    /**
+     * Returns a new {@link ZstdOutputStreamNoFinalizer} from the given {@link OutputStream}
+     * @param out the {@link OutputStream}
+     * @return a new {@link ZstdOutputStreamNoFinalizer} from the given {@link OutputStream}
+     * @throws IOException if an I/O error occurs
+     */
     @Override
     public OutputStream threadLocalOutputStream(OutputStream out) throws IOException {
         out.write(HEADER);
         return new ZstdOutputStreamNoFinalizer(new BufferedOutputStream(out, BUFFER_SIZE), RecyclingBufferPool.INSTANCE, LEVEL);
     }
 
+    /**
+     * Always throws an {@link UnsupportedOperationException} as ZSTD compression is supported only for snapshotting
+     * @param bytesReference a reference to the bytes to uncompress
+     * @return always throws an exception
+     * @throws UnsupportedOperationException if the method is called
+     * @throws IOException is never thrown
+     */
     @Override
     public BytesReference uncompress(BytesReference bytesReference) throws IOException {
         throw new UnsupportedOperationException("ZSTD compression is supported only for snapshotting");
     }
 
+    /**
+     * Always throws an {@link UnsupportedOperationException} as ZSTD compression is supported only for snapshotting
+     * @param bytesReference a reference to the bytes to compress
+     * @return always throws an exception
+     * @throws UnsupportedOperationException if the method is called
+     */
     @Override
     public BytesReference compress(BytesReference bytesReference) throws IOException {
         throw new UnsupportedOperationException("ZSTD compression is supported only for snapshotting");

libs/core/src/main/java/org/opensearch/core/common/breaker/CircuitBreaker.java

@@ -71,17 +71,23 @@ public interface CircuitBreaker {
 
     /**
      * The type of breaker
-     *
+     * can be {@link #MEMORY}, {@link #PARENT}, or {@link #NOOP}
      * @opensearch.internal
      */
     enum Type {
-        // A regular or ChildMemoryCircuitBreaker
+        /** A regular or ChildMemoryCircuitBreaker */
         MEMORY,
-        // A special parent-type for the hierarchy breaker service
+        /** A special parent-type for the hierarchy breaker service */
         PARENT,
-        // A breaker where every action is a noop, it never breaks
+        /** A breaker where every action is a noop, it never breaks */
         NOOP;
 
+        /**
+         * Converts string (case-insensitive) to breaker {@link Type}
+         * @param value "noop", "parent", or "memory" (case-insensitive)
+         * @return the breaker {@link Type}
+         * @throws IllegalArgumentException if value is not "noop", "parent", or "memory"
+         */
         public static Type parseValue(String value) {
             switch (value.toLowerCase(Locale.ROOT)) {
                 case "noop":
@@ -98,13 +104,13 @@ public static Type parseValue(String value) {
 
     /**
      * The breaker durability
-     *
+     * can be {@link #TRANSIENT} or {@link #PERMANENT}
      * @opensearch.internal
      */
     enum Durability {
-        // The condition that tripped the circuit breaker fixes itself eventually.
+        /** The condition that tripped the circuit breaker fixes itself eventually. */
         TRANSIENT,
-        // The condition that tripped the circuit breaker requires manual intervention.
+        /** The condition that tripped the circuit breaker requires manual intervention. */
         PERMANENT
     }
 
@@ -120,11 +126,14 @@ enum Durability {
      * @param bytes number of bytes to add
      * @param label string label describing the bytes being added
      * @return the number of "used" bytes for the circuit breaker
+     * @throws CircuitBreakingException if the breaker tripped
      */
     double addEstimateBytesAndMaybeBreak(long bytes, String label) throws CircuitBreakingException;
 
     /**
      * Adjust the circuit breaker without tripping
+     * @param bytes number of bytes to add
+     * @return the number of "used" bytes for the circuit breaker
      */
     long addWithoutBreaking(long bytes);
 
@@ -154,7 +163,10 @@ enum Durability {
     String getName();
 
     /**
-     * @return whether a tripped circuit breaker will reset itself (transient) or requires manual intervention (permanent).
+     * Returns the {@link Durability} of this breaker
+     * @return whether a tripped circuit breaker will
+     * reset itself ({@link Durability#TRANSIENT})
+     * or requires manual intervention ({@link Durability#PERMANENT}).
      */
     Durability getDurability();
 

libs/core/src/main/java/org/opensearch/core/common/breaker/CircuitBreakingException.java

@@ -46,8 +46,11 @@
  */
 public class CircuitBreakingException extends OpenSearchException {
 
+    /** The number of bytes wanted */
     private final long bytesWanted;
+    /** The circuit breaker limit */
     private final long byteLimit;
+    /** The {@link CircuitBreaker.Durability} of the circuit breaker */
     private final CircuitBreaker.Durability durability;
 
     public CircuitBreakingException(StreamInput in) throws IOException {
@@ -88,6 +91,7 @@ public CircuitBreaker.Durability getDurability() {
         return durability;
     }
 
+    /** Always returns {@link RestStatus#TOO_MANY_REQUESTS} */
     @Override
     public RestStatus status() {
         return RestStatus.TOO_MANY_REQUESTS;

libs/core/src/main/java/org/opensearch/core/common/breaker/NoopCircuitBreaker.java

@@ -33,65 +33,120 @@
 package org.opensearch.core.common.breaker;
 
 /**
- * A CircuitBreaker that doesn't increment or adjust, and all operations are
- * basically noops
- *
+ * A {@link CircuitBreaker} that doesn't increment or adjust, and all operations are
+ * basically noops.
+ * It never trips, limit is always -1, always returns 0 for all metrics.
  * @opensearch.internal
  */
 public class NoopCircuitBreaker implements CircuitBreaker {
-    public static final int LIMIT = -1;
 
+    /** The limit of this breaker is always -1 */
+    public static final int LIMIT = -1;
+    /** Name of this breaker */
     private final String name;
 
+    /**
+     * Creates a new NoopCircuitBreaker (that never trip) with the given name
+     * @param name the name of this breaker
+     */
     public NoopCircuitBreaker(String name) {
         this.name = name;
     }
 
+    /**
+     * This is a noop, a noop breaker never trip
+     * @param fieldName name of this noop breaker
+     * @param bytesNeeded bytes needed
+     */
     @Override
     public void circuitBreak(String fieldName, long bytesNeeded) {
         // noop
     }
 
+    /**
+     * This is a noop, always return 0 and never throw/trip
+     * @param bytes number of bytes to add
+     * @param label string label describing the bytes being added
+     * @return always return 0
+     * @throws CircuitBreakingException never thrown
+     */
     @Override
     public double addEstimateBytesAndMaybeBreak(long bytes, String label) throws CircuitBreakingException {
         return 0;
     }
 
+    /**
+     * This is a noop, nothing is added, always return 0
+     * @param bytes number of bytes to add (ignored)
+     * @return always return 0
+     */
     @Override
     public long addWithoutBreaking(long bytes) {
         return 0;
     }
 
+    /**
+     * This is a noop, always return 0
+     * @return always return 0
+     */
     @Override
     public long getUsed() {
         return 0;
     }
 
+    /**
+     * A noop breaker have a constant limit of -1
+     * @return always return -1
+     */
     @Override
     public long getLimit() {
         return LIMIT;
     }
 
+    /**
+     * A noop breaker have no overhead, always return 0
+     * @return always return 0
+     */
     @Override
     public double getOverhead() {
         return 0;
     }
 
+    /**
+     * A noop breaker never trip, always return 0
+     * @return always return 0
+     */
     @Override
     public long getTrippedCount() {
         return 0;
     }
 
+    /**
+     * return the name of this breaker
+     * @return the name of this breaker
+     */
     @Override
     public String getName() {
         return this.name;
     }
 
+    /**
+     * A noop breaker {@link Durability} is always {@link Durability#PERMANENT}
+     * @return always return {@link Durability#PERMANENT }
+     */
     @Override
     public Durability getDurability() {
         return Durability.PERMANENT;
     }
 
+    /**
+     * Limit and overhead are constant for a noop breaker.
+     * this is a noop.
+     * @param limit the desired limit (ignored)
+     * @param overhead the desired overhead (ignored)
+     */
     @Override
-    public void setLimitAndOverhead(long limit, double overhead) {}
+    public void setLimitAndOverhead(long limit, double overhead) {
+        // noop
+    }
 }

libs/core/src/main/java/org/opensearch/core/common/bytes/AbstractBytesReference.java

@@ -49,7 +49,8 @@
  */
 public abstract class AbstractBytesReference implements BytesReference {
 
-    private Integer hash = null; // we cache the hash of this reference since it can be quite costly to re-calculated it
+    /** we cache the hash of this reference since it can be quite costly to re-calculated it */
+    private Integer hash = null;
     private static final int MAX_UTF16_LENGTH = Integer.MAX_VALUE >> 1;
 
     @Override