Do various doc and other minor improvements

bson/src/main/org/bson/ByteBuf.java

@@ -434,7 +434,7 @@ public interface ByteBuf  {
     ByteBuffer asNIO();
 
     /**
-     * Gets the current reference count, which starts at 0.
+     * Gets the current reference count, which is 1 for a new {@link ByteBuf}.
      *
      * @return the current count, which must be greater than or equal to 0
      */

bson/src/main/org/bson/io/OutputBuffer.java

@@ -122,7 +122,10 @@ public int size() {
      * Get a list of byte buffers that are prepared to be read from; in other words, whose position is 0 and whose limit is the number of
      * bytes that should read. <p> Note that the byte buffers may be read-only. </p>
      *
-     * @return the non-null list of byte buffers, in LITTLE_ENDIAN order
+     * @return the non-null list of byte buffers, in LITTLE_ENDIAN order. The returned {@link ByteBuf}s must eventually be
+     * {@linkplain ByteBuf#release() released} explicitly, calling {@link OutputBuffer#close()} may be not enough to release them.
+     * The caller must not use the {@link ByteBuf}s after closing this {@link OutputBuffer},
+     * though releasing them is allowed to be done after closing this {@link OutputBuffer}.
      */
     public abstract List<ByteBuf> getByteBuffers();
 

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

@@ -131,6 +131,7 @@
  * <p>Connection pool configuration:</p>
  * <ul>
  * <li>{@code maxPoolSize=n}: The maximum number of connections in the connection pool.</li>
+ * <li>{@code minPoolSize=n}: The minimum number of connections in the connection pool.</li>
  * <li>{@code waitQueueTimeoutMS=ms}: The maximum wait time in milliseconds that a thread may wait for a connection to
  * become available.</li>
  * <li>{@code maxConnecting=n}: The maximum number of connections a pool may be establishing concurrently.</li>

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

@@ -485,6 +485,7 @@ public Builder codecRegistry(final CodecRegistry codecRegistry) {
          *
          * @param streamFactoryFactory the stream factory factory
          * @return this
+         * @see #getStreamFactoryFactory()
          */
         public Builder streamFactoryFactory(final StreamFactoryFactory streamFactoryFactory) {
             this.streamFactoryFactory = notNull("streamFactoryFactory", streamFactoryFactory);
@@ -712,7 +713,7 @@ public MongoCredential getCredential() {
      * <p>Default is {@code WriteConcern.ACKNOWLEDGED}.</p>
      *
      * @return the write concern
-     * @see WriteConcern#ACKNOWLEDGED
+     * @see Builder#writeConcern(WriteConcern)
      */
     public WriteConcern getWriteConcern() {
         return writeConcern;
@@ -765,6 +766,7 @@ public CodecRegistry getCodecRegistry() {
      * Gets the factory to use to create a {@code StreamFactory}.
      *
      * @return the stream factory factory
+     * @see Builder#streamFactoryFactory(StreamFactoryFactory)
      */
     @Nullable
     public StreamFactoryFactory getStreamFactoryFactory() {
@@ -789,6 +791,7 @@ public List<CommandListener> getCommandListeners() {
      * <p>Default is null.</p>
      *
      * @return the application name, which may be null
+     * @see Builder#applicationName(String)
      * @mongodb.server.release 3.4
      */
     @Nullable
@@ -926,7 +929,7 @@ public SocketSettings getHeartbeatSocketSettings() {
      *
      * @return a ConnectionPoolSettings populated with the settings from this {@code MongoClientSettings} instance that relate to the
      * connection provider.
-     * @see ConnectionPoolSettings
+     * @see Builder#applyToConnectionPoolSettings(Block)
      */
     public ConnectionPoolSettings getConnectionPoolSettings() {
         return connectionPoolSettings;

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

@@ -33,7 +33,7 @@ public class MongoInterruptedException extends MongoException {
      * @param message the message
      * @param e the cause
      */
-    public MongoInterruptedException(@Nullable final String message, final Exception e) {
+    public MongoInterruptedException(@Nullable final String message, @Nullable final Exception e) {
         super(message, e);
     }
 }

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

@@ -229,6 +229,7 @@ public String getWString() {
      *
      * @param timeUnit the non-null time unit for the result
      * @return the WTimeout, which may be null if a wTimeout has not been specified
+     * @see #withWTimeout(long, TimeUnit)
      * @since 3.2
      * @mongodb.driver.manual core/write-concern/#timeouts wTimeout
      */
@@ -380,6 +381,7 @@ public WriteConcern withJournal(@Nullable final Boolean journal) {
      * @param wTimeout the wTimeout, which must be >= 0 and <= Integer.MAX_VALUE after conversion to milliseconds
      * @param timeUnit the non-null time unit to apply to wTimeout
      * @return the WriteConcern with the given wTimeout
+     * @see #getWTimeout(TimeUnit)
      * @since 3.2
      * @mongodb.driver.manual reference/write-concern/#wtimeout wtimeout option
      */

driver-core/src/main/com/mongodb/connection/ClusterSettings.java

@@ -222,6 +222,7 @@ public Builder mode(final ClusterConnectionMode mode) {
          *
          * @param requiredReplicaSetName the required replica set name.
          * @return this
+         * @see #getRequiredReplicaSetName()
          */
         public Builder requiredReplicaSetName(@Nullable final String requiredReplicaSetName) {
             this.requiredReplicaSetName = requiredReplicaSetName;
@@ -443,7 +444,9 @@ public ClusterType getRequiredClusterType() {
      * Gets the required replica set name.
      *
      * @return the required replica set name
+     * @see Builder#requiredReplicaSetName(String)
      */
+    @Nullable
     public String getRequiredReplicaSetName() {
         return requiredReplicaSetName;
     }

driver-core/src/main/com/mongodb/connection/SocketSettings.java

@@ -103,6 +103,7 @@ public Builder connectTimeout(final int connectTimeout, final TimeUnit timeUnit)
          * @param readTimeout the read timeout
          * @param timeUnit the time unit
          * @return this
+         * @see #getReadTimeout(TimeUnit)
          */
         public Builder readTimeout(final int readTimeout, final TimeUnit timeUnit) {
             this.readTimeoutMS = MILLISECONDS.convert(readTimeout, timeUnit);
@@ -177,6 +178,7 @@ public int getConnectTimeout(final TimeUnit timeUnit) {
      *
      * @param timeUnit the time unit to get the timeout in
      * @return the read timeout in the requested time unit, or 0 if there is no timeout
+     * @see Builder#readTimeout(int, TimeUnit)
      */
     public int getReadTimeout(final TimeUnit timeUnit) {
         return (int) timeUnit.convert(readTimeoutMS, MILLISECONDS);

driver-core/src/main/com/mongodb/internal/Timeout.java

@@ -164,14 +164,12 @@ long remainingNanos(final long currentNanos) {
      *             returning {@code false}. If such a discrepancy is observed,
      *             the result of the {@link #expired()} method should be preferred.
      *
-     * @throws UnsupportedOperationException If the timeout is {@linkplain #isInfinite() infinite}.
+     * @throws AssertionError If the timeout is {@linkplain #isInfinite() infinite}.
      * @see #remainingOrInfinite(TimeUnit)
      */
-    public long remaining(final TimeUnit unit) throws UnsupportedOperationException {
+    public long remaining(final TimeUnit unit) {
         assertNotNull(unit);
-        if (isInfinite()) {
-            throw new UnsupportedOperationException();
-        }
+        assertFalse(isInfinite());
         return isImmediate() ? 0 : convertRoundUp(remainingNanos(System.nanoTime()), unit);
     }
 

driver-core/src/main/com/mongodb/internal/connection/ConcurrentPool.java

@@ -528,7 +528,7 @@ private static void lockInterruptiblyUnfair(final ReentrantLock lock) throws Mon
                 lock.lockInterruptibly();
             } catch (InterruptedException e) {
                 Thread.currentThread().interrupt();
-                throw new MongoInterruptedException(null, new InterruptedException());
+                throw new MongoInterruptedException(null, e);
             }
         }
     }
@@ -542,7 +542,7 @@ static void lockUnfair(final ReentrantLock lock) {
 
     private static void throwIfInterrupted() throws MongoInterruptedException {
         if (Thread.currentThread().isInterrupted()) {
-            throw new MongoInterruptedException(null, new InterruptedException());
+            throw new MongoInterruptedException(null, null);
         }
     }
 }

driver-core/src/main/com/mongodb/internal/connection/ConnectionGenerationSupplier.java

@@ -16,9 +16,11 @@
 
 package com.mongodb.internal.connection;
 
+import com.mongodb.annotations.ThreadSafe;
 import com.mongodb.lang.NonNull;
 import org.bson.types.ObjectId;
 
+@ThreadSafe
 interface ConnectionGenerationSupplier {
     int getGeneration();
 

driver-core/src/main/com/mongodb/internal/connection/ConnectionPool.java

@@ -17,6 +17,7 @@
 package com.mongodb.internal.connection;
 
 import com.mongodb.MongoConnectionPoolClearedException;
+import com.mongodb.annotations.ThreadSafe;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.internal.async.SingleResultCallback;
 import org.bson.types.ObjectId;
@@ -28,6 +29,7 @@
 /**
  * An instance of an implementation must be created in the {@linkplain #invalidate(Throwable) paused} state.
  */
+@ThreadSafe
 interface ConnectionPool extends Closeable {
     /**
      * Is equivalent to {@link #get(OperationContext, long, TimeUnit)} called with {@link ConnectionPoolSettings#getMaxWaitTime(TimeUnit)}.

driver-core/src/main/com/mongodb/internal/connection/DefaultConnectionPool.java

@@ -121,7 +121,8 @@
 import static java.util.concurrent.TimeUnit.NANOSECONDS;
 
 @SuppressWarnings("deprecation")
-class DefaultConnectionPool implements ConnectionPool {
+@ThreadSafe
+final class DefaultConnectionPool implements ConnectionPool {
     private static final Logger LOGGER = Loggers.getLogger("connection");
     private static final StructuredLogger STRUCTURED_LOGGER = new StructuredLogger("connection");
     private final ConcurrentPool<UsageTrackingInternalConnection> pool;
@@ -137,6 +138,7 @@ class DefaultConnectionPool implements ConnectionPool {
     private final StateAndGeneration stateAndGeneration;
     private final OptionalProvider<SdamServerDescriptionManager> sdamProvider;
 
+    @VisibleForTesting(otherwise = PRIVATE)
     DefaultConnectionPool(final ServerId serverId, final InternalConnectionFactory internalConnectionFactory,
             final ConnectionPoolSettings settings, final OptionalProvider<SdamServerDescriptionManager> sdamProvider) {
         this(serverId, internalConnectionFactory, settings, InternalConnectionPoolSettings.builder().build(), sdamProvider);
@@ -1156,6 +1158,7 @@ private MutableReference() {
         }
     }
 
+    @ThreadSafe
     static final class ServiceStateManager {
         private final ConcurrentHashMap<ObjectId, ServiceState> stateByServiceId = new ConcurrentHashMap<>();
 

driver-core/src/main/com/mongodb/internal/connection/InternalConnectionFactory.java

@@ -16,10 +16,12 @@
 
 package com.mongodb.internal.connection;
 
+import com.mongodb.annotations.ThreadSafe;
 import com.mongodb.connection.ServerId;
 import com.mongodb.lang.NonNull;
 import org.bson.types.ObjectId;
 
+@ThreadSafe
 interface InternalConnectionFactory {
     default InternalConnection create(ServerId serverId) {
         return create(serverId, new ConnectionGenerationSupplier() {

driver-core/src/main/com/mongodb/internal/connection/InternalConnectionInitializationDescription.java

@@ -16,12 +16,14 @@
 
 package com.mongodb.internal.connection;
 
+import com.mongodb.annotations.Immutable;
 import com.mongodb.connection.ConnectionDescription;
 import com.mongodb.connection.ServerDescription;
 
 /**
  * <p>This class is not part of the public API and may be removed or changed at any time</p>
  */
+@Immutable
 public class InternalConnectionInitializationDescription {
     private final ConnectionDescription connectionDescription;
     private final ServerDescription serverDescription;

driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnectionInitializer.java

@@ -60,7 +60,8 @@ public class InternalStreamConnectionInitializer implements InternalConnectionIn
 
     public InternalStreamConnectionInitializer(final ClusterConnectionMode clusterConnectionMode,
                                                @Nullable final Authenticator authenticator,
-                                               final BsonDocument clientMetadataDocument, final List<MongoCompressor> requestedCompressors,
+                                               @Nullable final BsonDocument clientMetadataDocument,
+                                               final List<MongoCompressor> requestedCompressors,
                                                @Nullable final ServerApi serverApi) {
         this.clusterConnectionMode = clusterConnectionMode;
         this.authenticator = authenticator;

driver-core/src/main/com/mongodb/internal/connection/MessageHeader.java

@@ -17,10 +17,12 @@
 package com.mongodb.internal.connection;
 
 import com.mongodb.MongoInternalException;
+import com.mongodb.annotations.Immutable;
 import org.bson.ByteBuf;
 
 // Contains the details of an OP_COMPRESSED reply from a MongoDB server.
-class MessageHeader {
+@Immutable
+final class MessageHeader {
     /**
      * The length of the standard message header in the MongoDB wire protocol.
      */

driver-core/src/main/com/mongodb/internal/connection/MessageSettings.java

@@ -27,8 +27,20 @@
  */
 @Immutable
 public final class MessageSettings {
+    /**
+     * <a href="https://www.mongodb.com/docs/current/reference/command/hello/#mongodb-data-hello.maxBsonObjectSize">
+     * {@code maxBsonObjectSize}</a>.
+     */
     private static final int DEFAULT_MAX_DOCUMENT_SIZE = 0x1000000;  // 16MB
+    /**
+     * <a href="https://www.mongodb.com/docs/current/reference/command/hello/#mongodb-data-hello.maxMessageSizeBytes">
+     * {@code maxMessageSizeBytes}</a>.
+     */
     private static final int DEFAULT_MAX_MESSAGE_SIZE = 0x2000000;   // 32MB
+    /**
+     * <a href="https://www.mongodb.com/docs/current/reference/command/hello/#mongodb-data-hello.maxWriteBatchSize">
+     * {@code maxWriteBatchSize}</a>.
+     */
     private static final int DEFAULT_MAX_BATCH_COUNT = 1000;
 
     private final int maxDocumentSize;

driver-core/src/test/unit/com/mongodb/internal/TimeoutTest.java

@@ -83,7 +83,7 @@ private static Stream<Arguments> durationArguments() {
     @Test
     void remainingNanosTrivialCases() {
         assertAll(
-                () -> assertThrows(UnsupportedOperationException.class, () -> Timeout.infinite().remaining(NANOSECONDS)),
+                () -> assertThrows(AssertionError.class, () -> Timeout.infinite().remaining(NANOSECONDS)),
                 () -> assertTrue(Timeout.infinite().remainingOrInfinite(NANOSECONDS) < 0),
                 () -> assertEquals(0, Timeout.immediate().remaining(NANOSECONDS)),
                 () -> assertEquals(0, Timeout.immediate().remainingOrInfinite(NANOSECONDS)));