Update JavaDocs

Author: clun

src/main/java/com/datastax/astra/client/Collection.java

@@ -130,6 +130,8 @@ public class Collection<DOC> extends AbstractCommandRunner {
      *      client namespace http
      * @param collectionName
      *      collection identifier
+     * @param clazz
+     *      working object for document in the collection
      */
     protected Collection(Database db, String collectionName, Class<DOC> clazz) {
         notNull(db, "database");

src/main/java/com/datastax/astra/client/DataAPIClient.java

@@ -29,6 +29,9 @@
 
 import static com.datastax.astra.client.AstraDBAdmin.DEFAULT_NAMESPACE;
 
+/**
+ * Entry point to access the Data API.
+ */
 public class DataAPIClient {
 
     /** Token in use with the solution. */
@@ -37,10 +40,24 @@ public class DataAPIClient {
     /** Options to setup the client. */
     private final DataAPIOptions options;
 
+    /**
+     * Constructor with a token
+     *
+     * @param token
+     *      authentication token.
+     */
     public DataAPIClient(String token) {
         this(token, DataAPIOptions.builder().build());
     }
 
+    /**
+     * Constructor with a token and options.
+     *
+     * @param token
+     *      authentication token
+     * @param options
+     *      set of options for the http client
+     */
     public DataAPIClient(String token, DataAPIOptions options) {
         Assert.hasLength(token, "token");
         Assert.notNull(options, "options");
@@ -52,14 +69,34 @@ public DataAPIClient(String token, DataAPIOptions options) {
     // ---       Access AstraDBAdmin                  ---
     // --------------------------------------------------
 
+    /**
+     * Access the administration client (crud on databases).
+     *
+     * @return
+     *      administration client
+     */
     public AstraDBAdmin getAdmin() {
         return getAdmin(this.token);
     }
 
+    /**
+     * Access the administration client (crud on databases) by providing a stronger token.
+     *
+     * @param superUserToken
+     *      provide a token with enough privileges for admin operations
+     * @return
+     *      administration client
+     */
     public AstraDBAdmin getAdmin(String superUserToken) {
        return new AstraDBAdmin(superUserToken, getAstraEnvironment(), options);
     }
 
+    /**
+     * Allow to find the environment from the destination.
+     *
+     * @return
+     *      current astra environment
+     */
     private Optional<AstraEnvironment> findAstraEnvironment() {
         if (options.getDestination() != null) {
             switch (options.getDestination()) {
@@ -74,6 +111,12 @@ private Optional<AstraEnvironment> findAstraEnvironment() {
         return Optional.empty();
     }
 
+    /**
+     * Get the current Astra Environment.
+     *
+     * @return
+     *      current astra environment
+     */
     private AstraEnvironment getAstraEnvironment() {
         return findAstraEnvironment()
                 .orElseThrow(() -> new IllegalArgumentException("'destination' should be ASTRA* to use the AstraDBAdmin"));
@@ -83,6 +126,16 @@ private AstraEnvironment getAstraEnvironment() {
     // ---       Access Database                      ---
     // --------------------------------------------------
 
+    /**
+     * Access a database client to interact with the Data API.
+     *
+     * @param databaseId
+     *      unique identifier of the database
+     * @param namespace
+     *      namespace to use
+     * @return
+     *      database client
+     */
     public Database getDatabase(UUID databaseId, String namespace) {
         Assert.notNull(databaseId, "databaseId");
         Assert.hasLength(namespace, "namespace");
@@ -92,14 +145,38 @@ public Database getDatabase(UUID databaseId, String namespace) {
                 namespace);
     }
 
+    /**
+     * Access a database client to interact with the Data API.
+     * @param databaseId
+     *      unique identifier of the database
+     * @return
+     *      database client
+     */
     public Database getDatabase(UUID databaseId) {
         return getDatabase(databaseId, DEFAULT_NAMESPACE);
     }
 
+    /**
+     * Access a database client to interact with the Data API.
+     * @param apiEndpoint
+     *      url of the api in used
+     * @param namespace
+     *      namespace to use
+     * @return
+     *      database client
+     */
     public Database getDatabase(String apiEndpoint, String namespace) {
         return new Database(apiEndpoint, token, namespace, options);
     }
 
+    /**
+     * Access a database client to interact with the Data API.
+     *
+     * @param apiEndpoint
+     *      url of the api in used
+     * @return
+     *      database client
+     */
     public Database getDatabase(String apiEndpoint) {
         return getDatabase(apiEndpoint, DEFAULT_NAMESPACE);
     }

src/main/java/com/datastax/astra/client/DataAPIClients.java

@@ -34,29 +34,29 @@ public class DataAPIClients {
     /** Default endpoint. */
     public static final String DEFAULT_ENDPOINT = "http://localhost:8181";
 
-    /** Default endpoint. */
-    public static final String PATH_HEALTH_CHECK = "/stargate/health";
-
-    /** Default service id. */
-    public static final String DEFAULT_SERVICE_ID = "sgv2-json";
-
-    /** Default datacenter id. */
-    private static final String DEFAULT_DATACENTER = "dc1";
-
     /**
      * Utility class, should not be instanced.
      */
     private DataAPIClients() {}
 
     /**
-     * Create from an Endpoint only
+     * Create DataApiClient to interact with a local instance of Stargate.
+     * @return
+     *      DataApiClient for local instance
+     *
      */
     public static DataAPIClient localClient() {
         return new DataAPIClient(
                 new StargateAuthenticationService().getToken(),
                 DataAPIOptions.builder().withDestination(DataAPIDestination.CASSANDRA).build());
     }
 
+    /**
+     * Create DataApiClient and Database to interact with a local instance of Stargate.
+     *
+     * @return
+     *    Database client for local instance
+     */
     public static Database localDatabase() {
         Database db = localClient().getDatabase(DEFAULT_ENDPOINT, DEFAULT_NAMESPACE);
         db.registerListener("logger", new LoggingCommandObserver(Database.class));
@@ -66,26 +66,50 @@ public static Database localDatabase() {
         return db;
     }
 
+
+    /**
+     * Create DataApiClient and Database to interact with Astra,
+     *
+     * @param token
+     *      authentication token
+     * @return
+     *      Database client to use Astra
+     */
     public static DataAPIClient astra(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
                 .withDestination(DataAPIDestination.ASTRA)
                 .build());
     }
 
+    /**
+     * Create DataApiClient and Database to interact with Astra in development environment.
+     *
+     * @param token
+     *      authentication token
+     * @return
+     *      Database client to use Astra DEV
+     */
     public static DataAPIClient astraDev(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
                 .withDestination(DataAPIDestination.ASTRA_DEV)
                 .build());
     }
 
+    /**
+     * Create DataApiClient and Database to interact with Astra in test  environment.
+     *
+     * @param token
+     *      authentication token
+     * @return
+     *      Database client to use Astra TEST
+     */
     public static DataAPIClient astraTest(String token) {
         return new DataAPIClient(token, DataAPIOptions
                 .builder()
                 .withDestination(DataAPIDestination.ASTRA_TEST)
                 .build());
     }
 
-
 }

src/main/java/com/datastax/astra/client/DataAPIDestination.java

@@ -20,6 +20,38 @@
  * #L%
  */
 
+/**
+ * Represent the destination of the data API.
+ */
 public enum DataAPIDestination {
-    ASTRA, ASTRA_DEV, ASTRA_TEST, DSE, CASSANDRA, OTHERS
+
+    /**
+     * Astra Production environment
+     */
+    ASTRA,
+
+    /**
+     * Astra Development environment
+     */
+    ASTRA_DEV,
+
+    /**
+     * Astra Test environment
+     */
+    ASTRA_TEST,
+
+    /**
+     * Local installation of Datastax Enterprise
+     */
+    DSE,
+
+    /**
+     * Local installation of Apache Cassandra
+     */
+    CASSANDRA,
+
+    /**
+     * Extra local installation .
+     */
+    OTHERS
 }

src/main/java/com/datastax/astra/client/DatabaseAdmin.java

@@ -61,9 +61,9 @@ public interface DatabaseAdmin {
      * Retrieves a stream of namespace names available in the current database. This method is essential for
      * applications that need to enumerate all namespaces to perform operations such as displaying available
      * namespaces to users, managing namespaces programmatically, or executing specific tasks within each
-     * namespace. The returned {@link Stream} facilitates efficient processing of namespace names, enabling
+     * namespace. The returned Stream facilitates efficient processing of namespace names, enabling
      * operations like filtering, sorting, and mapping without the need for preloading all names into memory.
-     * <p></p>
+     *
      * <p>Example usage:</p>
      * <pre>
      * {@code