Update javadoc

query/src/main/java/tech/ydb/query/QueryClient.java

@@ -20,9 +20,9 @@ static Builder newClient(@WillNotClose GrpcTransport transport) {
     }
 
     /**
-     * Create new session asynchronous
-     *
-     * @param duration - timeout of operation completion waiting
+     * Return a future with {@link QuerySession} for further work. The session will be taken from the session pool if
+     * it has any idle session or will be created on the fly
+     * @param duration timeout of operation completion waiting
      * @return Return a new CompletableFuture that is completed with successful
      * Result when session created, and fail Result otherwise
      */

query/src/main/java/tech/ydb/query/QuerySession.java

@@ -8,10 +8,23 @@
 import tech.ydb.table.query.Params;
 
 /**
+ * Sessions are basic primitives for communicating with YDB Query Service. The are similar to connections for classic
+ * relational DBs. Sessions serve three main purposes:
+ *
+ * <ol>
+ * <li>Provide a flow control for DB requests with limited number of active channels.</li>
+ * <li>Distribute load evenly across multiple DB nodes.</li>
+ * <li>Store state for volatile stateful operations, such as short-living transactions.</li>
+ * </ol>
  *
  * @author Aleksandr Gorshenin
  */
 public interface QuerySession extends AutoCloseable {
+
+    /**
+     *
+     * @return identifier of session
+     */
     String getId();
 
     QueryTransaction currentTransaction();
@@ -20,15 +33,42 @@ public interface QuerySession extends AutoCloseable {
 
     CompletableFuture<Result<QueryTransaction>> beginTransaction(QueryTx txMode, BeginTransactionSettings settings);
 
+    /**
+     * Create {@link QueryStream} for executing query with specified {@link QueryTx}. The query can contain DML, DDL and
+     * DCL statements. Supported mix of different statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param tx transaction mode
+     * @param prms query parameters
+     * @param settings additional settings of query execution
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     QueryStream createQuery(String query, QueryTx tx, Params prms, ExecuteQuerySettings settings);
 
     @Override
     void close();
 
+    /**
+     * Create {@link QueryStream} for executing query with specified {@link QueryTx}. The query can contain DML, DDL and
+     * DCL statements. Supported mix of different statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param tx transaction mode
+     * @param prms query parameters
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQuery(String query, QueryTx tx, Params prms) {
         return createQuery(query, tx, prms, ExecuteQuerySettings.newBuilder().build());
     }
 
+    /**
+     * Create {@link QueryStream} for executing query with specified {@link QueryTx}. The query can contain DML, DDL and
+     * DCL statements. Supported mix of different statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param tx transaction mode
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQuery(String query, QueryTx tx) {
         return createQuery(query, tx, Params.empty(), ExecuteQuerySettings.newBuilder().build());
     }

query/src/main/java/tech/ydb/query/QueryStream.java

@@ -19,4 +19,7 @@ interface PartsHandler {
 
     void cancel();
 
+    default CompletableFuture<Result<QueryInfo>> execute() {
+        return execute(null);
+    };
 }

query/src/main/java/tech/ydb/query/QueryTransaction.java

@@ -11,37 +11,94 @@
 import tech.ydb.table.query.Params;
 
 /**
- *
+ * Short-living object allows transactional execution of several queries in one interactive transaction.
  * @author Aleksandr Gorshenin
  */
 public interface QueryTransaction {
+
+    /**
+     * Returns identifier of the transaction or null if the transaction is not active (not started/committed/rollbacked)
+     * @return identifier of the transaction or null if the transaction is not active
+     */
     String getId();
 
+    /**
+     * Returns {@link QueryTx} with mode of the transaction
+     * @return the transaction mode
+     */
     QueryTx getQueryTx();
 
     default boolean isActive() {
         return getId() != null;
     }
 
+    /**
+     * Returns {@link QuerySession} that was used for creating the transaction
+     * @return session that was used for creating the transaction
+     */
     QuerySession getSession();
 
     CompletableFuture<Result<QueryInfo>> commit(CommitTransactionSettings settings);
     CompletableFuture<Status> rollback(RollbackTransactionSettings settings);
 
+    /**
+     * Creates {@link QueryStream} for executing query in this transaction. The query can contain DML, DDL and DCL
+     * statements. Supported mix of different statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param commitAtEnd true if transaction must be committed after query execution
+     * @param prms query parameters
+     * @param settings additional settings of query execution
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     QueryStream createQuery(String query, boolean commitAtEnd, Params prms, ExecuteQuerySettings settings);
 
+    /**
+     * Creates {@link QueryStream} for executing query in this transaction. Transaction <i>will not be committed</i>
+     * after the execution of query. The query can contain DML, DDL and DCL statements. Supported mix of different
+     * statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQuery(String query) {
         return createQuery(query, false, Params.empty(), ExecuteQuerySettings.newBuilder().build());
     }
 
+    /**
+     * Creates {@link QueryStream} for executing query in this transaction. Transaction <i>will not be committed</i>
+     * after the execution of query. The query can contain DML, DDL and DCL statements. Supported mix of different
+     * statement types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param prms query parameters
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQuery(String query, Params prms) {
         return createQuery(query, false, prms, ExecuteQuerySettings.newBuilder().build());
     }
 
+    /**
+     * Creates {@link QueryStream} for executing query in this transaction. Transaction <i>will be committed</i> after
+     * the execution of query. The query can contain DML, DDL and DCL statements. Supported mix of different statement
+     * types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQueryWithCommit(String query) {
         return createQuery(query, true, Params.empty(), ExecuteQuerySettings.newBuilder().build());
     }
 
+    /**
+     * Creates {@link QueryStream} for executing query in this transaction. Transaction <i>will be committed</i> after
+     * the execution of query. The query can contain DML, DDL and DCL statements. Supported mix of different statement
+     * types depends on the chosen transaction type.
+     *
+     * @param query text of query
+     * @param prms query parameters
+     * @return ready to execute an instance of {@link QueryStream}
+     */
     default QueryStream createQueryWithCommit(String query, Params prms) {
         return createQuery(query, true, prms, ExecuteQuerySettings.newBuilder().build());
     }