Improve and fix JavaDocs for Jackson 2.15 (#3917)

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

@@ -59,15 +59,15 @@ public enum Type {
              * Usually this can be defined by using
              * {@link com.fasterxml.jackson.annotation.JsonManagedReference}
              */
-            MANAGED_REFERENCE
+            MANAGED_REFERENCE,
 
             /**
              * Reference property that Jackson manages by suppressing it during serialization,
              * and reconstructing during deserialization.
              * Usually this can be defined by using
              * {@link com.fasterxml.jackson.annotation.JsonBackReference}
              */
-            ,BACK_REFERENCE
+            BACK_REFERENCE
             ;
         }
 

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

@@ -322,7 +322,7 @@ public enum MapperFeature implements ConfigFeature
      * Feature is enabled by default which means that deserialization does
      * support deserializing types via builders with type parameters (generic types).
      *<p>
-     * See: https://github.com/FasterXML/jackson-databind/issues/921
+     * See: <a href="https://github.com/FasterXML/jackson-databind/issues/921">databind#921</a>
      *
      * @since 2.12
      */
@@ -401,6 +401,11 @@ public enum MapperFeature implements ConfigFeature
      *<p>
      * Note: does <b>not</b> apply to {@link java.util.Map} serialization (since
      * entries are not considered Bean/POJO properties.
+     * <p>
+     * WARNING: Disabling it may have a negative impact on deserialization performance.
+     * When disabled, all properties before the last creator property in the input need to be buffered,
+     * since all creator properties are required to create the instance.
+     * Enabling this feature ensures that there is as little buffering as possible. 
      *<p>
      * Feature is enabled by default.
      *

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

@@ -4623,7 +4623,7 @@ public <T> T updateValue(T valueToUpdate, Object overrides)
      * @param t The class to generate schema for
      * @return Constructed JSON schema.
      *
-     * @deprecated Since 2.6 use external JSON Schema generator (https://github.com/FasterXML/jackson-module-jsonSchema)
+     * @deprecated Since 2.6 use external JSON Schema generator (<a href="https://github.com/FasterXML/jackson-module-jsonSchema">jackson-module-jsonSchema</a>)
      *    (which under the hood calls {@link #acceptJsonFormatVisitor(JavaType, JsonFormatVisitorWrapper)})
      */
     @Deprecated

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

@@ -947,19 +947,15 @@ public JsonSerializer<Object> getDefaultNullValueSerializer() {
     }
 
     /**
-     * Method called to get the serializer to use for serializing
-     * Map keys that are nulls: this is needed since JSON does not allow
-     * any non-String value as key, including null.
-     *<p>
-     * Typically, returned serializer
-     * will either throw an exception, or use an empty String; but
-     * other behaviors are possible.
-     */
-    /**
-     * Method called to find a serializer to use for null values for given
-     * declared type. Note that type is completely based on declared type,
+     * Method called to find a serializer to serializes Map keys that are nulls, 
+     * as JSON does not allow any non-String value as a key, including null.
+     * Note that type is completely based on declared type,
      * since nulls in Java have no type and thus runtime type cannot be
      * determined.
+     * 
+     * @return JsonSerializer that handles the serialization of null keys, 
+     * usually by throwing an exception or using an empty String,
+     * but other behaviors are also possible.
      *
      * @since 2.0
      */

src/main/java/com/fasterxml/jackson/databind/deser/std/CollectionDeserializer.java

@@ -529,8 +529,8 @@ public void resolveForwardReference(Object id, Object value) throws IOException
 
     /**
      * Helper class to maintain processing order of value. The resolved
-     * object associated with {@link #_id} comes before the values in
-     * {@link #next}.
+     * object associated with {@code #id} parameter from {@link #handleResolvedForwardReference(Object, Object)} 
+     * comes before the values in {@link #next}.
      */
     private final static class CollectionReferring extends Referring {
         private final CollectionReferringAccumulator _parent;

src/main/java/com/fasterxml/jackson/databind/introspect/AnnotatedClass.java

@@ -202,8 +202,7 @@ public static AnnotatedClass construct(JavaType type, MapperConfig<?> config,
      * Method similar to {@link #construct}, but that will NOT include
      * information from supertypes; only class itself and any direct
      * mix-ins it may have.
-     */
-    /**
+     * 
      * @deprecated Since 2.9, use methods in {@link AnnotatedClassResolver} instead.
      */
     @Deprecated

src/main/java/com/fasterxml/jackson/databind/util/internal/PrivateMaxEntriesMap.java

@@ -136,7 +136,7 @@ public final class PrivateMaxEntriesMap<K, V> extends AbstractMap<K, V>
 
     /**
      * The number of read buffers to use.
-     * The max of 4 was introduced due to https://github.com/FasterXML/jackson-databind/issues/3665.
+     * The max of 4 was introduced due to <a href="https://github.com/FasterXML/jackson-databind/issues/3665">databind#3665</a>.
      */
     static final int NUMBER_OF_READ_BUFFERS = Math.min(4, ceilingNextPowerOfTwo(NCPU));
 
@@ -145,7 +145,7 @@ public final class PrivateMaxEntriesMap<K, V> extends AbstractMap<K, V>
 
     /**
      * The number of pending read operations before attempting to drain.
-     * The threshold of 4 was introduced due to https://github.com/FasterXML/jackson-databind/issues/3665.
+     * The threshold of 4 was introduced due to <a href="https://github.com/FasterXML/jackson-databind/issues/3665">databind#3665</a>.
      */
     static final int READ_BUFFER_THRESHOLD = 4;
 

src/test/java/com/fasterxml/jackson/databind/deser/dos/StreamReadStringConstraintsTest.java

@@ -9,7 +9,7 @@
 import com.fasterxml.jackson.databind.json.JsonMapper;
 
 /**
- * Tests for {@a href="https://github.com/FasterXML/jackson-core/issues/863"}.
+ * Tests for <a href="https://github.com/FasterXML/jackson-core/issues/863">databind#863</a>"
  */
 public class StreamReadStringConstraintsTest extends BaseMapTest
 {

src/test/java/com/fasterxml/jackson/databind/jsontype/TestPolymorphicDeserialization676.java

@@ -8,7 +8,7 @@
 import java.util.*;
 
 /**
- * Reproduction of [https://github.com/FasterXML/jackson-databind/issues/676]
+ * Reproduction of <a href="https://github.com/FasterXML/jackson-databind/issues/676">databind#676</a>
  * <p/>
  * Deserialization of class with generic collection inside
  * depends on how is was deserialized first time.