Document that CodecRegistry instances configured by the application a… (#1020)

JAVA-4777

Author: jyemin

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

@@ -400,9 +400,15 @@ public Builder credential(final MongoCredential credential) {
         /**
          * Sets the codec registry
          *
+         * <p>The {@link CodecRegistry} configured by this method is effectively treated by the driver as an instance of
+         * {@link org.bson.codecs.configuration.CodecProvider}, which {@link CodecRegistry} extends. So there is no benefit to defining
+         * a class that implements {@link CodecRegistry}. Rather, an application should always create {@link CodecRegistry} instances
+         * using the factory methods in {@link org.bson.codecs.configuration.CodecRegistries}.</p>
+         *
          * @param codecRegistry the codec registry
          * @return this
          * @see MongoClientSettings#getCodecRegistry()
+         * @see org.bson.codecs.configuration.CodecRegistries
          */
         public Builder codecRegistry(final CodecRegistry codecRegistry) {
             this.codecRegistry = notNull("codecRegistry", codecRegistry);

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MongoCollection.java

@@ -118,8 +118,14 @@ public interface MongoCollection<TDocument> {
     /**
      * Create a new MongoCollection instance with a different codec registry.
      *
+     * <p>The {@link CodecRegistry} configured by this method is effectively treated by the driver as an instance of
+     * {@link org.bson.codecs.configuration.CodecProvider}, which {@link CodecRegistry} extends. So there is no benefit to defining
+     * a class that implements {@link CodecRegistry}. Rather, an application should always create {@link CodecRegistry} instances
+     * using the factory methods in {@link org.bson.codecs.configuration.CodecRegistries}.</p>
+     *
      * @param codecRegistry the new {@link org.bson.codecs.configuration.CodecRegistry} for the collection
      * @return a new MongoCollection instance with the different codec registry
+     * @see org.bson.codecs.configuration.CodecRegistries
      */
     MongoCollection<TDocument> withCodecRegistry(CodecRegistry codecRegistry);
 

driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/MongoDatabase.java

@@ -77,8 +77,14 @@ public interface MongoDatabase {
     /**
      * Create a new MongoDatabase instance with a different codec registry.
      *
+     * <p>The {@link CodecRegistry} configured by this method is effectively treated by the driver as an instance of
+     * {@link org.bson.codecs.configuration.CodecProvider}, which {@link CodecRegistry} extends. So there is no benefit to defining
+     * a class that implements {@link CodecRegistry}. Rather, an application should always create {@link CodecRegistry} instances
+     * using the factory methods in {@link org.bson.codecs.configuration.CodecRegistries}.</p>
+     *
      * @param codecRegistry the new {@link org.bson.codecs.configuration.CodecRegistry} for the collection
      * @return a new MongoDatabase instance with the different codec registry
+     * @see org.bson.codecs.configuration.CodecRegistries
      */
     MongoDatabase withCodecRegistry(CodecRegistry codecRegistry);
 

driver-scala/src/main/scala/org/mongodb/scala/MongoCollection.scala

@@ -96,8 +96,15 @@ case class MongoCollection[TResult](private val wrapped: JMongoCollection[TResul
   /**
    * Create a new MongoCollection instance with a different codec registry.
    *
+   * The { @link CodecRegistry} configured by this method is effectively treated by the driver as an
+   * instance of { @link CodecProvider}, which { @link CodecRegistry} extends.
+   * So there is no benefit to defining a class that implements { @link CodecRegistry}. Rather, an
+   * application should always create { @link CodecRegistry} instances using the factory methods in
+   * { @link CodecRegistries}.
+   *
    * @param codecRegistry the new { @link org.bson.codecs.configuration.CodecRegistry} for the collection
    * @return a new MongoCollection instance with the different codec registry
+   * @see CodecRegistries
    */
   def withCodecRegistry(codecRegistry: CodecRegistry): MongoCollection[TResult] =
     MongoCollection(wrapped.withCodecRegistry(codecRegistry))

driver-scala/src/main/scala/org/mongodb/scala/MongoDatabase.scala

@@ -72,8 +72,15 @@ case class MongoDatabase(private[scala] val wrapped: JMongoDatabase) {
   /**
    * Create a new MongoDatabase instance with a different codec registry.
    *
+   * The { @link CodecRegistry} configured by this method is effectively treated by the driver as an
+   * instance of { @link CodecProvider}, which { @link CodecRegistry} extends.
+   * So there is no benefit to defining a class that implements { @link CodecRegistry}. Rather, an
+   * application should always create { @link CodecRegistry} instances using the factory methods in
+   * { @link CodecRegistries}.
+   *
    * @param codecRegistry the new { @link org.bson.codecs.configuration.CodecRegistry} for the collection
    * @return a new MongoDatabase instance with the different codec registry
+   * @see CodecRegistries
    */
   def withCodecRegistry(codecRegistry: CodecRegistry): MongoDatabase =
     MongoDatabase(wrapped.withCodecRegistry(codecRegistry))

driver-sync/src/main/com/mongodb/client/MongoCollection.java

@@ -123,8 +123,14 @@ public interface MongoCollection<TDocument> {
     /**
      * Create a new MongoCollection instance with a different codec registry.
      *
+     * <p>The {@link CodecRegistry} configured by this method is effectively treated by the driver as an instance of
+     * {@link org.bson.codecs.configuration.CodecProvider}, which {@link CodecRegistry} extends. So there is no benefit to defining
+     * a class that implements {@link CodecRegistry}. Rather, an application should always create {@link CodecRegistry} instances
+     * using the factory methods in {@link org.bson.codecs.configuration.CodecRegistries}.</p>
+     *
      * @param codecRegistry the new {@link org.bson.codecs.configuration.CodecRegistry} for the collection
      * @return a new MongoCollection instance with the different codec registry
+     * @see org.bson.codecs.configuration.CodecRegistries
      */
     MongoCollection<TDocument> withCodecRegistry(CodecRegistry codecRegistry);
 

driver-sync/src/main/com/mongodb/client/MongoDatabase.java

@@ -79,8 +79,14 @@ public interface MongoDatabase {
     /**
      * Create a new MongoDatabase instance with a different codec registry.
      *
+     * <p>The {@link CodecRegistry} configured by this method is effectively treated by the driver as an instance of
+     * {@link org.bson.codecs.configuration.CodecProvider}, which {@link CodecRegistry} extends. So there is no benefit to defining
+     * a class that implements {@link CodecRegistry}. Rather, an application should always create {@link CodecRegistry} instances
+     * using the factory methods in {@link org.bson.codecs.configuration.CodecRegistries}.</p>
+     *
      * @param codecRegistry the new {@link org.bson.codecs.configuration.CodecRegistry} for the database
      * @return a new MongoDatabase instance with the different codec registry
+     * @see org.bson.codecs.configuration.CodecRegistries
      */
     MongoDatabase withCodecRegistry(CodecRegistry codecRegistry);