chore: refine javadoc

README.md

@@ -4,17 +4,11 @@
 ![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)
 [![Maven Central](https://img.shields.io/maven-central/v/io.greptime/greptimedb-ingester.svg?label=maven%20central)](https://central.sonatype.com/search?q=io.greptime&name=ingester-all)
 
-A Java ingester for GreptimeDB, which is compatible with GreptimeDB protocol and lightweight.
+A lightweight Java ingester for GreptimeDB designed for high-throughput data writing. It utilizes the gRPC protocol to provide a non-blocking, purely asynchronous API that is easy to use and integrate into your applications.
 
-## Features
+## Documentation
+- [API Reference](https://javadoc.io/doc/io.greptime/ingester-protocol/latest/index.html)
+- [Examples](https://github.com/GreptimeTeam/greptimedb-ingester-java/tree/main/ingester-example)
 
-- SPI-based extensible network transport layer; provides the default implementation by using the
-  gRPC framework
-- Non-blocking, purely asynchronous API, easy to use
-- Automatically collects various performance metrics by default. Users can then configure them and
-  write to local files
-- Users can take in-memory snapshots of critical objects, configure them, and write to local files.
-  This is helpful when troubleshooting complex issues
-
-## Javadoc
-- [ingester-protocol](https://javadoc.io/doc/io.greptime/ingester-protocol/latest/index.html)
+# Features
+TODO

ingester-common/src/main/java/io/greptime/common/util/ExecutorServiceHelper.java

@@ -30,6 +30,9 @@ public final class ExecutorServiceHelper {
 
     /**
      * @see #shutdownAndAwaitTermination(ExecutorService, long)
+     *
+     * @param pool the executor service to shutdown
+     * @return true if the executor service is shutdown successfully, false otherwise
      */
     public static boolean shutdownAndAwaitTermination(ExecutorService pool) {
         return shutdownAndAwaitTermination(pool, 1000);
@@ -40,6 +43,10 @@ public static boolean shutdownAndAwaitTermination(ExecutorService pool) {
      * phases, first by calling {@code shutdown} to reject incoming tasks,
      * and then calling {@code shutdownNow}, if necessary, to cancel any
      * lingering tasks.
+     *
+     * @param pool the executor service to shutdown
+     * @param timeoutMillis the timeout in milliseconds
+     * @return true if the executor service is shutdown successfully, false otherwise
      */
     public static boolean shutdownAndAwaitTermination(ExecutorService pool, long timeoutMillis) {
         if (pool == null) {

ingester-common/src/main/java/io/greptime/common/util/Files.java

@@ -50,6 +50,7 @@ public static void fsync(File file) throws IOException {
      * Creates the directory named by this pathname if not exists.
      *
      * @param path pathname
+     * @throws IOException if an I/O error occurs
      */
     public static void mkdirIfNotExists(String path) throws IOException {
         File dir = Paths.get(path).toFile().getAbsoluteFile();

ingester-common/src/main/java/io/greptime/common/util/MetricsUtil.java

@@ -82,71 +82,97 @@ public static void reportImmediately() {
     }
 
     /**
-     * Return the global registry of metric instances.
+     * Gets the global registry of metric instances.
+     *
+     * @return the global registry of metric instances
      */
     public static MetricRegistry metricRegistry() {
         return METRIC_REGISTRY;
     }
 
     /**
-     * Return the {@link Meter} registered under this name; or create
+     * Gets the {@link Meter} registered under this name; or create
      * and register a new {@link Meter} if none is registered.
+     *
+     * @param name the name of the metric
+     * @return the {@link Meter} registered under this name
      */
     public static Meter meter(Object name) {
         return METRIC_REGISTRY.meter(named(name));
     }
 
     /**
-     * Return the {@link Meter} registered under this name; or create
+     * Gets the {@link Meter} registered under this name; or create
      * and register a new {@link Meter} if none is registered.
+     *
+     * @param names the names of the metric
+     * @return the {@link Meter} registered under this name
      */
     public static Meter meter(Object... names) {
         return METRIC_REGISTRY.meter(named(names));
     }
 
     /**
-     * Return the {@link Timer} registered under this name; or create
+     * Gets the {@link Timer} registered under this name; or create
      * and register a new {@link Timer} if none is registered.
+     *
+     * @param name the name of the metric
+     * @return the {@link Timer} registered under this name
      */
     public static Timer timer(Object name) {
         return METRIC_REGISTRY.timer(named(name));
     }
 
     /**
-     * Return the {@link Timer} registered under this name; or create
+     * Gets the {@link Timer} registered under this name; or create
      * and register a new {@link Timer} if none is registered.
+     *
+     * @param names the names of the metric
+     * @return the {@link Timer} registered under this name
      */
     public static Timer timer(Object... names) {
         return METRIC_REGISTRY.timer(named(names));
     }
 
     /**
-     * Return the {@link Counter} registered under this name; or create
+     * Gets the {@link Counter} registered under this name; or create
      * and register a new {@link Counter} if none is registered.
+     *
+     * @param name the name of the metric
+     * @return the {@link Counter} registered under this name
      */
     public static Counter counter(Object name) {
         return METRIC_REGISTRY.counter(named(name));
     }
 
     /**
-     * Return the {@link Counter} registered under this name; or create
+     * Gets the {@link Counter} registered under this name; or create
      * and register a new {@link Counter} if none is registered.
+     *
+     * @param names the names of the metric
+     * @return the {@link Counter} registered under this name
      */
     public static Counter counter(Object... names) {
         return METRIC_REGISTRY.counter(named(names));
     }
 
     /**
-     * Return the {@link Histogram} registered under this name; or create
+     * Gets the {@link Histogram} registered under this name; or create
      * and register a new {@link Histogram} if none is registered.
+     *
+     * @param name the name of the metric
+     * @return the {@link Histogram} registered under this name
      */
     public static Histogram histogram(Object name) {
         return METRIC_REGISTRY.histogram(named(name));
     }
 
     /**
-     * Return the {@link Histogram} registered under this name; or create
+     * Gets the {@link Histogram} registered under this name; or create
      * and register a new {@link Histogram} if none is registered.
+     *
+     * @param names the names of the metric
+     * @return the {@link Histogram} registered under this name
      */
     public static Histogram histogram(Object... names) {
         return METRIC_REGISTRY.histogram(named(names));

ingester-common/src/main/java/io/greptime/common/util/ObjectPool.java

@@ -22,27 +22,37 @@
 public interface ObjectPool<T> {
 
     /**
-     * Get an object from the pool.
+     * Gets an object from the pool.
+     *
+     * @return an object from the pool
      */
     T getObject();
 
     /**
-     * Return the object to the pool.  The caller should not use the object beyond this point.
+     * Returns the object to the pool. The caller should not use the object beyond this point.
+     *
+     * @param returned the object to return to the pool
      */
     void returnObject(T returned);
 
     /**
      * Defines a resource, and the way to create and destroy instances of it.
+     *
+     * @param <T> the type of the resource
      */
     interface Resource<T> {
 
         /**
-         * Create a new instance of the resource.
+         * Creates a new instance of the resource.
+         *
+         * @return a new instance of the resource
          */
         T create();
 
         /**
-         * Destroy the given instance.
+         * Destroys the given instance.
+         *
+         * @param instance the instance to destroy
          */
         void close(T instance);
     }

ingester-common/src/main/java/io/greptime/common/util/Platform.java

@@ -35,14 +35,18 @@ public class Platform {
     private static final boolean IS_MAC = isMac0();
 
     /**
-     * Return {@code true} if the JVM is running on Windows
+     * Checks if the JVM is running on Windows.
+     *
+     * @return {@code true} if the JVM is running on Windows
      */
     public static boolean isWindows() {
         return IS_WINDOWS;
     }
 
     /**
-     * Return {@code true} if the JVM is running on Mac OSX
+     * Checks if the JVM is running on Mac OSX.
+     *
+     * @return {@code true} if the JVM is running on Mac OSX
      */
     public static boolean isMac() {
         return IS_MAC;

ingester-common/src/main/java/io/greptime/common/util/SerializingExecutor.java

@@ -66,6 +66,8 @@ public SerializingExecutor(String name, Thread.UncaughtExceptionHandler uncaught
      * under a lock of your own, but don't want the tasks to be run under
      * your lock (for fear of deadlock).  You can call this method in the
      * lock, and call {@link #drain} outside the lock.
+     *
+     * @param task the task to add
      */
     public final void executeLater(Runnable task) {
         this.queue.add(Ensures.ensureNonNull(task, "null `task`"));

ingester-common/src/main/java/io/greptime/common/util/SharedScheduledPool.java

@@ -19,7 +19,7 @@
 import java.util.concurrent.ScheduledExecutorService;
 
 /**
- * Like rust: pub type SharedScheduledPool = RcObjectPool<ScheduledExecutorService>
+ * Like rust: {@code pub type SharedScheduledPool = RcObjectPool<ScheduledExecutorService>}
  */
 public class SharedScheduledPool extends RcObjectPool<ScheduledExecutorService> {
 

ingester-common/src/main/java/io/greptime/common/util/SharedThreadPool.java

@@ -19,7 +19,7 @@
 import java.util.concurrent.ExecutorService;
 
 /**
- * Like rust: pub type SharedThreadPool = RcObjectPool<ExecutorService>
+ * Like rust: {@code pub type SharedThreadPool = RcObjectPool<ExecutorService>}
  */
 public class SharedThreadPool extends RcObjectPool<ExecutorService> {
 

ingester-common/src/main/java/io/greptime/common/util/Strings.java

@@ -33,21 +33,30 @@ public static String toString(Object obj) {
     }
 
     /**
-     * Returns the given string if it is non-null; the empty string otherwise.
+     * Converts a null string to an empty string.
+     *
+     * @param string the string to check
+     * @return the given string if it is non-null; the empty string otherwise
      */
     public static String nullToEmpty(String string) {
         return (string == null) ? "" : string;
     }
 
     /**
-     * Returns the given string if it is nonempty; {@code null} otherwise.
+     * Converts an empty string to a null string.
+     *
+     * @param string the string to check
+     * @return the given string if it is nonempty; {@code null} otherwise
      */
     public static String emptyToNull(String string) {
         return isNullOrEmpty(string) ? null : string;
     }
 
     /**
-     * Returns {@code true} if the given string is null or is the empty string.
+     * Checks if the given string is null or is the empty string.
+     *
+     * @param str the string to check
+     * @return {@code true} if the given string is null or is the empty string
      */
     public static boolean isNullOrEmpty(String str) {
         return str == null || str.isEmpty();
@@ -63,6 +72,9 @@ public static boolean isNullOrEmpty(String str) {
      * Strings.isBlank("bob")     = false
      * Strings.isBlank("  bob  ") = false
      * ```
+     *
+     * @param str the string to check
+     * @return {@code true} if the given string is null, empty or whitespace only
      */
     public static boolean isBlank(String str) {
         int strLen;
@@ -86,6 +98,9 @@ public static boolean isBlank(String str) {
      * Strings.isNotBlank("bob")     = true
      * Strings.isNotBlank("  bob  ") = true
      * ```
+     *
+     * @param str the string to check
+     * @return {@code true} if the given string is not null, empty or whitespace only
      */
     public static boolean isNotBlank(String str) {
         return !isBlank(str);
@@ -104,6 +119,10 @@ public static boolean isNotBlank(String str) {
      * Strings.split("a:b:c", '.')    = ["a:b:c"]
      * Strings.split("a b c", ' ')    = ["a", "b", "c"]
      * ```
+     *
+     * @param str the string to split
+     * @param separator the separator
+     * @return an array of strings
      */
     public static String[] split(String str, char separator) {
         return split(str, separator, false);
@@ -129,6 +148,11 @@ public static String[] split(String str, char separator) {
      * Strings.split("  a b c", ' ', true)  = ["", "", a", "b", "c"]
      * Strings.split(" a b c ", ' ', true)  = ["", a", "b", "c", ""]
      * ```
+     *
+     * @param str the string to split
+     * @param separator the separator
+     * @param preserveAllTokens {@code true} if all tokens should be preserved, including empty tokens created by adjacent separators
+     * @return an array of strings
      */
     public static String[] split(String str, char separator, boolean preserveAllTokens) {
         if (str == null) {