Addressed comments from Adrian.

src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudConnection.java

@@ -176,9 +176,18 @@ private DataCloudPreparedStatement getQueryPreparedStatement(String sql) {
     }
 
     /**
-     * Use getQueryStatus to determine if your query is "ready" then use this to get a collection of rows.
-     * When using {@link RowBased.Mode#FULL_RANGE} this method is not responsible for calculating the offset near the end of available rows,
-     * you must calculate the correct "pages" of offset and limit.
+     * Retrieves a collection of rows for the specified query once it is ready.
+     * Use {@link #getQueryStatus(String)} to check if the query has produced results or finished execution before calling this method.
+     * <p>
+     * When using {@link RowBased.Mode#FULL_RANGE}, this method does not handle pagination near the end of available rows.
+     * The caller is responsible for calculating the correct offset and limit to avoid out-of-range errors.
+     *
+     * @param queryId The identifier of the query to fetch results for.
+     * @param offset  The starting row offset.
+     * @param limit   The maximum number of rows to retrieve.
+     * @param mode    The fetching mode—either {@link RowBased.Mode#SINGLE_RPC} for a single request or
+     *                {@link RowBased.Mode#FULL_RANGE} to iterate through all available rows.
+     * @return A {@link DataCloudResultSet} containing the query results.
      */
     public DataCloudResultSet getRowBasedResultSet(String queryId, long offset, long limit, RowBased.Mode mode) {
         val iterator = RowBased.of(executor, queryId, offset, limit, mode);

src/main/java/com/salesforce/datacloud/jdbc/core/DataCloudQueryStatus.java

@@ -21,6 +21,15 @@
 import salesforce.cdp.hyperdb.v1.QueryInfo;
 import salesforce.cdp.hyperdb.v1.QueryStatus;
 
+/**
+ * Represents the status of a query.
+ * The {@link CompletionStatus} enum defines the possible states of the query, which are:
+ * <ul>
+ *   <li><b>RUNNING</b>: The query is still running or its status is unspecified.</li>
+ *   <li><b>RESULTS_PRODUCED</b>: The query has completed, and the results are ready for retrieval.</li>
+ *   <li><b>FINISHED</b>: The query has finished execution and its results have been persisted, guaranteed to be available until the expiration time.</li>
+ * </ul>
+ */
 @Value
 public class DataCloudQueryStatus {
     public enum CompletionStatus {
@@ -39,10 +48,20 @@ public enum CompletionStatus {
 
     CompletionStatus completionStatus;
 
-    public boolean isResultsProduced() {
+    /**
+     * Checks if the query's results have been produced.
+     *
+     * @return {@code true} if the query's results are available for retrieval, otherwise {@code false}.
+     */
+    public boolean isResultProduced() {
         return completionStatus == CompletionStatus.RESULTS_PRODUCED;
     }
 
+    /**
+     * Checks if the query execution is finished.
+     *
+     * @return {@code true} if the query has completed execution and results have been persisted, otherwise {@code false}.
+     */
     public boolean isExecutionFinished() {
         return completionStatus == CompletionStatus.FINISHED;
     }

src/test/java/com/salesforce/datacloud/jdbc/core/partial/RowBasedTest.java

@@ -122,7 +122,7 @@ void fetchWithRowsNearEndRange_FULL_RANGE() {
         final long rows;
         try (val conn = getHyperQueryConnection()) {
             rows = conn.getQueryStatus(small)
-                    .filter(t -> t.isResultsProduced() || t.isExecutionFinished())
+                    .filter(t -> t.isResultProduced() || t.isExecutionFinished())
                     .map(DataCloudQueryStatus::getRowCount)
                     .findFirst()
                     .orElseThrow(() -> new RuntimeException("boom"));
@@ -180,7 +180,7 @@ private void waitForQuery(String queryId) {
     }
 
     private boolean isReady(DataCloudConnection connection, String queryId) {
-        return connection.getQueryStatus(queryId).anyMatch(t -> t.isExecutionFinished() || t.isResultsProduced());
+        return connection.getQueryStatus(queryId).anyMatch(t -> t.isExecutionFinished() || t.isResultProduced());
     }
 
     private static List<Integer> rangeClosed(int start, int end) {