Improve CSOT API discoverability and document its effect on retrying

- Add timeout hierarchy list to getTimeout/withTimeout Javadoc across all driver modules
  (sync, reactive-streams, Kotlin sync/coroutine, Scala) to improve discoverability
- Document the effect of operation timeout on retrying in retryWrites/retryReads and
  timeout methods on MongoClientSettings
- Add cross-references between paired getter/setter methods via @see tags

JAVA-6122

Author: vbabanin

driver-core/src/main/com/mongodb/MongoClientSettings.java

@@ -432,9 +432,13 @@ public Builder writeConcern(final WriteConcern writeConcern) {
          *
          * <p>Starting with the 3.11.0 release, the default value is true</p>
          *
+         * <p>If a {@linkplain #timeout(long, TimeUnit) timeout} is set, the driver may retry
+         * multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
+         *
          * @param retryWrites sets if writes should be retried if they fail due to a network error.
          * @return this
          * @see #getRetryWrites()
+         * @see #timeout(long, TimeUnit)
          * @mongodb.server.release 3.6
          */
         public Builder retryWrites(final boolean retryWrites) {
@@ -445,9 +449,13 @@ public Builder retryWrites(final boolean retryWrites) {
         /**
          * Sets whether reads should be retried if they fail due to a network error.
          *
+         * <p>If a {@linkplain #timeout(long, TimeUnit) timeout} is set, the driver may retry
+         * multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
+         *
          * @param retryReads sets if reads should be retried if they fail due to a network error.
          * @return this
          * @see #getRetryReads()
+         * @see #timeout(long, TimeUnit)
          * @since 3.11
          * @mongodb.server.release 3.6
          */
@@ -716,11 +724,25 @@ public Builder inetAddressResolver(@Nullable final InetAddressResolver inetAddre
          *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
          * </ul>
          *
+         * <p>The timeout can be set at the following levels (ordered by lowest precedence):
+         * <ul>
+         *   <li>{@link #timeout(long, TimeUnit) MongoClientSettings} (current)</li>
+         *   <li>{@code MongoCluster.withTimeout}</li>
+         *   <li>{@code MongoDatabase.withTimeout}</li>
+         *   <li>{@code MongoCollection.withTimeout}</li>
+         *   <li>{@link ClientSessionOptions.Builder#defaultTimeout(long, TimeUnit) ClientSessionOptions}</li>
+         *   <li>{@link TransactionOptions.Builder#timeout(Long, TimeUnit) TransactionOptions}</li>
+         * </ul>
+         * If not set at a given level, the timeout is inherited from the level above.
+         *
+         * <p>If {@linkplain #retryWrites(boolean) write} or {@linkplain #retryReads(boolean) read} retries are enabled,
+         * the driver may retry multiple times until the timeout expires.
+         *
          * @param timeout the timeout
          * @param timeUnit the time unit
          * @return this
          * @since 5.2
-         * @see #getTimeout
+         * @see #getTimeout(TimeUnit)
          */
         @Alpha(Reason.CLIENT)
         public Builder timeout(final long timeout, final TimeUnit timeUnit) {
@@ -789,7 +811,11 @@ public WriteConcern getWriteConcern() {
      *
      * <p>Starting with the 3.11.0 release, the default value is true</p>
      *
+     * <p>If a {@linkplain #getTimeout(TimeUnit) timeout} is set, the driver may retry
+     * multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
+     *
      * @return the retryWrites value
+     * @see #getTimeout(TimeUnit)
      * @mongodb.server.release 3.6
      */
     public boolean getRetryWrites() {
@@ -799,7 +825,11 @@ public boolean getRetryWrites() {
     /**
      * Returns true if reads should be retried if they fail due to a network error or other retryable error. The default value is true.
      *
+     * <p>If a {@linkplain #getTimeout(TimeUnit) timeout} is set, the driver may retry
+     * multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
+     *
      * @return the retryReads value
+     * @see #getTimeout(TimeUnit)
      * @since 3.11
      * @mongodb.server.release 3.6
      */
@@ -931,9 +961,23 @@ public ServerApi getServerApi() {
      *    <li>{@code > 0} The time limit to use for the full execution of an operation.</li>
      * </ul>
      *
+     * <p>The timeout can also be set at the following levels (ordered by lowest precedence):
+     * <ul>
+     *   <li>{@code MongoCluster.getTimeout}</li>
+     *   <li>{@code MongoDatabase.getTimeout}</li>
+     *   <li>{@code MongoCollection.getTimeout}</li>
+     *   <li>{@link ClientSessionOptions.Builder#defaultTimeout(long, TimeUnit) ClientSessionOptions}</li>
+     *   <li>{@link TransactionOptions.Builder#timeout(Long, TimeUnit) TransactionOptions}</li>
+     * </ul>
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * <p>If {@linkplain #getRetryWrites() write} or {@linkplain #getRetryReads() read} retries are enabled,
+     * the driver may retry multiple times until the timeout expires. Otherwise, at most one retry attempt is made.
+     *
      * @param timeUnit the time unit
      * @return the timeout in the given time unit
      * @since 5.2
+     * @see Builder#timeout(long, TimeUnit)
      */
     @Alpha(Reason.CLIENT)
     @Nullable

driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCluster.kt

@@ -81,7 +81,21 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout] (current)
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      */
     @Alpha(Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
@@ -134,10 +148,23 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout] (current)
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCluster instance with the set time limit for operations
-     * @see [MongoDatabase.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)

driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCollection.kt

@@ -105,7 +105,21 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout] (current)
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)
@@ -179,10 +193,23 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout] (current)
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCollection instance with the set time limit for operations
-     * @see [MongoCollection.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)

driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoDatabase.kt

@@ -73,7 +73,21 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout] (current)
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)
@@ -127,10 +141,23 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout] (current)
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoDatabase instance with the set time limit for operations
-     * @see [MongoDatabase.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)

driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCluster.kt

@@ -78,7 +78,21 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout] (current)
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      */
     @Alpha(Reason.CLIENT)
     public fun timeout(timeUnit: TimeUnit = TimeUnit.MILLISECONDS): Long? = wrapped.getTimeout(timeUnit)
@@ -131,10 +145,23 @@ public open class MongoCluster protected constructor(private val wrapped: JMongo
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout] (current)
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCluster instance with the set time limit for operations
-     * @see [MongoDatabase.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)

driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt

@@ -102,7 +102,21 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout] (current)
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)
@@ -176,10 +190,23 @@ public class MongoCollection<T : Any>(private val wrapped: JMongoCollection<T>)
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout]
+     * - [MongoCollection.withTimeout] (current)
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoCollection instance with the set time limit for operations
-     * @see [MongoCollection.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)

driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt

@@ -71,7 +71,21 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means infinite timeout.
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout] (current)
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @return the optional timeout duration
+     * @see [withTimeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)
@@ -125,10 +139,23 @@ public class MongoDatabase(private val wrapped: JMongoDatabase) {
      * - `0` means an infinite timeout
      * - `> 0` The time limit to use for the full execution of an operation.
      *
+     * The timeout can be set at the following levels (ordered by lowest precedence):
+     * - [MongoClientSettings.Builder.timeout]
+     * - [MongoCluster.withTimeout]
+     * - [MongoDatabase.withTimeout] (current)
+     * - [MongoCollection.withTimeout]
+     * - [com.mongodb.ClientSessionOptions.Builder.defaultTimeout]
+     * - [com.mongodb.TransactionOptions.Builder.timeout]
+     *
+     * If not set at a given level, the timeout is inherited from the level above.
+     *
+     * If [write][MongoClientSettings.Builder.retryWrites] or [read][MongoClientSettings.Builder.retryReads] retries are
+     * enabled, the driver may retry multiple times until the timeout expires.
+     *
      * @param timeout the timeout, which must be greater than or equal to 0
      * @param timeUnit the time unit, defaults to Milliseconds
      * @return a new MongoDatabase instance with the set time limit for operations
-     * @see [MongoDatabase.timeout]
+     * @see [timeout]
      * @since 5.2
      */
     @Alpha(Reason.CLIENT)