Fixing various javadocs (#9817) (#9961)

* fixing javadoc of org.opensearch.cli.Terminal



* fixing javadoc of org.opensearch.cli.ExitCodes



* fixing javadoc



* fixing a mishap in formatting rule



---------


(cherry picked from commit 77f0df3)

Signed-off-by: Laurent Laborde <[email protected]>
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

libs/cli/src/main/java/org/opensearch/cli/ExitCodes.java

@@ -36,20 +36,34 @@
  * POSIX exit codes.
  */
 public class ExitCodes {
+    /** No error */
     public static final int OK = 0;
-    public static final int USAGE = 64; /* command line usage error */
-    public static final int DATA_ERROR = 65; /* data format error */
-    public static final int NO_INPUT = 66; /* cannot open input */
-    public static final int NO_USER = 67; /* addressee unknown */
-    public static final int NO_HOST = 68; /* host name unknown */
-    public static final int UNAVAILABLE = 69; /* service unavailable */
-    public static final int CODE_ERROR = 70; /* internal software error */
-    public static final int CANT_CREATE = 73; /* can't create (user) output file */
-    public static final int IO_ERROR = 74; /* input/output error */
-    public static final int TEMP_FAILURE = 75; /* temp failure; user is invited to retry */
-    public static final int PROTOCOL = 76; /* remote error in protocol */
-    public static final int NOPERM = 77; /* permission denied */
-    public static final int CONFIG = 78; /* configuration error */
+    /** command line usage error */
+    public static final int USAGE = 64;
+    /** data format error */
+    public static final int DATA_ERROR = 65;
+    /** cannot open input */
+    public static final int NO_INPUT = 66;
+    /** addressee unknown */
+    public static final int NO_USER = 67;
+    /** host name unknown */
+    public static final int NO_HOST = 68;
+    /** service unavailable */
+    public static final int UNAVAILABLE = 69;
+    /** internal software error */
+    public static final int CODE_ERROR = 70;
+    /** can't create (user) output file */
+    public static final int CANT_CREATE = 73;
+    /** input/output error */
+    public static final int IO_ERROR = 74;
+    /** temp failure; user is invited to retry */
+    public static final int TEMP_FAILURE = 75;
+    /** remote error in protocol */
+    public static final int PROTOCOL = 76;
+    /** permission denied */
+    public static final int NOPERM = 77;
+    /** configuration error */
+    public static final int CONFIG = 78;
 
     private ExitCodes() { /* no instance, just constants */ }
 }

libs/cli/src/main/java/org/opensearch/cli/Terminal.java

@@ -51,6 +51,8 @@
  * which allows {@link #println(Verbosity,String)} calls which act like a logger,
  * only actually printing if the verbosity level of the terminal is above
  * the verbosity of the message.
+ * @see ConsoleTerminal
+ * @see SystemTerminal
 */
 public abstract class Terminal {
 
@@ -65,35 +67,57 @@ private static PrintWriter newErrorWriter() {
         return new PrintWriter(System.err);
     }
 
-    /** Defines the available verbosity levels of messages to be printed. */
+    /** Defines the available verbosity levels of messages to be printed.*/
     public enum Verbosity {
-        SILENT, /* always printed */
-        NORMAL, /* printed when no options are given to cli */
-        VERBOSE /* printed only when cli is passed verbose option */
+        /** always printed */
+        SILENT,
+        /** printed when no options are given to cli */
+        NORMAL,
+        /** printed only when cli is passed verbose option */
+        VERBOSE
     }
 
     /** The current verbosity for the terminal, defaulting to {@link Verbosity#NORMAL}. */
     private Verbosity verbosity = Verbosity.NORMAL;
 
-    /** The newline used when calling println. */
+    /** The newline separator used when calling println. */
     private final String lineSeparator;
 
+    /** Constructs a new terminal with the given line separator.
+     * @param lineSeparator the line separator to use when calling println
+     * */
     protected Terminal(String lineSeparator) {
         this.lineSeparator = lineSeparator;
     }
 
-    /** Sets the verbosity of the terminal. */
+    /** Sets the {@link Terminal#verbosity} of the terminal. (Default is {@link Verbosity#NORMAL})
+     * @param verbosity the {@link Verbosity} level that will be used for printing
+     * */
     public void setVerbosity(Verbosity verbosity) {
         this.verbosity = verbosity;
     }
 
-    /** Reads clear text from the terminal input. See {@link Console#readLine()}. */
+    /** Reads clear text from the terminal input.
+     * @see Console#readLine()
+     * @param prompt message to display to the user
+     * @return the text entered by the user
+     * */
     public abstract String readText(String prompt);
 
-    /** Reads password text from the terminal input. See {@link Console#readPassword()}}. */
+    /** Reads secret text from the terminal input with echoing disabled.
+     * @see Console#readPassword()
+     * @param prompt message to display to the user
+     * @return the secret as a character array
+     * */
     public abstract char[] readSecret(String prompt);
 
-    /** Read password text form terminal input up to a maximum length. */
+    /** Read secret text from terminal input with echoing disabled, up to a maximum length.
+     * @see Console#readPassword()
+     * @param prompt message to display to the user
+     * @param maxLength the maximum length of the secret
+     * @return the secret as a character array
+     * @throws IllegalStateException if the secret exceeds the maximum length
+     * */
     public char[] readSecret(String prompt, int maxLength) {
         char[] result = readSecret(prompt);
         if (result.length > maxLength) {
@@ -103,30 +127,48 @@ public char[] readSecret(String prompt, int maxLength) {
         return result;
     }
 
-    /** Returns a Writer which can be used to write to the terminal directly using standard output. */
+    /** Returns a Writer which can be used to write to the terminal directly using standard output.
+     * @return a writer to {@link Terminal#DEFAULT} output
+     * @see Terminal.ConsoleTerminal
+     * @see Terminal.SystemTerminal
+     * */
     public abstract PrintWriter getWriter();
 
-    /** Returns a Writer which can be used to write to the terminal directly using standard error. */
+    /** Returns a Writer which can be used to write to the terminal directly using standard error.
+     * @return a writer to stderr
+     * */
     public PrintWriter getErrorWriter() {
         return ERROR_WRITER;
     }
 
-    /** Prints a line to the terminal at {@link Verbosity#NORMAL} verbosity level. */
+    /** Prints a line to the terminal at {@link Verbosity#NORMAL} verbosity level, with a {@link Terminal#lineSeparator}
+     * @param msg the message to print
+     * */
     public final void println(String msg) {
         println(Verbosity.NORMAL, msg);
     }
 
-    /** Prints a line to the terminal at {@code verbosity} level. */
+    /** Prints message to the terminal's standard output at {@link Verbosity} level, with a {@link Terminal#lineSeparator}.
+     * @param verbosity the {@link Verbosity} level at which to print
+     * @param msg the message to print
+     * */
     public final void println(Verbosity verbosity, String msg) {
         print(verbosity, msg + lineSeparator);
     }
 
-    /** Prints message to the terminal's standard output at {@code verbosity} level, without a newline. */
+    /** Prints message to the terminal's standard output at {@link Verbosity} level, without adding a {@link Terminal#lineSeparator}.
+     * @param verbosity the {@link Verbosity} level at which to print
+     * @param msg the message to print
+     * */
     public final void print(Verbosity verbosity, String msg) {
         print(verbosity, msg, false);
     }
 
-    /** Prints message to the terminal at {@code verbosity} level, without a newline. */
+    /** Prints message to either standard or error output at {@link Verbosity} level, without adding a {@link Terminal#lineSeparator}.
+     * @param verbosity the {@link Verbosity} level at which to print.
+     * @param msg the message to print
+     * @param isError if true, prints to standard error instead of standard output
+     * */
     private void print(Verbosity verbosity, String msg, boolean isError) {
         if (isPrintable(verbosity)) {
             PrintWriter writer = isError ? getErrorWriter() : getWriter();
@@ -135,29 +177,44 @@ private void print(Verbosity verbosity, String msg, boolean isError) {
         }
     }
 
-    /** Prints a line to the terminal's standard error at {@link Verbosity#NORMAL} verbosity level, without a newline. */
+    /** Prints a line to the terminal's standard error at {@link Verbosity} level, without adding a {@link Terminal#lineSeparator}.
+     * @param verbosity the {@link Verbosity} level at which to print.
+     * @param msg the message to print
+     * */
     public final void errorPrint(Verbosity verbosity, String msg) {
         print(verbosity, msg, true);
     }
 
-    /** Prints a line to the terminal's standard error at {@link Verbosity#NORMAL} verbosity level. */
+    /** Prints a line to the terminal's standard error at {@link Verbosity#NORMAL} verbosity level, with a {@link Terminal#lineSeparator}
+     * @param msg the message to print
+     * */
     public final void errorPrintln(String msg) {
         errorPrintln(Verbosity.NORMAL, msg);
     }
 
-    /** Prints a line to the terminal's standard error at {@code verbosity} level. */
+    /** Prints a line to the terminal's standard error at {@link Verbosity} level, with a {@link Terminal#lineSeparator}.
+     * @param verbosity the {@link Verbosity} level at which to print.
+     * @param msg the message to print
+     * */
     public final void errorPrintln(Verbosity verbosity, String msg) {
         errorPrint(verbosity, msg + lineSeparator);
     }
 
-    /** Checks if is enough {@code verbosity} level to be printed */
+    /** Checks if given {@link Verbosity} level is high enough to be printed at the level defined by {@link Terminal#verbosity}
+     * @param verbosity the {@link Verbosity} level to check
+     * @return true if the {@link Verbosity} level is high enough to be printed
+     * @see Terminal#setVerbosity(Verbosity)
+     * */
     public final boolean isPrintable(Verbosity verbosity) {
         return this.verbosity.ordinal() >= verbosity.ordinal();
     }
 
     /**
-     * Prompt for a yes or no answer from the user. This method will loop until 'y' or 'n'
+     * Prompt for a yes or no answer from the user. This method will loop until 'y', 'n'
      * (or the default empty value) is entered.
+     * @param prompt the prompt to display to the user
+     * @param defaultYes if true, the default answer is 'y', otherwise it is 'n'
+     * @return true if the user answered 'y', false if the user answered 'n' or the defaultYes value if the user entered nothing
      */
     public final boolean promptYesNo(String prompt, boolean defaultYes) {
         String answerPrompt = defaultYes ? " [Y/n]" : " [y/N]";
@@ -181,6 +238,11 @@ public final boolean promptYesNo(String prompt, boolean defaultYes) {
      * character is immediately preceded by a carriage return, we have
      * a Windows-style newline, so we discard the carriage return as well
      * as the newline.
+     * @param reader the reader to read from
+     * @param maxLength the maximum length of the line to read
+     * @return the line read from the reader
+     * @throws RuntimeException if the line read exceeds the maximum length
+     * @throws RuntimeException if an IOException occurs while reading
      */
     public static char[] readLineToCharArray(Reader reader, int maxLength) {
         char[] buf = new char[maxLength + 2];
@@ -215,6 +277,7 @@ public static char[] readLineToCharArray(Reader reader, int maxLength) {
         }
     }
 
+    /** Flushes the terminal's standard output and standard error. */
     public void flush() {
         this.getWriter().flush();
         this.getErrorWriter().flush();

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

@@ -61,6 +61,20 @@ public V2 v2() {
         return v2;
     }
 
+    /**
+     * Returns {@code true} if the given object is also a tuple and the two tuples
+     * have equal {@link #v1()} and {@link #v2()} values.
+     * <p>
+     * Returns {@code false} otherwise, including for {@code null} values or
+     * objects of different types.
+     * <p>
+     * Note: {@code Tuple} instances are equal if the underlying values are
+     * equal, even if the types are different.
+     *
+     * @param o the object to compare to
+     * @return {@code true} if the given object is also a tuple and the two tuples
+     * have equal {@link #v1()} and {@link #v2()} values.
+     */
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -74,13 +88,21 @@ public boolean equals(Object o) {
         return true;
     }
 
+    /**
+     * Returns the hash code value for this Tuple.
+     * @return the hash code value for this Tuple.
+     */
     @Override
     public int hashCode() {
         int result = v1 != null ? v1.hashCode() : 0;
         result = 31 * result + (v2 != null ? v2.hashCode() : 0);
         return result;
     }
 
+    /**
+     * Returns a string representation of a Tuple
+     * @return {@code "Tuple [v1=value1, v2=value2]"}
+     */
     @Override
     public String toString() {
         return "Tuple [v1=" + v1 + ", v2=" + v2 + "]";

libs/common/src/main/java/org/opensearch/common/crypto/CryptoHandler.java

@@ -19,8 +19,8 @@
  * Crypto provider abstractions for encryption and decryption of data. Allows registering multiple providers
  * for defining different ways of encrypting or decrypting data.
  *
- * T - Encryption Metadata / CryptoContext
- * U - Parsed Encryption Metadata / CryptoContext
+ * @param <T> Encryption Metadata / CryptoContext
+ * @param <U> Parsed Encryption Metadata / CryptoContext
  */
 @ExperimentalApi
 public interface CryptoHandler<T, U> extends Closeable {
@@ -38,6 +38,7 @@ public interface CryptoHandler<T, U> extends Closeable {
      * Note that underlying information in the loaded metadata object is same as present in the object created during
      * encryption but object type may differ.
      *
+     * @param encryptedHeaderContentSupplier supplier for encrypted header content.
      * @return crypto metadata instance used in decryption.
      */
     U loadEncryptionMetadata(EncryptedHeaderContentSupplier encryptedHeaderContentSupplier) throws IOException;

libs/common/src/main/java/org/opensearch/common/crypto/DataKeyPair.java

@@ -11,7 +11,10 @@
  * Key pair generated by {@link MasterKeyProvider}
  */
 public class DataKeyPair {
+
+    /** Unencrypted data key used for encryption and decryption */
     private final byte[] rawKey;
+    /** Encrypted version of rawKey */
     private final byte[] encryptedKey;
 
     /**
@@ -25,7 +28,7 @@ public DataKeyPair(byte[] rawKey, byte[] encryptedKey) {
     }
 
     /**
-     * Returns raw key
+     * Returns Unencrypted data key
      * @return raw/decrypted key
      */
     public byte[] getRawKey() {

libs/common/src/main/java/org/opensearch/common/crypto/DecryptedRangedStreamProvider.java

@@ -16,7 +16,9 @@
  */
 public class DecryptedRangedStreamProvider {
 
+    /** Adjusted range of partial encrypted content which needs to be used for decryption. */
     private final long[] adjustedRange;
+    /** Stream provider for decryption and range re-adjustment. */
     private final UnaryOperator<InputStream> decryptedStreamProvider;
 
     /**

libs/common/src/main/java/org/opensearch/common/crypto/MasterKeyProvider.java

@@ -22,7 +22,7 @@ public interface MasterKeyProvider extends Closeable {
     DataKeyPair generateDataPair();
 
     /**
-     * Returns decrpted key against the encrypted key.
+     * Returns decrypted key against the encrypted key.
      * @param encryptedKey Key to decrypt
      * @return Decrypted version of key.
      */
@@ -35,6 +35,7 @@ public interface MasterKeyProvider extends Closeable {
     String getKeyId();
 
     /**
+     * Returns encryption context associated with this master key.
      * @return encryption context associated with this master key.
      */
     Map<String, String> getEncryptionContext();

libs/compress/src/main/java/org/opensearch/compress/spi/CompressionProvider.java

@@ -23,7 +23,10 @@
  */
 public class CompressionProvider implements CompressorProvider {
 
-    /** Returns the concrete {@link Compressor}s provided by the compress library */
+    /**
+     * Returns the concrete {@link Compressor}s provided by the compress library
+     * @return a list of {@link Compressor}s
+     * */
     @SuppressWarnings({ "unchecked", "rawtypes" })
     @Override
     public List<Entry<String, Compressor>> getCompressors() {