docs: documents resume on update database ddl

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

@@ -172,6 +172,11 @@ public OperationFuture<Database, RestoreDatabaseMetadata> restoreDatabase(
    * problem like a `NULL` value in a column to which `NOT NULL` would be added). If a statement
    * fails, all subsequent statements in the batch are automatically cancelled.
    *
+   * <p>If an operation already exists with the given operation id, the operation will be resumed
+   * and the returned future will complete when the original operation finishes. See more
+   * information in {@link com.google.cloud.spanner.spi.v1.GapicSpannerRpc#updateDatabaseDdl(String,
+   * Iterable, String)}
+   *
    * <p>Example to update the database DDL.
    *
    * <pre>{@code

google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/GapicSpannerRpc.java

@@ -1037,6 +1037,17 @@ public Timestamp apply(Operation input) {
         NanoClock.getDefaultClock());
   }
 
+  /**
+   * If the update database ddl operation returns an ALREADY_EXISTS error, meaning the operation id
+   * used is already in flight, this method will simply resume the original operation. The returned
+   * future will be completed when the original operation finishes.
+   *
+   * <p>This mechanism is necessary, because the update database ddl can be retried. If a retryable
+   * failure occurs, the backend has already started processing the update database ddl operation
+   * with the given id and the library issues a retry, an ALREADY_EXISTS error will be returned. If
+   * we were to bubble this error up, it would be confusing for the caller, who used originally
+   * called the method with a new operation id.
+   */
   @Override
   public OperationFuture<Empty, UpdateDatabaseDdlMetadata> updateDatabaseDdl(
       final String databaseName,