Improve CSOT API discoverability and document its effect on retrying#1939
Improve CSOT API discoverability and document its effect on retrying#1939vbabanin wants to merge 4 commits intomongodb:mainfrom
Conversation
- 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
# Conflicts: # driver-core/src/main/com/mongodb/MongoClientSettings.java # driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCluster.kt # driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt # driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt # driver-sync/src/main/com/mongodb/client/MongoCluster.java # driver-sync/src/main/com/mongodb/client/MongoCollection.java # driver-sync/src/main/com/mongodb/client/MongoDatabase.java
There was a problem hiding this comment.
Pull request overview
This PR improves discoverability and clarity of the Client-Side Operation Timeout (CSOT) API across driver modules by documenting the timeout precedence hierarchy, cross-linking paired timeout getter/setter methods, and clarifying how operation timeouts affect retry behavior.
Changes:
- Documented timeout precedence (“hierarchy”) for
getTimeout/withTimeoutacross sync, reactive-streams, Kotlin (sync/coroutine), and Scala APIs. - Documented how enabling retries interacts with operation timeout in
MongoClientSettings(retryWrites/retryReadsand timeout methods). - Added cross-references between timeout getters/setters via
@see.
Reviewed changes
Copilot reviewed 16 out of 18 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| driver-sync/src/main/com/mongodb/client/MongoDatabase.java | Adds timeout precedence list, retry/timeout interaction note, and @see cross-reference in timeout docs. |
| driver-sync/src/main/com/mongodb/client/MongoCollection.java | Same as above for collection-level timeouts. |
| driver-sync/src/main/com/mongodb/client/MongoCluster.java | Same as above for cluster-level timeouts. |
| driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MongoDatabase.java | Adds timeout precedence list, retry/timeout interaction note, and @see cross-reference for reactive DB API. |
| driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MongoCollection.java | Same as above for reactive collection API. |
| driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MongoCluster.java | Same as above for reactive cluster API. |
| driver-scala/src/main/scala/org/mongodb/scala/MongoDatabase.scala | Adds ScalaDoc timeout precedence + retry/timeout note + @see cross-references. |
| driver-scala/src/main/scala/org/mongodb/scala/MongoCollection.scala | Same as above for Scala collection wrapper. |
| driver-scala/src/main/scala/org/mongodb/scala/MongoCluster.scala | Same as above for Scala cluster wrapper. |
| driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt | Adds KDoc timeout precedence + retry/timeout note + @see cross-references. |
| driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt | Same as above for Kotlin sync collection wrapper. |
| driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCluster.kt | Same as above for Kotlin sync cluster wrapper. |
| driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoDatabase.kt | Adds KDoc timeout precedence + retry/timeout note + @see cross-references for coroutine wrapper. |
| driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCollection.kt | Same as above for coroutine collection wrapper. |
| driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCluster.kt | Same as above for coroutine cluster wrapper. |
| driver-core/src/main/com/mongodb/TransactionOptions.java | Javadoc formatting alignment for timeout note. |
| driver-core/src/main/com/mongodb/MongoClientSettings.java | Documents retry/timeout interaction for retryReads/retryWrites and adds timeout precedence lists + @see updates. |
| driver-core/src/main/com/mongodb/ClientSessionOptions.java | Javadoc formatting alignment for timeout note. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoDatabase.kt
Show resolved
Hide resolved
driver-kotlin-sync/src/main/kotlin/com/mongodb/kotlin/client/MongoCollection.kt
Outdated
Show resolved
Hide resolved
driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoDatabase.kt
Show resolved
Hide resolved
driver-kotlin-coroutine/src/main/kotlin/com/mongodb/kotlin/client/coroutine/MongoCollection.kt
Show resolved
Hide resolved
…t docs - Add imports for MongoClientSettings, ClientSessionOptions, and TransactionOptions to use short names in KDoc links instead of fully-qualified com.mongodb.* references - Shorten pre-existing fully-qualified KDoc references for ReadPreference, WriteConcern, and MongoClientSettings.getRetryWrites in MongoCollection and MongoCluster JAVA-6122
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/gridfs/GridFSBucket.java
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 19 out of 21 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * | ||
| * @param retryWrites sets if writes should be retried if they fail due to a network error. | ||
| * @return this | ||
| * @see #getRetryWrites() |
There was a problem hiding this comment.
This @see #getRetryWrites() tag is inside MongoClientSettings.Builder, but Builder doesn’t define getRetryWrites(). This will produce a broken/unresolved Javadoc reference. Consider updating it to reference the actual getter on MongoClientSettings (e.g., MongoClientSettings#getRetryWrites()).
| * @see #getRetryWrites() | |
| * @see MongoClientSettings#getRetryWrites() |
| * <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) |
There was a problem hiding this comment.
This @see #getRetryReads() tag is inside MongoClientSettings.Builder, but Builder doesn’t define getRetryReads(). This will produce a broken/unresolved Javadoc reference. Consider updating it to reference the actual getter on MongoClientSettings (e.g., MongoClientSettings#getRetryReads()).
| * @return this | ||
| * @since 5.2 | ||
| * @see #getTimeout | ||
| * @see #getTimeout(TimeUnit) |
There was a problem hiding this comment.
@see #getTimeout(TimeUnit) here is in MongoClientSettings.Builder, but Builder doesn’t have a getTimeout method. This will result in an unresolved Javadoc reference; consider changing it to point at MongoClientSettings#getTimeout(TimeUnit) instead.
| * @see #getTimeout(TimeUnit) | |
| * @see MongoClientSettings#getTimeout(TimeUnit) |
Changes:
JAVA-6122