Improve JavaDoc regarding MutableCoercionConfig (FasterXML#4112)

src/main/java/com/fasterxml/jackson/databind/ObjectMapper.java

@@ -9,6 +9,7 @@
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Consumer;
 
 import com.fasterxml.jackson.annotation.*;
 import com.fasterxml.jackson.core.*;
@@ -2150,6 +2151,10 @@ public MutableConfigOverride configOverride(Class<?> type) {
      * Note that such settings are only applied if more specific
      * (by logical and physical type) configuration have
      * not been defined.
+     * <p>
+     * NOTE: Preferred access method and point is through {@code Builder} style
+     * construction, see {@link com.fasterxml.jackson.databind.json.JsonMapper.Builder}
+     * and {@link MapperBuilder#withCoercionConfigDefaults(Consumer)}.
      *
      * @since 2.12
      */
@@ -2160,6 +2165,10 @@ public MutableCoercionConfig coercionConfigDefaults() {
     /**
      * Accessor for {@link MutableCoercionConfig} through which
      * coercion configuration for specified logical target type can be set.
+     * <p>
+     * NOTE: Preferred access method and point is through {@code Builder} style
+     * construction, see {@link com.fasterxml.jackson.databind.json.JsonMapper.Builder}
+     * and {@link MapperBuilder#withCoercionConfig(LogicalType, Consumer)}.
      *
      * @since 2.12
      */
@@ -2170,6 +2179,10 @@ public MutableCoercionConfig coercionConfigFor(LogicalType logicalType) {
     /**
      * Accessor for {@link MutableCoercionConfig} through which
      * coercion configuration for specified physical target type can be set.
+     * <p>
+     * NOTE: Preferred access method and point is through {@code Builder} style
+     * construction, see {@link com.fasterxml.jackson.databind.json.JsonMapper.Builder}
+     * and {@link MapperBuilder#withCoercionConfig(Class, Consumer)} (Consumer)}.
      *
      * @since 2.12
      */

src/main/java/com/fasterxml/jackson/databind/cfg/MutableCoercionConfig.java

@@ -1,9 +1,14 @@
 package com.fasterxml.jackson.databind.cfg;
 
+import com.fasterxml.jackson.databind.json.JsonMapper;
+import com.fasterxml.jackson.databind.type.LogicalType;
+
+import java.util.function.Consumer;
+
 /**
  * Mutable version of {@link CoercionConfig} (or rather, extended API)
  * exposed during configuration phase of {@link com.fasterxml.jackson.databind.ObjectMapper}
- * construction (via Builder).
+ * construction (via {@link JsonMapper#builder()}).
  *
  * @since 2.12
  */
@@ -23,6 +28,15 @@ public MutableCoercionConfig copy() {
         return new MutableCoercionConfig(this);
     }
 
+    /**
+     * Method to set coercions to target type or class during builder-style mapper construction with
+     * <ul>
+     *     <li>{@link MapperBuilder#withCoercionConfig(Class, Consumer)},</li>
+     *     <li>{@link MapperBuilder#withCoercionConfig(LogicalType, Consumer)} and</li>
+     *     <li>{@link MapperBuilder#withCoercionConfigDefaults(Consumer)}</li>
+     * </ul>
+     * ... these builder methods. Refrain from using this method outside of builder phase.
+     */
     public MutableCoercionConfig setCoercion(CoercionInputShape shape,
             CoercionAction action) {
         _coercionsByShape[shape.ordinal()] = action;