JAVA-2542: Improve the javadocs of methods in CqlSession (scylladb#34)

Author: tomekl007

changelog/README.md

@@ -8,6 +8,7 @@ This version brings in all functionality that was formerly only in the DataStax
 such as the built-in support for reactive programming. Going forward, all new features will be 
 implemented in this single driver.
 
+- [documentation] JAVA-2542: JAVA-2542: Improve the javadocs of methods in CqlSession
 - [documentation] JAVA-2609: Add docs for proxy authentication to unified driver
 - [improvement] JAVA-2554: Improve efficiency of InsightsClient by improving supportsInsights check
 - [improvement] JAVA-2601: Inject Google Tag Manager scripts in generated API documentation

core/src/main/java/com/datastax/dse/driver/api/core/graph/GraphSession.java

@@ -53,6 +53,8 @@ public interface GraphSession extends Session {
    * Apache Cassandra® cluster will result in a runtime error.
    *
    * @see GraphResultSet
+   * @param graphStatement the graph query to execute (that can be any {@code GraphStatement}).
+   * @return the result of the graph query. That result will never be null but can be empty.
    */
   @NonNull
   default GraphResultSet execute(@NonNull GraphStatement<?> graphStatement) {
@@ -70,6 +72,8 @@ default GraphResultSet execute(@NonNull GraphStatement<?> graphStatement) {
    *
    * @see #execute(GraphStatement)
    * @see AsyncGraphResultSet
+   * @param graphStatement the graph query to execute (that can be any {@code GraphStatement}).
+   * @return the {@code CompletionStage} on the result of the graph query.
    */
   @NonNull
   default CompletionStage<AsyncGraphResultSet> executeAsync(

core/src/main/java/com/datastax/oss/driver/api/core/CqlSession.java

@@ -56,6 +56,8 @@ public interface CqlSession
    * Returns a builder to create a new instance.
    *
    * <p>Note that this builder is mutable and not thread-safe.
+   *
+   * @return {@code CqlSessionBuilder} to create a new instance.
    */
   @NonNull
   static CqlSessionBuilder builder() {

core/src/main/java/com/datastax/oss/driver/api/core/cql/AsyncCqlSession.java

@@ -31,6 +31,9 @@ public interface AsyncCqlSession extends Session {
   /**
    * Executes a CQL statement asynchronously (the call returns as soon as the statement was sent,
    * generally before the result is available).
+   *
+   * @param statement the CQL query to execute (that can be any {@code Statement}).
+   * @return a {@code CompletionStage} that, once complete, will produce the async result set.
    */
   @NonNull
   default CompletionStage<AsyncResultSet> executeAsync(@NonNull Statement<?> statement) {
@@ -41,6 +44,9 @@ default CompletionStage<AsyncResultSet> executeAsync(@NonNull Statement<?> state
   /**
    * Executes a CQL statement asynchronously (the call returns as soon as the statement was sent,
    * generally before the result is available).
+   *
+   * @param query the CQL query to execute.
+   * @return a {@code CompletionStage} that, once complete, will produce the async result set.
    */
   @NonNull
   default CompletionStage<AsyncResultSet> executeAsync(@NonNull String query) {
@@ -57,6 +63,9 @@ default CompletionStage<AsyncResultSet> executeAsync(@NonNull String query) {
    *
    * <p>The result of this method is cached (see {@link SyncCqlSession#prepare(SimpleStatement)} for
    * more explanations).
+   *
+   * @param statement the CQL query to prepare (that can be any {@code SimpleStatement}).
+   * @return a {@code CompletionStage} that, once complete, will produce the prepared statement.
    */
   @NonNull
   default CompletionStage<PreparedStatement> prepareAsync(@NonNull SimpleStatement statement) {
@@ -71,6 +80,9 @@ default CompletionStage<PreparedStatement> prepareAsync(@NonNull SimpleStatement
    *
    * <p>The result of this method is cached (see {@link SyncCqlSession#prepare(SimpleStatement)} for
    * more explanations).
+   *
+   * @param query the CQL query string to prepare.
+   * @return a {@code CompletionStage} that, once complete, will produce the prepared statement.
    */
   @NonNull
   default CompletionStage<PreparedStatement> prepareAsync(@NonNull String query) {
@@ -90,6 +102,9 @@ default CompletionStage<PreparedStatement> prepareAsync(@NonNull String query) {
    *
    * <p>The result of this method is cached (see {@link SyncCqlSession#prepare(SimpleStatement)} for
    * more explanations).
+   *
+   * @param request the {@code PrepareRequest} to prepare.
+   * @return a {@code CompletionStage} that, once complete, will produce the prepared statement.
    */
   @NonNull
   default CompletionStage<PreparedStatement> prepareAsync(PrepareRequest request) {

core/src/main/java/com/datastax/oss/driver/api/core/cql/SyncCqlSession.java

@@ -15,6 +15,10 @@
  */
 package com.datastax.oss.driver.api.core.cql;
 
+import com.datastax.oss.driver.api.core.AllNodesFailedException;
+import com.datastax.oss.driver.api.core.servererrors.QueryExecutionException;
+import com.datastax.oss.driver.api.core.servererrors.QueryValidationException;
+import com.datastax.oss.driver.api.core.servererrors.SyntaxError;
 import com.datastax.oss.driver.api.core.session.Request;
 import com.datastax.oss.driver.api.core.session.Session;
 import com.datastax.oss.driver.internal.core.cql.DefaultPrepareRequest;
@@ -31,6 +35,17 @@ public interface SyncCqlSession extends Session {
   /**
    * Executes a CQL statement synchronously (the calling thread blocks until the result becomes
    * available).
+   *
+   * @param statement the CQL query to execute (that can be any {@link Statement}).
+   * @return the result of the query. That result will never be null but can be empty (and will be
+   *     for any non SELECT query).
+   * @throws AllNodesFailedException if no host in the cluster can be contacted successfully to
+   *     execute this query.
+   * @throws QueryExecutionException if the query triggered an execution exception, i.e. an
+   *     exception thrown by Cassandra when it cannot execute the query with the requested
+   *     consistency level successfully.
+   * @throws QueryValidationException if the query is invalid (syntax error, unauthorized or any
+   *     other validation problem).
    */
   @NonNull
   default ResultSet execute(@NonNull Statement<?> statement) {
@@ -41,6 +56,17 @@ default ResultSet execute(@NonNull Statement<?> statement) {
   /**
    * Executes a CQL statement synchronously (the calling thread blocks until the result becomes
    * available).
+   *
+   * @param query the CQL query to execute.
+   * @return the result of the query. That result will never be null but can be empty (and will be
+   *     for any non SELECT query).
+   * @throws AllNodesFailedException if no host in the cluster can be contacted successfully to
+   *     execute this query.
+   * @throws QueryExecutionException if the query triggered an execution exception, i.e. an
+   *     exception thrown by Cassandra when it cannot execute the query with the requested
+   *     consistency level successfully.
+   * @throws QueryValidationException if the query if invalid (syntax error, unauthorized or any
+   *     other validation problem).
    */
   @NonNull
   default ResultSet execute(@NonNull String query) {
@@ -110,6 +136,10 @@ default ResultSet execute(@NonNull String query) {
    *       query strings but different {@linkplain SimpleStatement#getConsistencyLevel() consistency
    *       levels} will yield distinct prepared statements.
    * </ul>
+   *
+   * @param statement the CQL query to execute (that can be any {@link SimpleStatement}).
+   * @return the prepared statement corresponding to {@code statement}.
+   * @throws SyntaxError if the syntax of the query to prepare is not correct.
    */
   @NonNull
   default PreparedStatement prepare(@NonNull SimpleStatement statement) {
@@ -124,6 +154,10 @@ default PreparedStatement prepare(@NonNull SimpleStatement statement) {
    *
    * <p>The result of this method is cached (see {@link #prepare(SimpleStatement)} for more
    * explanations).
+   *
+   * @param query the CQL string query to execute.
+   * @return the prepared statement corresponding to {@code query}.
+   * @throws SyntaxError if the syntax of the query to prepare is not correct.
    */
   @NonNull
   default PreparedStatement prepare(@NonNull String query) {
@@ -143,6 +177,10 @@ default PreparedStatement prepare(@NonNull String query) {
    *
    * <p>The result of this method is cached (see {@link #prepare(SimpleStatement)} for more
    * explanations).
+   *
+   * @param request the {@code PrepareRequest} to execute.
+   * @return the prepared statement corresponding to {@code request}.
+   * @throws SyntaxError if the syntax of the query to prepare is not correct.
    */
   @NonNull
   default PreparedStatement prepare(@NonNull PrepareRequest request) {