Merge pull request #123 from IBM/polish-code-javadoc

Polish code and improve javadoc documentation

Author: andreadimaio

modules/watsonx-ai-core/src/main/java/com/ibm/watsonx/ai/core/auth/iam/DefaultRestClient.java

@@ -14,6 +14,7 @@
 import java.net.http.HttpResponse.BodyHandlers;
 import java.nio.charset.StandardCharsets;
 import java.util.concurrent.CompletableFuture;
+import java.util.function.Function;
 import com.ibm.watsonx.ai.core.auth.IdentityTokenResponse;
 import com.ibm.watsonx.ai.core.factory.HttpClientFactory;
 import com.ibm.watsonx.ai.core.http.AsyncHttpClient;
@@ -71,7 +72,7 @@ public CompletableFuture<IdentityTokenResponse> asyncToken(String apiKey, String
                 throw new RuntimeException(response.body());
 
             }, ExecutorProvider.cpuExecutor())
-            .thenApplyAsync(r -> r, ExecutorProvider.ioExecutor());
+            .thenApplyAsync(Function.identity(), ExecutorProvider.ioExecutor());
     }
 
     /*

modules/watsonx-ai-core/src/test/java/com/ibm/watsonx/ai/core/LoggerInterceptorTest.java

@@ -32,6 +32,7 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.Executors;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
 import java.util.stream.Stream;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
@@ -359,7 +360,7 @@ public <T> CompletableFuture<HttpResponse<T>> intercept(HttpRequest request, Bod
                         assertEquals("io-thread", Thread.currentThread().getName());
                         threadNames.add(Thread.currentThread().getName());
                         return chain.proceed(request, bodyHandler)
-                            .thenApplyAsync(r -> r, cpuExecutor)
+                            .thenApplyAsync(Function.identity(), cpuExecutor)
                             .thenApplyAsync(r -> {
                                 threadNames.add(Thread.currentThread().getName());
                                 return r;

modules/watsonx-ai-core/src/test/java/com/ibm/watsonx/ai/core/RetryInterceptorTest.java

@@ -35,6 +35,7 @@
 import java.util.concurrent.Executors;
 import java.util.concurrent.Flow;
 import java.util.concurrent.TimeUnit;
+import java.util.function.Function;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
@@ -625,8 +626,8 @@ void test_executor() throws Exception {
                     public <T> CompletableFuture<HttpResponse<T>> intercept(HttpRequest request, BodyHandler<T> bodyHandler,
                         int index, AsyncChain chain) {
                         return chain.proceed(request, bodyHandler)
-                            .thenApplyAsync(r -> r, cpuExecutor)
-                            .thenApplyAsync(r -> r, ioExecutor);
+                            .thenApplyAsync(Function.identity(), cpuExecutor)
+                            .thenApplyAsync(Function.identity(), ioExecutor);
                     }
                 }).build();
 

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/chat/model/Thinking.java

@@ -152,4 +152,10 @@ public Thinking build() {
             return new Thinking(this);
         }
     }
+
+    @Override
+    public String toString() {
+        return "Thinking [enabled=" + enabled + ", includeReasoning=" + includeReasoning + ", extractionTags=" + extractionTags + ", thinkingEffort="
+            + thinkingEffort + "]";
+    }
 }

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/DetectionService.java

@@ -23,7 +23,7 @@
  * DetectionResponse<DetectionTextResponse> response = detectionService.detect(
  *     DetectionTextRequest.builder()
  *         .input("...")
- *         .detectors(Pii.create(), Hap.builder().threshold(0.3).build())
+ *         .detectors(Pii.ofDefaults(), Hap.builder().threshold(0.3).build())
  *         .build()
  * );
  * }</pre>
@@ -72,7 +72,7 @@ public DetectionResponse<DetectionTextResponse> detect(DetectionTextRequest requ
      * DetectionResponse<DetectionTextResponse> response = detectionService.detect(
      *     DetectionTextRequest.builder()
      *         .input("...")
-     *         .detectors(Pii.create(), Hap.builder().threshold(0.3).build())
+     *         .detectors(Pii.ofDefaults(), Hap.builder().threshold(0.3).build())
      *         .build()
      * );
      * }</pre>

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/DetectionTextRequest.java

@@ -20,7 +20,7 @@
  * DetectionTextRequest request =
  *     DetectionTextRequest.builder()
  *         .input("...")
- *         .detectors(Pii.create(), Hap.builder().threshold(0.3).build())
+ *         .detectors(Pii.ofDefaults(), Hap.builder().threshold(0.3).build())
  *         .build();
  * }</pre>
  */
