change javadoc

Author: ekuvardin

query/src/main/java/tech/ydb/query/script/ScriptClient.java

@@ -1,5 +1,10 @@
 package tech.ydb.query.script;
 
+import java.util.concurrent.CompletableFuture;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+
 import tech.ydb.core.Result;
 import tech.ydb.core.Status;
 import tech.ydb.core.operation.Operation;
@@ -10,11 +15,6 @@
 import tech.ydb.query.script.settings.FindScriptSettings;
 import tech.ydb.table.query.Params;
 
-
-import javax.annotation.Nullable;
-
-import java.util.concurrent.CompletableFuture;
-
 /**
  * High-level API for executing YQL scripts and retrieving their results.
  * <p>
@@ -27,27 +27,21 @@
  *     <li>fetchQueryScriptStatus - wait for script execution</li>
  *     <li>fetchQueryScriptResult - fetch script result if necessary</li>
  * </ul>
- * </p>
- * Example with fetch
- * <p>
- *  <ul>
- *    <li> Operation<Status> operation = scriptClient.startQueryScript("select...",Params.of(...), executeScriptSettings).join()</li>
- *    <li>Status status = scriptClient.fetchQueryScriptStatus(operation, 1).join()</li>
- *    <li>Result<ScriptResultPart> resultPartResult = scriptClient.fetchQueryScriptResult(operation, null, fetchScriptSettings).join()</li>
- *    <li>ResultSetReader reader = scriptResultPart.getResultSetReader()</li>
- *    <li>reader.next()</li>
- *  </ul>
- * </p>
- *
- *  * Example without fetch
- *  * <p>
- *  *  <ul>
- *  *    <li> Status status =
- *                      scriptClient.startQueryScript("select...",Params.of(...), executeScriptSettings)
- *                                  .thenCompose(p -> scriptClient.fetchQueryScriptStatus(p, 1))
- *                                  .join()</li>
- *  *  </ul>
- *  * </p>
+ * <p>Example with fetch
+ * <pre>{@code
+ *      Operation<Status> operation = scriptClient.startQueryScript("select...",Params.of(...), executeScriptSettings).join())
+ *      Status status = scriptClient.fetchQueryScriptStatus(operation, 1).join()
+ *      Result< ScriptResultPart> resultPartResult = scriptClient.fetchQueryScriptResult(operation, null, fetchScriptSettings).join()
+ *      ResultSetReader reader = scriptResultPart.getResultSetReader()
+ *      reader.next()
+ * }</pre>
+ * <p>Example without fetch
+ * <pre>{@code
+ * Status status = scriptClient.startQueryScript("select...",Params.of(...), executeScriptSettings)
+ *                             .thenCompose(p -> scriptClient.fetchQueryScriptStatus(p, 1))
+ *                             .join()
+ * }</pre>
+ * <p>Author: Evgeny Kuvardin
  */
 public interface ScriptClient {
 
@@ -91,7 +85,8 @@ default CompletableFuture<Status> fetchQueryScriptStatus(Operation<Status> opera
      * @param settings  fetch configuration
      * @return future resolving to result part containing a result set fragment
      */
-    CompletableFuture<Result<ScriptResultPart>> fetchQueryScriptResult(Operation<Status> operation,
-                                                                       @Nullable ScriptResultPart previous, FetchScriptSettings settings);
+    CompletableFuture<Result<ScriptResultPart>> fetchQueryScriptResult(@Nonnull Operation<Status> operation,
+                                                                       @Nullable ScriptResultPart previous,
+                                                                       FetchScriptSettings settings);
 
 }

query/src/main/java/tech/ydb/query/script/ScriptRpc.java

@@ -1,13 +1,13 @@
 package tech.ydb.query.script;
 
+import java.util.concurrent.CompletableFuture;
+
 import tech.ydb.core.Result;
 import tech.ydb.core.Status;
 import tech.ydb.core.grpc.GrpcRequestSettings;
 import tech.ydb.core.operation.Operation;
 import tech.ydb.proto.query.YdbQuery;
 
-import java.util.concurrent.CompletableFuture;
-
 /**
  * Low-level RPC interface for executing YQL scripts and fetching their results using gRPC.
  * <p>

query/src/main/java/tech/ydb/query/script/impl/ScriptClientImpl.java

@@ -1,5 +1,12 @@
 package tech.ydb.query.script.impl;
 
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
+import javax.annotation.WillNotClose;
+
 import com.google.protobuf.Duration;
 
 import tech.ydb.core.Result;
@@ -13,19 +20,20 @@
 import tech.ydb.query.script.ScriptRpc;
 import tech.ydb.query.script.result.ScriptResultPart;
 import tech.ydb.query.script.settings.ExecuteScriptSettings;
-import tech.ydb.query.script.settings.FindScriptSettings;
 import tech.ydb.query.script.settings.FetchScriptSettings;
+import tech.ydb.query.script.settings.FindScriptSettings;
 import tech.ydb.query.settings.QueryExecMode;
 import tech.ydb.query.settings.QueryStatsMode;
 import tech.ydb.table.query.Params;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-import javax.annotation.WillNotClose;
-
-import java.util.UUID;
-import java.util.concurrent.CompletableFuture;
-
+/**
+ * Default implementation of {@link ScriptClient} using {@link ScriptRpc} for RPC calls.
+ * <p>
+ * Handles script execution lifecycle: starting scripts, polling their status,
+ * and retrieving result sets in streaming fashion.
+ *
+ * <p>Author: Evgeny Kuvardin
+ */
 public class ScriptClientImpl implements ScriptClient {
 
     private final ScriptRpc scriptRpc;
@@ -74,7 +82,8 @@ public CompletableFuture<Operation<Status>> startQueryScript(String query,
 
     @Override
     public CompletableFuture<Result<ScriptResultPart>> fetchQueryScriptResult(@Nonnull Operation<Status> operation,
-                                                                              @Nullable ScriptResultPart previous, FetchScriptSettings settings) {
+                                                                              @Nullable ScriptResultPart previous,
+                                                                              FetchScriptSettings settings) {
         YdbQuery.FetchScriptResultsRequest.Builder requestBuilder = YdbQuery.FetchScriptResultsRequest.newBuilder();
 
         if (previous != null && previous.getNextFetchToken() != null) {

query/src/main/java/tech/ydb/query/script/impl/ScriptRpcImpl.java

@@ -1,5 +1,9 @@
 package tech.ydb.query.script.impl;
 
+import java.util.concurrent.CompletableFuture;
+
+import javax.annotation.WillNotClose;
+
 import tech.ydb.core.Result;
 import tech.ydb.core.Status;
 import tech.ydb.core.grpc.GrpcRequestSettings;
@@ -12,17 +16,14 @@
 import tech.ydb.proto.query.v1.QueryServiceGrpc;
 import tech.ydb.query.script.ScriptRpc;
 
-import javax.annotation.WillNotClose;
-
-import java.util.concurrent.CompletableFuture;
-
 /**
  * Default gRPC-based implementation of {@link ScriptRpc}.
  * <p>
  * Uses {@link GrpcTransport} to communicate with YDB QueryService and OperationService.
  * Provides async unary calls for executing scripts and retrieving results or operation metadata.
+ *
+ * <p>Author: Evgeny Kuvardin
  */
-
 public class ScriptRpcImpl implements ScriptRpc {
 
     private final GrpcTransport transport;

query/src/main/java/tech/ydb/query/script/result/ScriptResultPart.java

@@ -5,6 +5,17 @@
 import tech.ydb.table.result.ResultSetReader;
 import tech.ydb.table.result.impl.ProtoValueReaders;
 
+/**
+ * Represents a single portion of script execution results.
+ * <p>
+ * Contains:
+ * <ul>
+ *     <li>a result set reader for the retrieved rows</li>
+ *     <li>index of the result set within the script</li>
+ *     <li>fetch token for retrieving the next portion</li>
+ *     <li>issues returned by the server</li>
+ * </ul>
+ */
 public class ScriptResultPart {
     private final ResultSetReader resultSetReader;
     private final long resultSetIndex;

query/src/main/java/tech/ydb/query/script/settings/ExecuteScriptSettings.java

@@ -7,9 +7,10 @@
 import tech.ydb.query.settings.QueryStatsMode;
 
 /**
- * Settings for configuring script execution requests.
+ * Settings controlling execution of a YQL script.
  * <p>
- * Used by {@code QuerySession.executeScript(...)} and similar APIs.
+ * Used to specify execution mode, statistics collection level,
+ * result TTL, and resource pool assignment.
  *
  * <p>Author: Evgeny Kuvardin
  */

query/src/main/java/tech/ydb/query/script/settings/FetchScriptSettings.java

@@ -4,6 +4,7 @@
 
 /**
  * Settings for configuring the fetch phase of a previously executed YQL script.
+ * Take a note that script should be executed successfully before fetch result
  * <p>
  * These settings define which operation results to fetch, pagination options,
  * row limits, and which result set index to retrieve.
@@ -44,6 +45,9 @@ public long getSetResultSetIndex() {
         return setResultSetIndex;
     }
 
+    /**
+     * Creates a new builder configured for asynchronous operation requests.
+     */
     public static Builder newBuilder() {
         return new Builder();
     }

query/src/main/java/tech/ydb/query/script/settings/FindScriptSettings.java

@@ -2,6 +2,13 @@
 
 import tech.ydb.core.settings.OperationSettings;
 
+/**
+ * Settings for retrieving metadata of a previously started script operation.
+ * <p>
+ * Extends {@link OperationSettings} and enables async fetching by default.
+ *
+ * <p>Author: Evgeny Kuvardin
+ */
 public class FindScriptSettings extends OperationSettings {
 
     private FindScriptSettings(Builder builder) {