less warnings

Author: clun

astra-db-java/src/main/java/com/datastax/astra/client/collections/definition/documents/Document.java

@@ -554,52 +554,104 @@ public String toJson() {
         return toString();
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Evaluation if a key is present in the document
+     * @param key
+     *     key to evaluate
+     * @return
+     *      true if the key is present
+     */
     public boolean containsKey(final Object key) {
         return documentMap.containsKey(key);
     }
 
-    /** {@inheritDoc} */
+
+    /**
+     * Retrieves the value associated with the specified key from the document.
+     *
+     * @param key the key whose associated value is to be returned
+     * @return the value associated with the specified key, or {@code null} if the key is not found
+     */
     public Object get(final Object key) {
         return documentMap.get(key);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Associates the specified value with the specified key in the document.
+     * If the key already has a value, the old value is replaced.
+     *
+     * @param key   the key with which the specified value is to be associated
+     * @param value the value to be associated with the specified key
+     * @return the previous value associated with the key, or {@code null} if there was no mapping for the key
+     */
     public Object put(final String key, final Object value) {
         return documentMap.put(key, value);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Removes the mapping for a key from the document if it is present.
+     *
+     * @param key the key whose mapping is to be removed
+     * @return the value that was associated with the key, or {@code null} if the key was not mapped
+     */
     public Object remove(final Object key) {
         return documentMap.remove(key);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Copies all mappings from the specified map to this document.
+     * Existing mappings will be replaced with mappings from the provided map.
+     *
+     * @param map the map containing mappings to be copied to this document
+     */
     public void putAll(final Map<? extends String, ?> map) {
         documentMap.putAll(map);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Copies all mappings from the specified {@code Document} to this document.
+     * Existing mappings will be replaced with mappings from the provided document.
+     *
+     * @param doc the document whose mappings are to be copied to this document
+     */
     public void putAll(Document doc) {
         documentMap.putAll(doc.getDocumentMap());
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Removes all mappings from this document.
+     * The document will be empty after this operation.
+     */
     public void clear() {
         documentMap.clear();
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Returns a collection view of the values contained in this document.
+     *
+     * @return a collection view of the values contained in this document
+     */
     public Collection<Object> values() {
         return documentMap.values();
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Returns a set view of the mappings contained in this document.
+     * Each entry in the set is a key-value pair.
+     *
+     * @return a set view of the mappings contained in this document
+     */
     public Set<Map.Entry<String, Object>> entrySet() {
         return documentMap.entrySet();
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Compares this document to another object for equality.
+     * Two documents are considered equal if their underlying maps are equal.
+     *
+     * @param o the object to compare with this document
+     * @return {@code true} if the specified object is equal to this document, {@code false} otherwise
+     */
     @Override
     public boolean equals(final Object o) {
         if (this == o) {
@@ -612,13 +664,17 @@ public boolean equals(final Object o) {
         return documentMap.equals(document.documentMap);
     }
 
-    /** {@inheritDoc} */
+    /**
+     * Returns the hash code value for this document.
+     * The hash code is computed based on the underlying map.
+     *
+     * @return the hash code value for this document
+     */
     @Override
     public int hashCode() {
         return documentMap.hashCode();
     }
 
 
 
-
 }

astra-db-java/src/main/java/com/datastax/astra/client/core/paging/CollectionCursor.java

@@ -127,6 +127,7 @@ public CollectionCursor<T> clone() {
      *
      * @param newFilter
      *      a new filter
+     * @return a new {@code CollectionCursor} instance with the filter applied
      */
     public CollectionCursor<T> filter(Filter newFilter) {
         checkIdleState();
@@ -140,6 +141,7 @@ public CollectionCursor<T> filter(Filter newFilter) {
      *
      * @param newProjection
      *      a new projection
+     * @return a new {@code CollectionCursor} instance with the projection applied
      */
     public CollectionCursor<T> project(Projection... newProjection) {
         checkIdleState();
@@ -236,7 +238,12 @@ private void rewind() {
         this.consumedCount = 0;
     }
 
-    // Buffer consumption
+    /**
+     * Consume the buffer and return the results.
+     *
+     * @return
+     *      list of results
+     */
     public List<T> consumeBuffer(int n) {
         if (state == CursorState.CLOSED || state == CursorState.IDLE) {
             return Collections.emptyList();
@@ -297,7 +304,9 @@ public T next() {
         }
     }
 
-    // Fetch next batch of documents
+    /**
+     * Fetch the next batch of documents into the buffer.
+     */
     private void fetchNextBatch() {
         if (currentPage == null) {
             currentPage = myCollection.findPage(filter, findOptions);
@@ -311,15 +320,32 @@ private void fetchNextBatch() {
         }
     }
 
-    // Additional methods
+    /**
+     * Check if there is a next element.
+     *
+     * @return
+     *      true if there is a next element
+     */
     public boolean hasNext() {
         return iterator().hasNext();
     }
 
+    /**
+     * Retrieve the next element.
+     *
+     * @return
+     *      next element
+     */
     public T next() {
         return iterator().next();
     }
 
+    /**
+     * Retrieve all the elements in a list.
+     *
+     * @return
+     *      list of elements
+     */
     public List<T> toList() {
         List<T> result = new ArrayList<>();
         try {

astra-db-java/src/main/java/com/datastax/astra/client/exceptions/ClientErrorCodes.java

@@ -22,27 +22,110 @@
 
 import lombok.Getter;
 
+/**
+ * Represents client error codes used to standardize error reporting in the application.
+ * Each error code is associated with a unique identifier (`code`) and a descriptive message (`message`).
+ * <p>
+ * This enum is designed to facilitate consistent error handling and logging across various components.
+ * Some codes are pre-configured with detailed messages that accept placeholders for dynamic values,
+ * while others are placeholders for future implementation.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * {@code
+ * String errorCode = ClientErrorCodes.CONFIG_MISSING.getCode();
+ * String errorMessage = String.format(ClientErrorCodes.CONFIG_MISSING.getMessage(), "paramName", "operationName");
+ * }
+ * </pre>
+ */
 @Getter
 public enum ClientErrorCodes {
+
+    /**
+     * Indicates that the operation is restricted to Astra environments.
+     * Dynamic placeholders:
+     * <ul>
+     *   <li>{@code '%s'}: The operation name.</li>
+     *   <li>{@code '%s'}: The current environment.</li>
+     * </ul>
+     */
     ENV_RESTRICTED_ASTRA("ASTRA_RESTRICTED", "Operation '%s' available only for Astra environments (current is '%s')"),
+
+    /**
+     * Indicates that a required configuration parameter is missing.
+     * Dynamic placeholders:
+     * <ul>
+     *   <li>{@code '%s'}: The name of the missing configuration parameter.</li>
+     *   <li>{@code '%s'}: The operation requiring the parameter.</li>
+     * </ul>
+     */
     CONFIG_MISSING("CLIENT_CONFIG_MISSING", "Configuration parameter is missing : '%s' for operation '%s'"),
+
+    /**
+     * Indicates that a required annotation is missing from a bean.
+     * Dynamic placeholders:
+     * <ul>
+     *   <li>{@code '%s'}: The name of the missing annotation.</li>
+     *   <li>{@code '%s'}: The name of the bean.</li>
+     *   <li>{@code '%s'}: The operation requiring the annotation.</li>
+     * </ul>
+     */
     MISSING_ANNOTATION("CLIENT_MISSING_ANNOTATION", "Annotation '%s' is missing on bean '%s' for operation '%s'"),
 
-    // TODO
+    /**
+     * Generic client error with no specific message.
+     */
     ERROR("CLIENT_ERROR", ""),
+
+    /**
+     * Indicates an HTTP error encountered by the client.
+     */
     HTTP("CLIENT_HTTP", ""),
+
+    /**
+     * Indicates a timeout error encountered by the client.
+     */
     TIMEOUT("CLIENT_TIMEOUT", ""),
+
+    /**
+     * Indicates an operation was interrupted.
+     */
     INTERRUPTED("CLIENT_INTERRUPTED", ""),
+
+    /**
+     * Placeholder for random client errors.
+     */
     RANDOM("CLIENT_RANDOM", ""),
+
+    /**
+     * Indicates an error related to cursor operations.
+     */
     CURSOR("CLIENT_CURSOR", ""),
+
+    /**
+     * Indicates an error in client-side serialization.
+     */
     SERIALIZATION("CLIENT_SERIALIZATION", "CLIENT_SERIALIZATION");
 
+    /**
+     * The unique code representing the error.
+     */
     private final String code;
 
+    /**
+     * The descriptive message associated with the error.
+     */
     private final String message;
 
+    /**
+     * Constructs a new {@code ClientErrorCodes} instance with the specified code and message.
+     *
+     * @param code    the unique code representing the error
+     * @param message the descriptive message associated with the error
+     */
     ClientErrorCodes(String code, String message) {
-        this.code    = code;
+        this.code = code;
         this.message = message;
     }
 }

astra-db-java/src/main/java/com/datastax/astra/client/tables/commands/options/AlterTableOptions.java

@@ -27,30 +27,54 @@
 
 import static com.datastax.astra.client.tables.Table.DEFAULT_TABLE_SERIALIZER;
 
+/**
+ * Represents options for altering a table in a database schema.
+ * Extends {@link BaseOptions} to provide additional functionality for table alteration commands.
+ * <p>
+ * This class supports a fluent, chainable API using the {@link Accessors} annotation.
+ * Common options include specifying whether to include an "IF EXISTS" condition during the operation.
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>
+ * {@code
+ * AlterTableOptions options = new AlterTableOptions()
+ *     .ifExists(true);
+ * }
+ * </pre>
+ */
 @Setter
 @Accessors(fluent = true, chain = true)
 public class AlterTableOptions extends BaseOptions<AlterTableOptions> {
 
-    /** Improve syntax. */
+    /**
+     * A predefined instance of {@code AlterTableOptions} with the "IF EXISTS" condition enabled.
+     * This improves syntax for commonly used configurations.
+     */
     public static final AlterTableOptions IF_EXISTS = new AlterTableOptions().ifExists(true);
 
     /**
-     * Condition to upsert the table.
+     * Indicates whether the "IF EXISTS" condition should be applied to the table alteration.
+     * When {@code true}, the operation will only proceed if the table exists.
      */
-    boolean ifExists = true;
+    private boolean ifExists = true;
 
+    /**
+     * Constructs a new {@code AlterTableOptions} instance with default settings.
+     * Initializes the options with {@link CommandType#TABLE_ADMIN} and the default table serializer.
+     */
     public AlterTableOptions() {
         super(null, CommandType.TABLE_ADMIN, DEFAULT_TABLE_SERIALIZER, null);
     }
 
     /**
-     * Accessor for serialization.
+     * Retrieves the value of the "IF EXISTS" condition.
+     * This condition determines whether the operation should check for the existence of the table.
      *
-     * @return
-     *      accessor for serialization
+     * @return {@code true} if the "IF EXISTS" condition is enabled, {@code false} otherwise
      */
     public boolean isIfExists() {
         return ifExists;
     }
-
 }
+