@@ -52,7 +52,7 @@ public Map<String, Map<String, Object>> getDetectors() {
      * DetectionTextRequest request =
      *     DetectionTextRequest.builder()
      *         .input("...")
-     *         .detectors(Pii.create(), Hap.builder().threshold(0.3).build())
+     *         .detectors(Pii.ofDefaults(), Hap.builder().threshold(0.3).build())
      *         .build();
      * }</pre>
      *
@@ -109,4 +109,10 @@ public DetectionTextRequest build() {
             return new DetectionTextRequest(this);
         }
     }
+
+    @Override
+    public String toString() {
+        return "DetectionTextRequest [projectId=" + projectId + ", spaceId=" + spaceId + ", transactionId=" + transactionId + ", input=" + input
+            + ", detectors=" + detectors + "]";
+    }
 }

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/detector/BaseDetector.java

@@ -10,7 +10,18 @@
 import java.util.Map;
 
 /**
- * Abstract class for all detectors.
+ * Represents a configurable content detector used by the detection service.
+ * <p>
+ * This is an abstract base class, one of its concrete implementations should be used instead:
+ * <ul>
+ * <li>{@link Pii} — detects personally identifiable information (PII)</li>
+ * <li>{@link Hap} — detects hate or profanity content</li>
+ * <li>{@link GraniteGuardian} — performs general content moderation</li>
+ * </ul>
+ * <p>
+ * Each detector exposes a builder for fluent configuration of parameters.
+ * <p>
+ * Detectors are used in a {@code DetectionService} request to specify which kinds of content analysis to perform.
  *
  * @see Pii
  * @see Hap

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/detector/GraniteGuardian.java

@@ -21,6 +21,21 @@ private GraniteGuardian(Builder builder) {
         super(builder);
     }
 
+    /**
+     * Returns an empty {@link GraniteGuardian} detector instance with no properties configured.
+     * <p>
+     * This is equivalent to:
+     *
+     * <pre>{@code
+     * GraniteGuardian detector = GraniteGuardian.builder().build();
+     * }</pre>
+     *
+     * @return an empty {@link GraniteGuardian} instance.
+     */
+    public static GraniteGuardian ofDefaults() {
+        return builder().build();
+    }
+
     /**
      * Returns a new {@link Builder} instance.
      * <p>

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/detector/Hap.java

@@ -21,6 +21,21 @@ private Hap(Builder builder) {
         super(builder);
     }
 
+    /**
+     * Returns an empty {@link Hap} detector instance with no properties configured.
+     * <p>
+     * This is equivalent to:
+     *
+     * <pre>{@code
+     * Hap detector = Hap.builder().build();
+     * }</pre>
+     *
+     * @return an empty {@link Hap} instance.
+     */
+    public static Hap ofDefaults() {
+        return builder().build();
+    }
+
     /**
      * Returns a new {@link Builder} instance.
      * <p>

modules/watsonx-ai/src/main/java/com/ibm/watsonx/ai/detection/detector/Pii.java

@@ -10,9 +10,7 @@
  * <b>Example usage:</b>
  *
  * <pre>{@code
- * Pii detector = Pii.builder()
- *     .threshold(0.5)
- *     .build();
+ * Pii detector = Pii.ofDefaults();
  * }</pre>
  */
 public final class Pii extends BaseDetector {
@@ -22,11 +20,17 @@ private Pii(Builder builder) {
     }
 
     /**
-     * Creates a new instance of Pii.
+     * Returns an empty {@link Pii} detector instance with no properties configured.
+     * <p>
+     * This is equivalent to:
+     *
+     * <pre>{@code
+     * Pii detector = Pii.builder().build();
+     * }</pre>
      *
-     * @return new {@link Pii} instance.
+     * @return an empty {@link Pii} instance.
      */
-    public static Pii create() {
+    public static Pii ofDefaults() {
         return builder().build();
     }
 
@@ -36,9 +40,7 @@ public static Pii create() {
      * <b>Example usage:</b>
      *
      * <pre>{@code
-     * Pii detector = Pii.builder()
-     *     .threshold(0.5)
-     *     .build();
+     * Pii detector = Pii.ofDefaults();
      * }</pre>
      *
      * @return {@link Builder} instance.