Javadoc fix for #3076

Author: cowtowncoder

src/main/java/com/fasterxml/jackson/databind/annotation/JsonDeserialize.java

@@ -49,7 +49,7 @@
      * Depending on what is annotated,
      * value is either an instance of annotated class (used globablly
      * anywhere where class deserializer is needed); or only used for
-     * deserializing property access via a setter method.
+     * deserializing the value of the property annotated.
      */
     @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties
     public Class<? extends JsonDeserializer> using()
@@ -58,18 +58,22 @@ public Class<? extends JsonDeserializer> using()
     /**
      * Deserializer class to use for deserializing contents (elements
      * of a Collection/array, values of Maps) of annotated property.
-     * Can only be used on instances (methods, fields, constructors),
-     * and not value classes themselves.
+     * Can only be used on accessors (methods, fields, constructors), to
+     * apply to values of {@link java.util.Map}-valued properties; not
+     * applicable for value types used as Array elements
+     * or {@link java.util.Collection} and {@link java.util.Map} values.
      */
     @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties
     public Class<? extends JsonDeserializer> contentUsing()
         default JsonDeserializer.None.class;
 
     /**
      * Deserializer class to use for deserializing Map keys
-     * of annotated property.
-     * Can only be used on instances (methods, fields, constructors),
-     * and not value classes themselves.
+     * of annotated property or Map keys of value type so annotated.
+     * Can be used both on accessors (methods, fields, constructors), to
+     * apply to values of {@link java.util.Map}-valued properties, and
+     * on "key" classes, to apply to use of annotated type as
+     * {@link java.util.Map} keys (latter starting with Jackson 2.11).
      */
     public Class<? extends KeyDeserializer> keyUsing()
         default KeyDeserializer.None.class;

src/main/java/com/fasterxml/jackson/databind/annotation/JsonSerialize.java

@@ -38,26 +38,30 @@
      * serializing associated value. Depending on what is annotated,
      * value is either an instance of annotated class (used globablly
      * anywhere where class serializer is needed); or only used for
-     * serializing property access via a getter method.
+     * serializing the value of the property annotated.
      */
     @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties
     public Class<? extends JsonSerializer> using() default JsonSerializer.None.class;
 
     /**
      * Serializer class to use for serializing contents (elements
      * of a Collection/array, values of Maps) of annotated property.
-     * Can only be used on properties (methods, fields, constructors),
-     * and not value classes themselves (as they are typically generic)
+     * Can only be used on accessors (methods, fields, constructors), to
+     * apply to values of {@link java.util.Map}-valued properties; not
+     * applicable for value types used as Array elements
+     * or {@link java.util.Collection} and {@link java.util.Map} values.
      */
     @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties
     public Class<? extends JsonSerializer> contentUsing()
         default JsonSerializer.None.class;
 
     /**
-     * Serializer class to use for serializing Map keys
-     * of annotated property.
-     * Can only be used on properties (methods, fields, constructors),
-     * and not value classes themselves.
+     * Serializer class to use for deserializing Map keys
+     * of annotated property or Map keys of value type so annotated.
+     * Can be used both on accessors (methods, fields, constructors), to
+     * apply to values of {@link java.util.Map}-valued properties, and
+     * on "key" classes, to apply to use of annotated type as
+     * {@link java.util.Map} keys (latter starting with Jackson 2.11).
      */
     @SuppressWarnings("rawtypes") // to work around JDK8 bug wrt Class-valued annotation properties
     public Class<? extends JsonSerializer> keyUsing()