docs: fixing errors (#2536)

Java SDK team is installing a job to compile doc errors as part of - https://togithub.com/googleapis/java-spanner/pull/2515 . The job won't succeed with existing errors. This PR fixes the existing errors in docs.

Command for testing - `mvn javadoc:javadoc javadoc:test-javadoc -B -ntp`

Author: arpan14

.github/sync-repo-settings.yaml

@@ -10,6 +10,7 @@ branchProtectionRules:
     requiredStatusCheckContexts:
       - dependencies (17)
       - lint
+      - javadoc
       - units (8)
       - units (11)
       - 'Kokoro - Test: Integration'
@@ -28,6 +29,7 @@ branchProtectionRules:
     requiredStatusCheckContexts:
       - dependencies (11)
       - lint
+      - javadoc
       - units (7)
       - units (8)
       - units (11)
@@ -42,6 +44,7 @@ branchProtectionRules:
     requiredStatusCheckContexts:
       - dependencies (11)
       - lint
+      - javadoc
       - units (7)
       - units (8)
       - units (11)
@@ -56,6 +59,7 @@ branchProtectionRules:
     requiredStatusCheckContexts:
       - dependencies (11)
       - lint
+      - javadoc
       - units (7)
       - units (8)
       - units (11)
@@ -69,6 +73,7 @@ branchProtectionRules:
     requiresStrictStatusChecks: false
     requiredStatusCheckContexts:
       - lint
+      - javadoc
       - units (8)
       - units (11)
       - 'Kokoro - Test: Integration'
@@ -81,6 +86,7 @@ branchProtectionRules:
     requiresStrictStatusChecks: false
     requiredStatusCheckContexts:
       - lint
+      - javadoc
       - units (8)
       - units (11)
       - 'Kokoro - Test: Integration'
@@ -95,6 +101,7 @@ branchProtectionRules:
     requiresStrictStatusChecks: false
     requiredStatusCheckContexts:
       - lint
+      - javadoc
       - units (8)
       - units (11)
       - 'Kokoro - Test: Integration'
@@ -109,6 +116,7 @@ branchProtectionRules:
     requiresStrictStatusChecks: false
     requiredStatusCheckContexts:
       - lint
+      - javadoc
       - units (8)
       - units (11)
       - 'Kokoro - Test: Integration'

google-cloud-spanner/src/main/java/com/google/cloud/spanner/AbstractLazyInitializer.java

@@ -19,6 +19,8 @@
 /**
  * Generic {@link AbstractLazyInitializer} for any heavy-weight object that might throw an exception
  * during initialization. The underlying object is initialized at most once.
+ *
+ * @param <T> Object which is to be initialized lazily
  */
 public abstract class AbstractLazyInitializer<T> {
   private final Object lock = new Object();

google-cloud-spanner/src/main/java/com/google/cloud/spanner/AsyncResultSet.java

@@ -60,16 +60,17 @@ enum CallbackResponse {
     CONTINUE,
 
     /**
-     * Tell the cursor to suspend all callbacks until application calls {@link RowCursor#resume()}.
+     * Tell the cursor to suspend all callbacks until application calls {@link
+     * ForwardingAsyncResultSet#resume()}.
      */
     PAUSE,
 
     /**
      * Tell the cursor you are done receiving results, even if there are more results sitting in the
      * buffer. Once you return DONE, you will receive no further callbacks.
      *
-     * <p>Approximately equivalent to calling {@link RowCursor#cancel()}, and then returning {@code
-     * PAUSE}, but more clear, immediate, and idiomatic.
+     * <p>Approximately equivalent to calling {@link ForwardingAsyncResultSet#cancel()}, and then
+     * returning {@code PAUSE}, but more clear, immediate, and idiomatic.
      *
      * <p>It is legal to commit a transaction that owns this read before actually returning {@code
      * DONE}.
@@ -105,17 +106,18 @@ interface ReadyCallback {
    *   <li>Callback will stop being called once any of the following occurs:
    *       <ol>
    *         <li>Callback returns {@link CallbackResponse#DONE}.
-   *         <li>{@link ResultSet#tryNext()} returns {@link CursorState#DONE}.
-   *         <li>{@link ResultSet#tryNext()} throws an exception.
+   *         <li>{@link ForwardingAsyncResultSet#tryNext()} returns {@link CursorState#DONE}.
+   *         <li>{@link ForwardingAsyncResultSet#tryNext()} throws an exception.
    *       </ol>
-   *   <li>Callback may possibly be invoked after a call to {@link ResultSet#cancel()} call, but the
-   *       subsequent call to {@link #tryNext()} will yield a SpannerException.
+   *   <li>Callback may possibly be invoked after a call to {@link
+   *       ForwardingAsyncResultSet#cancel()} call, but the subsequent call to {@link #tryNext()}
+   *       will yield a SpannerException.
    *   <li>Spurious callbacks are possible where cursors are not actually ready. Typically callback
    *       should return {@link CallbackResponse#CONTINUE} any time it sees {@link
    *       CursorState#NOT_READY}.
    * </ul>
    *
-   * <h3>Flow Control</h3>
+   * <h4>Flow Control</h4>
    *
    * If no flow control is needed (say because result sizes are known in advance to be finite in
    * size) then async processing is simple. The following is a code example that transfers work from

google-cloud-spanner/src/main/java/com/google/cloud/spanner/AsyncRunner.java

@@ -18,6 +18,7 @@
 
 import com.google.api.core.ApiFuture;
 import com.google.cloud.Timestamp;
+import io.grpc.Status.Code;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.Executor;
 
@@ -40,8 +41,8 @@ interface AsyncWork<R> {
      * <p>In most cases, the implementation will not need to catch {@code SpannerException}s from
      * Spanner operations, instead letting these propagate to the framework. The transaction runner
      * will take appropriate action based on the type of exception. In particular, implementations
-     * should never catch an exception of type {@link SpannerErrors#isAborted}: these indicate that
-     * some reads may have returned inconsistent data and the transaction attempt must be aborted.
+     * should never catch an exception of type {@link Code#ABORTED}: these indicate that some reads
+     * may have returned inconsistent data and the transaction attempt must be aborted.
      *
      * @param txn the transaction
      * @return future over the result of the work

google-cloud-spanner/src/main/java/com/google/cloud/spanner/AsyncTransactionManager.java

@@ -18,7 +18,7 @@
 
 import com.google.api.core.ApiFuture;
 import com.google.cloud.Timestamp;
-import com.google.cloud.spanner.AsyncTransactionManager.TransactionContextFuture;
+import com.google.cloud.spanner.Options.TransactionOption;
 import com.google.cloud.spanner.TransactionManager.TransactionState;
 import com.google.common.util.concurrent.ListenableFuture;
 import com.google.common.util.concurrent.MoreExecutors;
@@ -43,7 +43,7 @@
  * so can cause resources to be leaked and deadlocks. Easiest way to guarantee this is by calling
  * {@link #close()} in a finally block.
  *
- * @see DatabaseClient#transactionManagerAsync()
+ * @see DatabaseClient#transactionManagerAsync(TransactionOption...)
  */
 public interface AsyncTransactionManager extends AutoCloseable {
   /**
@@ -91,10 +91,10 @@ Timestamp get(long timeout, TimeUnit unit)
 
   /**
    * {@link AsyncTransactionStep} is returned by {@link
-   * TransactionContextFuture#then(AsyncTransactionFunction)} and {@link
-   * AsyncTransactionStep#then(AsyncTransactionFunction)} and allows transaction steps that should
-   * be executed serially to be chained together. Each step can contain one or more statements that
-   * may execute in parallel.
+   * TransactionContextFuture#then(AsyncTransactionFunction, Executor)} and {@link
+   * AsyncTransactionStep#then(AsyncTransactionFunction, Executor)} and allows transaction steps
+   * that should be executed serially to be chained together. Each step can contain one or more
+   * statements that may execute in parallel.
    *
    * <p>Example usage:
    *
@@ -115,6 +115,9 @@ Timestamp get(long timeout, TimeUnit unit)
    *     executor)
    *   .commitAsync();
    * }</pre>
+   *
+   * @param <I>
+   * @param <O>
    */
   interface AsyncTransactionStep<I, O> extends ApiFuture<O> {
     /**
@@ -140,6 +143,9 @@ <RES> AsyncTransactionStep<O, RES> then(
    * a {@link TransactionContext} and the output value of the previous transaction step as its input
    * parameters. The method should return an {@link ApiFuture} that will return the result of this
    * step.
+   *
+   * @param <I>
+   * @param <O>
    */
   interface AsyncTransactionFunction<I, O> {
     /**
@@ -151,16 +157,16 @@ interface AsyncTransactionFunction<I, O> {
      * @param input the result of the previous transaction step.
      * @return an {@link ApiFuture} that will return the result of this step, and that will be the
      *     input of the next transaction step. This method should never return <code>null</code>.
-     *     Instead, if the method does not have a return value, the method should return {@link
-     *     ApiFutures#immediateFuture(null)}.
+     *     Instead, if the method does not have a return value, the method should return
+     *     ApiFutures#immediateFuture(null).
      */
     ApiFuture<O> apply(TransactionContext txn, I input) throws Exception;
   }
 
   /**
    * Creates a new read write transaction. This must be called before doing any other operation and
    * can only be called once. To create a new transaction for subsequent retries, see {@link
-   * #resetForRetry()}.
+   * #resetForRetryAsync()}.
    */
   TransactionContextFuture beginAsync();
 

google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseAdminClient.java

@@ -137,7 +137,7 @@ default OperationFuture<Database, CreateDatabaseMetadata> createDatabase(
    * Database db = op.waitFor().getResult();
    * }</pre>
    *
-   * @see also #createDatabase(String, String, Iterable)
+   * @see #createDatabase(String, String, Iterable)
    */
   OperationFuture<Database, CreateDatabaseMetadata> createDatabase(
       Database database, Iterable<String> statements) throws SpannerException;

google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java

@@ -368,8 +368,8 @@ CommitResponse writeAtLeastOnceWithOptions(
 
   /**
    * Returns a transaction manager which allows manual management of transaction lifecycle. This API
-   * is meant for advanced users. Most users should instead use the {@link #readWriteTransaction()}
-   * API instead.
+   * is meant for advanced users. Most users should instead use the {@link
+   * #readWriteTransaction(TransactionOption...)} API instead.
    *
    * <p>Example of using {@link TransactionManager}.
    *
@@ -412,7 +412,7 @@ CommitResponse writeAtLeastOnceWithOptions(
    *
    * <p>Example of a read write transaction.
    *
-   * <pre> <code>
+   * <pre>{@code
    * Executor executor = Executors.newSingleThreadExecutor();
    * final long singerId = my_singer_id;
    * AsyncRunner runner = client.runAsync();
@@ -432,7 +432,7 @@ CommitResponse writeAtLeastOnceWithOptions(
    *                   .build());
    *         },
    *         executor);
-   * </code></pre>
+   * }</pre>
    *
    * Options for a transaction can include:
    *
@@ -449,7 +449,7 @@ CommitResponse writeAtLeastOnceWithOptions(
   /**
    * Returns an asynchronous transaction manager which allows manual management of transaction
    * lifecycle. This API is meant for advanced users. Most users should instead use the {@link
-   * #runAsync()} API instead.
+   * #runAsync(TransactionOption...)} API instead.
    *
    * <p>Example of using {@link AsyncTransactionManager}.
    *
@@ -514,12 +514,13 @@ CommitResponse writeAtLeastOnceWithOptions(
    *
    * <p>Partitioned DML updates are used to execute a single DML statement with a different
    * execution strategy that provides different, and often better, scalability properties for large,
-   * table-wide operations than DML in a {@link #readWriteTransaction()} transaction. Smaller scoped
-   * statements, such as an OLTP workload, should prefer using {@link
-   * TransactionContext#executeUpdate(Statement)} with {@link #readWriteTransaction()}.
+   * table-wide operations than DML in a {@link #readWriteTransaction(TransactionOption...)}
+   * transaction. Smaller scoped statements, such as an OLTP workload, should prefer using {@link
+   * TransactionContext#executeUpdate(Statement,UpdateOption...)} with {@link
+   * #readWriteTransaction(TransactionOption...)}.
    *
    * <p>That said, Partitioned DML is not a drop-in replacement for standard DML used in {@link
-   * #readWriteTransaction()}.
+   * #readWriteTransaction(TransactionOption...)}.
    *
    * <ul>
    *   <li>The DML statement must be fully-partitionable. Specifically, the statement must be

google-cloud-spanner/src/main/java/com/google/cloud/spanner/InstanceConfigInfo.java

@@ -117,9 +117,9 @@ public List<ReplicaInfo> getOptionalReplicas() {
   }
 
   /**
-   * Base configuration, e.g. projects/<project_name>/instanceConfigs/nam3, based on which this
-   * configuration is created. Only set for user managed configurations. The base config must refer
-   * to a configuration of type GOOGLE_MANAGED.
+   * Base configuration, e.g. {@code projects/<project_name>/instanceConfigs/nam3}, based on which
+   * this configuration is created. Only set for user managed configurations. The base config must
+   * refer to a configuration of type GOOGLE_MANAGED.
    */
   public InstanceConfigInfo getBaseConfig() {
     return baseConfig;

google-cloud-spanner/src/main/java/com/google/cloud/spanner/Operation.java

@@ -32,7 +32,12 @@
 import javax.annotation.Nullable;
 import org.threeten.bp.Duration;
 
-/** Represents a long running operation. */
+/**
+ * Represents a long-running operation.
+ *
+ * @param <R>
+ * @param <M>
+ */
 // TODO(user): Implement other operations on Operation.
 public class Operation<R, M> {
 

google-cloud-spanner/src/main/java/com/google/cloud/spanner/Options.java

@@ -156,9 +156,9 @@ public static ListOption pageSize(int pageSize) {
   }
 
   /**
-   * If this is for a partitioned read & query and this field is set to `true`, the request will be
-   * executed via Spanner independent compute resources. The method is available in Beta mode (and
-   * is not generally available now).
+   * If this is for a partitioned read and query and this field is set to `true`, the request will
+   * be executed via Spanner independent compute resources. The method is available in Beta mode
+   * (and is not generally available now).
    */
   @BetaApi
   public static DataBoostQueryOption dataBoostEnabled(Boolean dataBoostEnabled) {

google-cloud-spanner/src/main/java/com/google/cloud/spanner/Session.java

@@ -18,6 +18,7 @@
 
 import com.google.api.core.ApiFuture;
 import com.google.api.core.InternalApi;
+import com.google.cloud.spanner.Options.TransactionOption;
 import com.google.protobuf.Empty;
 
 /**
@@ -48,11 +49,12 @@ public interface Session extends DatabaseClient, AutoCloseable {
   String getName();
 
   /**
-   * Prepares a transaction for use by a subsequent {@link #readWriteTransaction()} or {@link
-   * #write(Iterable)} call. It is not necessary to call this method before running a transaction or
-   * performing a write, but doing so may allow one round trip of the protocol to be performed in
-   * advance; calling this method on an idle session that is expected to execute a transaction or
-   * write in the near future may reduce the latency of the subsequent transaction/write.
+   * Prepares a transaction for use by a subsequent {@link
+   * DatabaseClient#readWriteTransaction(TransactionOption...)} or {@link #write(Iterable)} call. It
+   * is not necessary to call this method before running a transaction or performing a write, but
+   * doing so may allow one round trip of the protocol to be performed in advance; calling this
+   * method on an idle session that is expected to execute a transaction or write in the near future
+   * may reduce the latency of the subsequent transaction/write.
    */
   void prepareReadWriteTransaction();
 

google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

@@ -32,6 +32,7 @@
 import com.google.cloud.grpc.GcpManagedChannelOptions;
 import com.google.cloud.grpc.GrpcTransportOptions;
 import com.google.cloud.spanner.Options.QueryOption;
+import com.google.cloud.spanner.Options.UpdateOption;
 import com.google.cloud.spanner.admin.database.v1.DatabaseAdminSettings;
 import com.google.cloud.spanner.admin.database.v1.stub.DatabaseAdminStubSettings;
 import com.google.cloud.spanner.admin.instance.v1.InstanceAdminSettings;
@@ -134,10 +135,7 @@ public class SpannerOptions extends ServiceOptions<Spanner, SpannerOptions> {
   private final String compressorName;
   private final boolean leaderAwareRoutingEnabled;
 
-  /**
-   * Interface that can be used to provide {@link CallCredentials} instead of {@link Credentials} to
-   * {@link SpannerOptions}.
-   */
+  /** Interface that can be used to provide {@link CallCredentials} to {@link SpannerOptions}. */
   public interface CallCredentialsProvider {
     /** Return the {@link CallCredentials} to use for a gRPC call. */
     CallCredentials getCallCredentials();
@@ -970,7 +968,7 @@ public DatabaseAdminStubSettings.Builder getDatabaseAdminStubSettingsBuilder() {
 
     /**
      * Sets a timeout specifically for Partitioned DML statements executed through {@link
-     * DatabaseClient#executePartitionedUpdate(Statement)}. The default is 2 hours.
+     * DatabaseClient#executePartitionedUpdate(Statement, UpdateOption...)}. The default is 2 hours.
      */
     public Builder setPartitionedDmlTimeout(Duration timeout) {
       this.partitionedDmlTimeout = timeout;
@@ -1065,9 +1063,7 @@ QueryOptions getEnvironmentQueryOptions() {
 
     /**
      * Sets a {@link CallCredentialsProvider} that can deliver {@link CallCredentials} to use on a
-     * per-gRPC basis. Any credentials returned by this {@link CallCredentialsProvider} will have
-     * preference above any {@link Credentials} that may have been set on the {@link SpannerOptions}
-     * instance.
+     * per-gRPC basis.
      */
     public Builder setCallCredentialsProvider(CallCredentialsProvider callCredentialsProvider) {
       this.callCredentialsProvider = callCredentialsProvider;