test(cdc): bind EnvUtils public documentation

cdc-service/src/main/java/com/xtrmetl/cdc/util/EnvUtils.java

@@ -2,10 +2,24 @@
 
 import java.util.Map;
 
+/**
+ * Reads process environment variables for CDC deployment configuration.
+ *
+ * <p>Optional lookups use caller-provided defaults for missing or blank values. Required
+ * lookups fail closed when a value is missing or blank. Returned configured values are not
+ * transformed by this utility.</p>
+ */
 public final class EnvUtils {
 
     private EnvUtils() {}
 
+    /**
+     * Reads an optional environment variable and returns the supplied default when the variable is missing or blank.
+     *
+     * @param key environment variable name
+     * @param defaultValue value returned when the variable is missing or blank
+     * @return configured value when present and non-blank, otherwise {@code defaultValue}
+     */
     public static String getEnv(String key, String defaultValue) {
         return getEnv(System.getenv(), key, defaultValue);
     }
@@ -18,6 +32,13 @@ static String getEnv(Map<String, String> env, String key, String defaultValue) {
         return value;
     }
 
+    /**
+     * Reads a required environment variable.
+     *
+     * @param key environment variable name
+     * @return configured non-blank value
+     * @throws IllegalStateException when the variable is missing or blank
+     */
     public static String requireEnv(String key) {
         return requireEnv(System.getenv(), key);
     }

cdc-service/src/test/java/com/xtrmetl/cdc/util/EnvUtilsTest.java

@@ -2,12 +2,17 @@
 
 import org.junit.jupiter.api.Test;
 
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.HashMap;
 import java.util.Map;
 import java.util.UUID;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 class EnvUtilsTest {
 
@@ -54,4 +59,19 @@ void publicMethodsWorkForMissingEnv() {
         assertEquals("default", EnvUtils.getEnv(key, "default"));
         assertThrows(IllegalStateException.class, () -> EnvUtils.requireEnv(key));
     }
+
+    @Test
+    void publicEnvironmentApiHasBeginnerReadableJavadoc() throws IOException {
+        String source = Files.readString(
+                Path.of("src/main/java/com/xtrmetl/cdc/util/EnvUtils.java"),
+                StandardCharsets.UTF_8
+        );
+
+        assertTrue(source.contains("Reads an optional environment variable"));
+        assertTrue(source.contains("returns the supplied default when the variable is missing or blank"));
+        assertTrue(source.contains("@param key environment variable name"));
+        assertTrue(source.contains("@param defaultValue value returned when the variable is missing or blank"));
+        assertTrue(source.contains("Reads a required environment variable"));
+        assertTrue(source.contains("@throws IllegalStateException when the variable is missing or blank"));
+    }
 }