Update javadoc

Author: damianmalczewski

src/main/java/io/github/problem4j/core/ProblemBuilder.java

@@ -111,7 +111,8 @@ public interface ProblemBuilder {
   ProblemBuilder extension(@Nullable String name, @Nullable Object value);
 
   /**
-   * Adds multiple custom extensions from a map.
+   * Adds multiple custom extensions from a map. If the value of any provided extension is {@code
+   * null} and an extension with the same key already exists, it will be removed.
    *
    * @param extensions map of extension keys and values
    * @return this builder instance for chaining
@@ -124,7 +125,9 @@ default ProblemBuilder extensions(@Nullable Map<String, ? extends @Nullable Obje
   }
 
   /**
-   * Adds single custom extension from {@link Problem.Extension}.
+   * Adds single custom extension from {@link Problem.Extension}. If the value of the provided
+   * extension is {@code null} and an extension with the same key already exists, it will be
+   * removed.
    *
    * @param extension array of extensions
    * @return this builder instance for chaining
@@ -137,7 +140,9 @@ default ProblemBuilder extension(Problem.@Nullable Extension extension) {
   }
 
   /**
-   * Adds multiple custom extensions from varargs of {@link Problem.Extension}.
+   * Adds multiple custom extensions from varargs of {@link Problem.Extension}. If the value of any
+   * provided extension is {@code null} and an extension with the same key already exists, it will
+   * be removed.
    *
    * @param extensions array of extensions
    * @return this builder instance for chaining
@@ -154,7 +159,9 @@ default ProblemBuilder extensions(Problem.@Nullable Extension @Nullable ... exte
   }
 
   /**
-   * Adds multiple custom extensions from a collection of {@link Problem.Extension}.
+   * Adds multiple custom extensions from a collection of {@link Problem.Extension}. If the value of
+   * any provided extension is {@code null} and an extension with the same key already exists, it
+   * will be removed.
    *
    * @param extensions collection of extensions
    * @return this builder instance for chaining

src/main/java/io/github/problem4j/core/ProblemMapper.java

@@ -56,7 +56,7 @@ public interface ProblemMapper {
    * <p>Note that because default implementation is thread-safe and stateless, since {@code v1.3.3}
    * this method returns a singleton instance.
    *
-   * @return a new {@link ProblemMapper} instance
+   * @return default implementation of {@link ProblemMapper}
    */
   static ProblemMapper create() {
     return ProblemMapperImpl.INSTANCE;

src/test/java/io/github/problem4j/core/AbstractProblemTest.java

@@ -148,6 +148,7 @@ void givenUnknownStatus_whenFindTitle_thenReturnsUnknownTitle() {
     assertThat(problem.getTitle()).isEqualTo(Problem.UNKNOWN_TITLE);
   }
 
+  @SuppressWarnings("deprecation")
   @Test
   void givenExtension_whenSetValue_thenValueIsUpdated() {
     Problem.Extension ext = new AbstractProblem.AbstractExtension("key", "original") {};