Skip to content
This repository was archived by the owner on Apr 7, 2026. It is now read-only.

Commit 8aa407f

Browse files
author
Arpan Mishra
authored
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`
1 parent a72ce86 commit 8aa407f

24 files changed

Lines changed: 371 additions & 211 deletions

‎.github/sync-repo-settings.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ branchProtectionRules:
1010
requiredStatusCheckContexts:
1111
- dependencies (17)
1212
- lint
13+
- javadoc
1314
- units (8)
1415
- units (11)
1516
- 'Kokoro - Test: Integration'
@@ -28,6 +29,7 @@ branchProtectionRules:
2829
requiredStatusCheckContexts:
2930
- dependencies (11)
3031
- lint
32+
- javadoc
3133
- units (7)
3234
- units (8)
3335
- units (11)
@@ -42,6 +44,7 @@ branchProtectionRules:
4244
requiredStatusCheckContexts:
4345
- dependencies (11)
4446
- lint
47+
- javadoc
4548
- units (7)
4649
- units (8)
4750
- units (11)
@@ -56,6 +59,7 @@ branchProtectionRules:
5659
requiredStatusCheckContexts:
5760
- dependencies (11)
5861
- lint
62+
- javadoc
5963
- units (7)
6064
- units (8)
6165
- units (11)
@@ -69,6 +73,7 @@ branchProtectionRules:
6973
requiresStrictStatusChecks: false
7074
requiredStatusCheckContexts:
7175
- lint
76+
- javadoc
7277
- units (8)
7378
- units (11)
7479
- 'Kokoro - Test: Integration'
@@ -81,6 +86,7 @@ branchProtectionRules:
8186
requiresStrictStatusChecks: false
8287
requiredStatusCheckContexts:
8388
- lint
89+
- javadoc
8490
- units (8)
8591
- units (11)
8692
- 'Kokoro - Test: Integration'
@@ -95,6 +101,7 @@ branchProtectionRules:
95101
requiresStrictStatusChecks: false
96102
requiredStatusCheckContexts:
97103
- lint
104+
- javadoc
98105
- units (8)
99106
- units (11)
100107
- 'Kokoro - Test: Integration'
@@ -109,6 +116,7 @@ branchProtectionRules:
109116
requiresStrictStatusChecks: false
110117
requiredStatusCheckContexts:
111118
- lint
119+
- javadoc
112120
- units (8)
113121
- units (11)
114122
- 'Kokoro - Test: Integration'

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@
1919
/**
2020
* Generic {@link AbstractLazyInitializer} for any heavy-weight object that might throw an exception
2121
* during initialization. The underlying object is initialized at most once.
22+
*
23+
* @param <T> Object which is to be initialized lazily
2224
*/
2325
public abstract class AbstractLazyInitializer<T> {
2426
private final Object lock = new Object();

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

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -60,16 +60,17 @@ enum CallbackResponse {
6060
CONTINUE,
6161

6262
/**
63-
* Tell the cursor to suspend all callbacks until application calls {@link RowCursor#resume()}.
63+
* Tell the cursor to suspend all callbacks until application calls {@link
64+
* ForwardingAsyncResultSet#resume()}.
6465
*/
6566
PAUSE,
6667

6768
/**
6869
* Tell the cursor you are done receiving results, even if there are more results sitting in the
6970
* buffer. Once you return DONE, you will receive no further callbacks.
7071
*
71-
* <p>Approximately equivalent to calling {@link RowCursor#cancel()}, and then returning {@code
72-
* PAUSE}, but more clear, immediate, and idiomatic.
72+
* <p>Approximately equivalent to calling {@link ForwardingAsyncResultSet#cancel()}, and then
73+
* returning {@code PAUSE}, but more clear, immediate, and idiomatic.
7374
*
7475
* <p>It is legal to commit a transaction that owns this read before actually returning {@code
7576
* DONE}.
@@ -105,17 +106,18 @@ interface ReadyCallback {
105106
* <li>Callback will stop being called once any of the following occurs:
106107
* <ol>
107108
* <li>Callback returns {@link CallbackResponse#DONE}.
108-
* <li>{@link ResultSet#tryNext()} returns {@link CursorState#DONE}.
109-
* <li>{@link ResultSet#tryNext()} throws an exception.
109+
* <li>{@link ForwardingAsyncResultSet#tryNext()} returns {@link CursorState#DONE}.
110+
* <li>{@link ForwardingAsyncResultSet#tryNext()} throws an exception.
110111
* </ol>
111-
* <li>Callback may possibly be invoked after a call to {@link ResultSet#cancel()} call, but the
112-
* subsequent call to {@link #tryNext()} will yield a SpannerException.
112+
* <li>Callback may possibly be invoked after a call to {@link
113+
* ForwardingAsyncResultSet#cancel()} call, but the subsequent call to {@link #tryNext()}
114+
* will yield a SpannerException.
113115
* <li>Spurious callbacks are possible where cursors are not actually ready. Typically callback
114116
* should return {@link CallbackResponse#CONTINUE} any time it sees {@link
115117
* CursorState#NOT_READY}.
116118
* </ul>
117119
*
118-
* <h3>Flow Control</h3>
120+
* <h4>Flow Control</h4>
119121
*
120122
* If no flow control is needed (say because result sizes are known in advance to be finite in
121123
* 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‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818

1919
import com.google.api.core.ApiFuture;
2020
import com.google.cloud.Timestamp;
21+
import io.grpc.Status.Code;
2122
import java.util.concurrent.ExecutionException;
2223
import java.util.concurrent.Executor;
2324

@@ -40,8 +41,8 @@ interface AsyncWork<R> {
4041
* <p>In most cases, the implementation will not need to catch {@code SpannerException}s from
4142
* Spanner operations, instead letting these propagate to the framework. The transaction runner
4243
* will take appropriate action based on the type of exception. In particular, implementations
43-
* should never catch an exception of type {@link SpannerErrors#isAborted}: these indicate that
44-
* some reads may have returned inconsistent data and the transaction attempt must be aborted.
44+
* should never catch an exception of type {@link Code#ABORTED}: these indicate that some reads
45+
* may have returned inconsistent data and the transaction attempt must be aborted.
4546
*
4647
* @param txn the transaction
4748
* @return future over the result of the work

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

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818

1919
import com.google.api.core.ApiFuture;
2020
import com.google.cloud.Timestamp;
21-
import com.google.cloud.spanner.AsyncTransactionManager.TransactionContextFuture;
21+
import com.google.cloud.spanner.Options.TransactionOption;
2222
import com.google.cloud.spanner.TransactionManager.TransactionState;
2323
import com.google.common.util.concurrent.ListenableFuture;
2424
import com.google.common.util.concurrent.MoreExecutors;
@@ -43,7 +43,7 @@
4343
* so can cause resources to be leaked and deadlocks. Easiest way to guarantee this is by calling
4444
* {@link #close()} in a finally block.
4545
*
46-
* @see DatabaseClient#transactionManagerAsync()
46+
* @see DatabaseClient#transactionManagerAsync(TransactionOption...)
4747
*/
4848
public interface AsyncTransactionManager extends AutoCloseable {
4949
/**
@@ -91,10 +91,10 @@ Timestamp get(long timeout, TimeUnit unit)
9191

9292
/**
9393
* {@link AsyncTransactionStep} is returned by {@link
94-
* TransactionContextFuture#then(AsyncTransactionFunction)} and {@link
95-
* AsyncTransactionStep#then(AsyncTransactionFunction)} and allows transaction steps that should
96-
* be executed serially to be chained together. Each step can contain one or more statements that
97-
* may execute in parallel.
94+
* TransactionContextFuture#then(AsyncTransactionFunction, Executor)} and {@link
95+
* AsyncTransactionStep#then(AsyncTransactionFunction, Executor)} and allows transaction steps
96+
* that should be executed serially to be chained together. Each step can contain one or more
97+
* statements that may execute in parallel.
9898
*
9999
* <p>Example usage:
100100
*
@@ -115,6 +115,9 @@ Timestamp get(long timeout, TimeUnit unit)
115115
* executor)
116116
* .commitAsync();
117117
* }</pre>
118+
*
119+
* @param <I>
120+
* @param <O>
118121
*/
119122
interface AsyncTransactionStep<I, O> extends ApiFuture<O> {
120123
/**
@@ -140,6 +143,9 @@ <RES> AsyncTransactionStep<O, RES> then(
140143
* a {@link TransactionContext} and the output value of the previous transaction step as its input
141144
* parameters. The method should return an {@link ApiFuture} that will return the result of this
142145
* step.
146+
*
147+
* @param <I>
148+
* @param <O>
143149
*/
144150
interface AsyncTransactionFunction<I, O> {
145151
/**
@@ -151,16 +157,16 @@ interface AsyncTransactionFunction<I, O> {
151157
* @param input the result of the previous transaction step.
152158
* @return an {@link ApiFuture} that will return the result of this step, and that will be the
153159
* input of the next transaction step. This method should never return <code>null</code>.
154-
* Instead, if the method does not have a return value, the method should return {@link
155-
* ApiFutures#immediateFuture(null)}.
160+
* Instead, if the method does not have a return value, the method should return
161+
* ApiFutures#immediateFuture(null).
156162
*/
157163
ApiFuture<O> apply(TransactionContext txn, I input) throws Exception;
158164
}
159165

160166
/**
161167
* Creates a new read write transaction. This must be called before doing any other operation and
162168
* can only be called once. To create a new transaction for subsequent retries, see {@link
163-
* #resetForRetry()}.
169+
* #resetForRetryAsync()}.
164170
*/
165171
TransactionContextFuture beginAsync();
166172

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ default OperationFuture<Database, CreateDatabaseMetadata> createDatabase(
137137
* Database db = op.waitFor().getResult();
138138
* }</pre>
139139
*
140-
* @see also #createDatabase(String, String, Iterable)
140+
* @see #createDatabase(String, String, Iterable)
141141
*/
142142
OperationFuture<Database, CreateDatabaseMetadata> createDatabase(
143143
Database database, Iterable<String> statements) throws SpannerException;

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

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -368,8 +368,8 @@ CommitResponse writeAtLeastOnceWithOptions(
368368

369369
/**
370370
* Returns a transaction manager which allows manual management of transaction lifecycle. This API
371-
* is meant for advanced users. Most users should instead use the {@link #readWriteTransaction()}
372-
* API instead.
371+
* is meant for advanced users. Most users should instead use the {@link
372+
* #readWriteTransaction(TransactionOption...)} API instead.
373373
*
374374
* <p>Example of using {@link TransactionManager}.
375375
*
@@ -412,7 +412,7 @@ CommitResponse writeAtLeastOnceWithOptions(
412412
*
413413
* <p>Example of a read write transaction.
414414
*
415-
* <pre> <code>
415+
* <pre>{@code
416416
* Executor executor = Executors.newSingleThreadExecutor();
417417
* final long singerId = my_singer_id;
418418
* AsyncRunner runner = client.runAsync();
@@ -432,7 +432,7 @@ CommitResponse writeAtLeastOnceWithOptions(
432432
* .build());
433433
* },
434434
* executor);
435-
* </code></pre>
435+
* }</pre>
436436
*
437437
* Options for a transaction can include:
438438
*
@@ -449,7 +449,7 @@ CommitResponse writeAtLeastOnceWithOptions(
449449
/**
450450
* Returns an asynchronous transaction manager which allows manual management of transaction
451451
* lifecycle. This API is meant for advanced users. Most users should instead use the {@link
452-
* #runAsync()} API instead.
452+
* #runAsync(TransactionOption...)} API instead.
453453
*
454454
* <p>Example of using {@link AsyncTransactionManager}.
455455
*
@@ -514,12 +514,13 @@ CommitResponse writeAtLeastOnceWithOptions(
514514
*
515515
* <p>Partitioned DML updates are used to execute a single DML statement with a different
516516
* execution strategy that provides different, and often better, scalability properties for large,
517-
* table-wide operations than DML in a {@link #readWriteTransaction()} transaction. Smaller scoped
518-
* statements, such as an OLTP workload, should prefer using {@link
519-
* TransactionContext#executeUpdate(Statement)} with {@link #readWriteTransaction()}.
517+
* table-wide operations than DML in a {@link #readWriteTransaction(TransactionOption...)}
518+
* transaction. Smaller scoped statements, such as an OLTP workload, should prefer using {@link
519+
* TransactionContext#executeUpdate(Statement,UpdateOption...)} with {@link
520+
* #readWriteTransaction(TransactionOption...)}.
520521
*
521522
* <p>That said, Partitioned DML is not a drop-in replacement for standard DML used in {@link
522-
* #readWriteTransaction()}.
523+
* #readWriteTransaction(TransactionOption...)}.
523524
*
524525
* <ul>
525526
* <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‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -117,9 +117,9 @@ public List<ReplicaInfo> getOptionalReplicas() {
117117
}
118118

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

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,12 @@
3232
import javax.annotation.Nullable;
3333
import org.threeten.bp.Duration;
3434

35-
/** Represents a long running operation. */
35+
/**
36+
* Represents a long-running operation.
37+
*
38+
* @param <R>
39+
* @param <M>
40+
*/
3641
// TODO(user): Implement other operations on Operation.
3742
public class Operation<R, M> {
3843

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -156,9 +156,9 @@ public static ListOption pageSize(int pageSize) {
156156
}
157157

158158
/**
159-
* If this is for a partitioned read & query and this field is set to `true`, the request will be
160-
* executed via Spanner independent compute resources. The method is available in Beta mode (and
161-
* is not generally available now).
159+
* If this is for a partitioned read and query and this field is set to `true`, the request will
160+
* be executed via Spanner independent compute resources. The method is available in Beta mode
161+
* (and is not generally available now).
162162
*/
163163
@BetaApi
164164
public static DataBoostQueryOption dataBoostEnabled(Boolean dataBoostEnabled) {

0 commit comments

Comments
 (0)