From be92a6ebaf8ad52d0b6262cbfdb3257a392570e1 Mon Sep 17 00:00:00 2001
From: Tatu Saloranta <tatu.saloranta@iki.fi>
Date: Sun, 26 Jan 2025 11:58:51 -0800
Subject: [PATCH] Javadoc improvement wrt #4928

---
 .../jackson/databind/SerializerProvider.java  | 26 ++++++++++++-------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java b/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java
index d89e565a22..7eed38b6d3 100644
--- a/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java
+++ b/src/main/java/com/fasterxml/jackson/databind/SerializerProvider.java
@@ -560,6 +560,9 @@ public abstract WritableObjectId findObjectId(Object forPojo,
      * Note that serializers produced should NOT handle polymorphic serialization
      * aspects; separate {@link TypeSerializer} is to be constructed by caller
      * if and as necessary.
+     *<p>
+     * Note: this call will also contextualize serializer (call
+     * {@code serializer.createContextual()}) before returning it.
      *
      * @throws JsonMappingException if there are fatal problems with
      *   accessing suitable serializer; including that of not
@@ -602,7 +605,8 @@ public JsonSerializer<Object> findValueSerializer(Class<?> valueType, BeanProper
      * This is necessary for accurate handling of external type information,
      * to handle polymorphic types.
      *<p>
-     * Note: this call will also contextualize serializer before returning it.
+     * Note: this call will also contextualize serializer (call
+     * {@code serializer.createContextual()}) before returning it.
      *
      * @param property When creating secondary serializers, property for which
      *   serializer is needed: annotations of the property (or bean that contains it)
@@ -634,9 +638,10 @@ public JsonSerializer<Object> findValueSerializer(JavaType valueType, BeanProper
     }
 
     /**
-     * Method variant used when we do NOT want contextualization to happen; it will need
-     * to be handled at a later point, but caller wants to be able to do that
-     * as needed; sometimes to avoid infinite loops
+     * Serializer lookup variant used when we do NOT want contextualization to happen;
+     * while contextualization MUST be handled at some point (many serializers will not be
+     * in usable state before contextualization), but caller wants to be able to do that
+     * later; sometimes to avoid infinite loops.
      *
      * @since 2.5
      */
@@ -663,9 +668,10 @@ public JsonSerializer<Object> findValueSerializer(Class<?> valueType) throws Jso
     }
 
     /**
-     * Method variant used when we do NOT want contextualization to happen; it will need
-     * to be handled at a later point, but caller wants to be able to do that
-     * as needed; sometimes to avoid infinite loops
+     * Serializer lookup variant used when we do NOT want contextualization to happen;
+     * while contextualization MUST be handled at some point (many serializers will not be
+     * in usable state before contextualization), but caller wants to be able to do that
+     * later; sometimes to avoid infinite loops.
      *
      * @since 2.5
      */
@@ -697,8 +703,10 @@ public JsonSerializer<Object> findValueSerializer(JavaType valueType)
      * certain that this is the primary property value serializer.
      *
      * @param valueType Type of values to serialize
-     * @param property Property that is being handled; will never be null, and its
-     *    type has to match <code>valueType</code> parameter.
+     * @param property Property that directly refers to value being serialized (optional,
+     *    may be {@code null} for root level serializers).
+     *    Should not be null if property is known. If not null,
+     *    its type must match {@code valueType} argument.
      *
      * @since 2.3
      */