Fix gradle build warnings for tsunami-common module.

PiperOrigin-RevId: 380063003
Change-Id: I2a795a7ba4ac7186a1308f93c747fd7a05774692

common/src/main/java/com/google/tsunami/common/command/CommandExecutor.java

@@ -51,13 +51,11 @@ public CommandExecutor(String... args) {
     this.processBuilder = new ProcessBuilder(args);
   }
 
-  /**
+  /*
    * Executes the command and uses a {@link ThreadPoolExecutor} to collect output and error.
    *
-   * <p>This is a convenience method for testing purposes only as the executor is not shared and
+   * This is a convenience method for testing purposes only as the executor is not shared and
    * therefore defeats the purpose of having a cached thread pool.
-   *
-   * @return Started {@link Process} object.
    */
   @VisibleForTesting
   Process execute() throws IOException, InterruptedException, ExecutionException {
@@ -76,6 +74,9 @@ Process execute() throws IOException, InterruptedException, ExecutionException {
    *
    * @param executor The executor to collect output and error streams.
    * @return Started {@link Process} object.
+   * @throws IOException if an I/O error occurs when starting the command executing process.
+   * @throws InterruptedException if interrupted while waiting for the command's output.
+   * @throws ExecutionException if the command execution failed.
    */
   public Process execute(Executor executor)
       throws IOException, InterruptedException, ExecutionException {

common/src/main/java/com/google/tsunami/common/command/CommandExecutorFactory.java

@@ -23,6 +23,8 @@ public class CommandExecutorFactory {
   /**
    * Sets an executor instance that will be returned by all future calls to {@link
    * CommandExecutorFactory#create(String...)}
+   *
+   * @param executor The {@link CommandExecutor} returned by this factory.
    */
   public static void setInstance(CommandExecutor executor) {
     instance = executor;
@@ -32,6 +34,7 @@ public static void setInstance(CommandExecutor executor) {
    * Creates a new {@link CommandExecutor} if none is set.
    *
    * @param args List of arguments to pass to the newly created {@link CommandExecutor}.
+   * @return the {@link CommandExecutor} instance created by this factory.
    */
   public static CommandExecutor create(String... args) {
     if (instance == null) {

common/src/main/java/com/google/tsunami/common/concurrent/BaseThreadPoolModule.java

@@ -126,35 +126,59 @@ abstract static class BaseThreadPoolModuleBuilder<
     /**
      * Sets the name used to name the threads; automatically suffixed with "-%s"to incorporate the
      * thread number
+     *
+     * @param name the name of the thread pool.
+     * @return the Builder instance itself.
      */
     public BuilderImplT setName(String name) {
       checkArgument(!Strings.isNullOrEmpty(name), "Name should not be empty");
       this.name = name;
       return self();
     }
 
-    /** Sets the maximum number of threads allowed in the pool; value should be positive. */
+    /**
+     * Sets the maximum number of threads allowed in the pool; value should be positive.
+     *
+     * @param maxSize the maximum number of threads allowed in this thread pool.
+     * @return the Builder instance itself.
+     */
     BuilderImplT setMaxSize(int maxSize) {
       checkArgument(maxSize > 0, "Max thread pool size should be positive.");
       this.maxSize = maxSize;
       return self();
     }
 
-    /** Sets the number of threads to keep in the pool. */
+    /**
+     * Sets the number of threads to keep in the pool.
+     *
+     * @param coreSize the minimum number of threads to keep alive in this thread pool.
+     * @return the Builder instance itself.
+     */
     BuilderImplT setCoreSize(int coreSize) {
       checkArgument(coreSize >= 0, "The core pool size should be non-negative.");
       this.coreSize = coreSize;
       return self();
     }
 
-    /** Sets the keep alive time in seconds for the threads not in core pool. */
+    /**
+     * Sets the keep alive time in seconds for the threads not in core pool.
+     *
+     * @param keepAliveSeconds the maximum number of seconds an idle thread in this pool can keep
+     *     alive before being terminated.
+     * @return the Builder instance itself.
+     */
     public BuilderImplT setKeepAliveSeconds(long keepAliveSeconds) {
       checkArgument(keepAliveSeconds >= 0, "The keep alive time should be non-negative.");
       this.keepAliveSeconds = keepAliveSeconds;
       return self();
     }
 
-    /** Sets whether or not new threads created by the pool will be daemon threads. */
+    /**
+     * Sets whether or not new threads created by the pool will be daemon threads.*
+     *
+     * @param daemon whether threads created in this pool are daemon threads.
+     * @return the Builder instance itself.
+     */
     public BuilderImplT setDaemon(boolean daemon) {
       factoryBuilder.setDaemon(daemon);
       this.daemon = daemon;
@@ -165,25 +189,43 @@ public BuilderImplT setDaemon(boolean daemon) {
      * Sets how long the JVM should wait to exit for daemon threads to complete.
      *
      * <p>This has no effect if the pool does not use daemon threads.
+     *
+     * @param shutdownDelay the delay enforced during the thread pool shutdown.
+     * @return the Builder instance itself.
      */
     public BuilderImplT setDelayedShutdown(Duration shutdownDelay) {
       this.shutdownDelay = checkNotNull(shutdownDelay);
       return self();
     }
 
-    /** Sets the priority for threads created by the pool. */
+    /**
+     * Sets the priority for threads created by the pool.
+     *
+     * @param priority the priority of the threads created by this pool.
+     * @return the Builder instance itself.
+     */
     public BuilderImplT setPriority(int priority) {
       factoryBuilder.setPriority(priority);
       return self();
     }
 
-    /** Sets the binding annotation. */
+    /**
+     * Sets the binding annotation.
+     *
+     * @param annotation the Guice binding annotation for this thread pool.
+     * @return the Builder instance itself.
+     */
     public BuilderImplT setAnnotation(Annotation annotation) {
       key = Key.get(executorServiceTypeClass, checkNotNull(annotation));
       return self();
     }
 
-    /** Sets the binding annotation. */
+    /**
+     * Sets the binding annotation.
+     *
+     * @param annotationClass the Guice binding annotation class for this thread pool.
+     * @return the Builder instance itself.
+     */
     public BuilderImplT setAnnotation(Class<? extends Annotation> annotationClass) {
       key = Key.get(executorServiceTypeClass, checkNotNull(annotationClass));
       return self();
@@ -195,6 +237,10 @@ public BuilderImplT setAnnotation(Class<? extends Annotation> annotationClass) {
      *
      * <p>By default, {@link AbortPolicy} is used for rejected execution, which throws the {@link
      * java.util.concurrent.RejectedExecutionException}.
+     *
+     * @param rejectedExecutionHandler A handler for tasks that cannot be executed by this thread
+     *     pool.
+     * @return the Builder instance itself.
      */
     public BuilderImplT setRejectedExecutionHandler(
         RejectedExecutionHandler rejectedExecutionHandler) {

common/src/main/java/com/google/tsunami/common/concurrent/ScheduledThreadPoolModule.java

@@ -80,7 +80,12 @@ Builder self() {
       return this;
     }
 
-    /** Sets the size of the thread pool. */
+    /**
+     * Sets the size of the thread pool.
+     *
+     * @param size the size of the thread pool.
+     * @return the {@link Builder} instance itself.
+     */
     public Builder setSize(int size) {
       checkArgument(size > 0, "Thread pool size should be positive.");
       setCoreSize(size);

common/src/main/java/com/google/tsunami/common/concurrent/ThreadPoolModule.java

@@ -108,6 +108,9 @@ public Builder setCoreSize(int coreSize) {
      *
      * <p>By default, {@link SynchronousQueue} will be used when {@code queueCapacity} is set to
      * zero. Otherwise a {@link LinkedBlockingQueue} will be used.
+     *
+     * @param queueCapacity the capacity of the task queue.
+     * @return the Builder instance itself.
      */
     public Builder setQueueCapacity(int queueCapacity) {
       checkArgument(queueCapacity >= 0, "The queue capacity should be non-negative value.");
@@ -121,6 +124,9 @@ public Builder setQueueCapacity(int queueCapacity) {
      * <p>NOTE: Do NOT set both {@link BlockingQueue} and {@code queueCapacity}. Only use this
      * method to override the default {@link BlockingQueue} choice. See comments of {@link
      * #getBlockingQueue} for which {@link BlockingQueue} is used by default.
+     *
+     * @param blockingQueue a {@link BlockingQueue} used for holding tasks before executing.
+     * @return the Builder instance itself.
      */
     public Builder setBlockingQueue(BlockingQueue<Runnable> blockingQueue) {
       this.blockingQueue = checkNotNull(blockingQueue);

common/src/main/java/com/google/tsunami/common/data/NetworkEndpointUtils.java

@@ -73,6 +73,9 @@ public static boolean isIpV6Endpoint(NetworkEndpoint networkEndpoint) {
    *   <li>ip_v6 = "3ffe::1", port = 8888 -&gt; uri = "[3ffe::1]:8888"
    *   <li>host = "localhost", port = 8888 -&gt; url = "localhost:8888"
    * </ul>
+   *
+   * @param networkEndpoint the {@link NetworkEndpoint} instance to be converted.
+   * @return the URI authority converted from the {@link NetworkEndpoint} instance.
    */
   public static String toUriAuthority(NetworkEndpoint networkEndpoint) {
     return toHostAndPort(networkEndpoint).toString();
@@ -102,7 +105,12 @@ public static HostAndPort toHostAndPort(NetworkEndpoint networkEndpoint) {
             "Should never happen. Unchecked NetworkEndpoint type: %s", networkEndpoint.getType()));
   }
 
-  /** Returns a {@link NetworkEndpoint} proto buffer object from the given ip address. */
+  /**
+   * Creates a {@link NetworkEndpoint} proto buffer object from the given ip address.
+   *
+   * @param ipAddress the IP address of the network endpoint.
+   * @return the created {@link NetworkEndpoint} instance from the given IP address.
+   */
   public static NetworkEndpoint forIp(String ipAddress) {
     checkArgument(InetAddresses.isInetAddress(ipAddress), "'%s' is not an IP address.", ipAddress);
 
@@ -115,7 +123,13 @@ public static NetworkEndpoint forIp(String ipAddress) {
         .build();
   }
 
-  /** Returns a {@link NetworkEndpoint} proto buffer object from the given ip address and port. */
+  /**
+   * Creates a {@link NetworkEndpoint} proto buffer object from the given ip address and port.
+   *
+   * @param ipAddress the IP address of the network endpoint.
+   * @param port the port number of the network endpoint
+   * @return the created {@link NetworkEndpoint} instance from the given IP and port.
+   */
   public static NetworkEndpoint forIpAndPort(String ipAddress, int port) {
     checkArgument(InetAddresses.isInetAddress(ipAddress), "'%s' is not an IP address.", ipAddress);
     checkArgument(
@@ -130,7 +144,12 @@ public static NetworkEndpoint forIpAndPort(String ipAddress, int port) {
         .build();
   }
 
-  /** Returns a {@link NetworkEndpoint} proto buffer object from the given hostname. */
+  /**
+   * Creates a {@link NetworkEndpoint} proto buffer object from the given hostname.
+   *
+   * @param hostname the hostname of the network endpoint
+   * @return the created {@link NetworkEndpoint} instance from the hostname.
+   */
   public static NetworkEndpoint forHostname(String hostname) {
     checkArgument(
         !InetAddresses.isInetAddress(hostname), "Expected hostname, got IP address '%s'", hostname);
@@ -142,7 +161,11 @@ public static NetworkEndpoint forHostname(String hostname) {
   }
 
   /**
-   * Returns a {@link NetworkEndpoint} proto buffer object from the given ip address and hostname.
+   * Creates a {@link NetworkEndpoint} proto buffer object from the given ip address and hostname.
+   *
+   * @param hostname the hostname of the network endpoint
+   * @param ipAddress the IP address of the network endpoint.
+   * @return the created {@link NetworkEndpoint} instance from the IP address and hostname.
    */
   public static NetworkEndpoint forIpAndHostname(String ipAddress, String hostname) {
     return forIp(ipAddress).toBuilder()
@@ -151,7 +174,13 @@ public static NetworkEndpoint forIpAndHostname(String ipAddress, String hostname
         .build();
   }
 
-  /** Returns a {@link NetworkEndpoint} proto buffer object from the given hostname and port. */
+  /**
+   * Creates a {@link NetworkEndpoint} proto buffer object from the given hostname and port.
+   *
+   * @param hostname the hostname of the network endpoint
+   * @param port the port number of the network endpoint.
+   * @return the created {@link NetworkEndpoint} instance from the hostname and port.
+   */
   public static NetworkEndpoint forHostnameAndPort(String hostname, int port) {
     checkArgument(
         0 <= port && port <= MAX_PORT_NUMBER,
@@ -168,6 +197,11 @@ public static NetworkEndpoint forHostnameAndPort(String hostname, int port) {
   /**
    * Returns a {@link NetworkEndpoint} proto buffer object from the given ip address, hostname and
    * port.
+   *
+   * @param ipAddress the IP address of the network endpoint.
+   * @param hostname the hostname of the network endpoint
+   * @param port the port number of the network endpoint.
+   * @return the created {@link NetworkEndpoint} instance from the parameters.
    */
   public static NetworkEndpoint forIpHostnameAndPort(String ipAddress, String hostname, int port) {
     checkArgument(
@@ -186,6 +220,10 @@ public static NetworkEndpoint forIpHostnameAndPort(String ipAddress, String host
    * Returns a {@link NetworkEndpoint} proto buffer object from the given {@code networkEndpoint}
    * and port. The {@code networkEndpoint} parameter cannot contain any port information, otherwise
    * {@link IllegalArgumentException} is thrown.
+   *
+   * @param networkEndpoint the source {@link NetworkEndpoint} instance without the port number
+   * @param port the port number of the network endpoint.
+   * @return the {@link NetworkEndpoint} instance from the parameters.
    */
   public static NetworkEndpoint forNetworkEndpointAndPort(
       NetworkEndpoint networkEndpoint, int port) {

common/src/main/java/com/google/tsunami/common/io/archiving/testing/FakeGoogleCloudStorageArchivers.java

@@ -31,15 +31,27 @@ public void assertNoDataStored() {
     }
   }
 
-  /** Get the byte array data stored in {@code storage} at {@code gcsUrl}. */
+  /**
+   * Get the byte array data stored in {@code storage} at {@code gcsUrl}.
+   *
+   * @param storage the instance of the GCS storage.
+   * @param gcsUrl the URL to the GCS storage object.
+   * @return the content of the GCS storage object in byte array format.
+   */
   public byte[] getStoredByteArrays(Storage storage, String gcsUrl) {
     if (!delegatedArchivers.containsKey(storage)) {
       throw new NoSuchElementException(String.format("Storage '%s' not found", storage));
     }
     return delegatedArchivers.get(storage).getStoredByteArrays(gcsUrl);
   }
 
-  /** Get the {@link CharSequence} data stored in {@code storage} at {@code gcsUrl}. */
+  /**
+   * Get the {@link CharSequence} data stored in {@code storage} at {@code gcsUrl}.
+   *
+   * @param storage the instance of the GCS storage.
+   * @param gcsUrl the URL to the GCS storage object.
+   * @return the content of the GCS storage object in {@link CharSequence} format.
+   */
   public CharSequence getStoredCharSequence(Storage storage, String gcsUrl) {
     if (!delegatedArchivers.containsKey(storage)) {
       throw new NoSuchElementException(String.format("Storage '%s' not found", storage));