diff --git a/src/main/java/org/apache/sling/api/resource/ValueMap.java b/src/main/java/org/apache/sling/api/resource/ValueMap.java
index ceebe08..94fd522 100644
--- a/src/main/java/org/apache/sling/api/resource/ValueMap.java
+++ b/src/main/java/org/apache/sling/api/resource/ValueMap.java
@@ -72,14 +72,18 @@
      * This method does not support conversion into a primitive type or an
      * array of a primitive type. It should return the default value in this
      * case.
+     * <br><br>
+     * <b>Implementation hint</b>: In the past it was allowed to call this with a 2nd parameter being {@code null}. 
+     * Therefore all implementations should internally call {@link #get(String, Class)} when the 2nd parameter
+     * has value {@code null}.
      *
      * @param name The name of the property
      * @param <T> The expected type
      * @param defaultValue The default value to use if the named property does
      *            not exist or cannot be converted to the requested type. The
      *            default value is also used to define the type to convert the
-     *            value to. If this is <code>null</code> any existing property is
-     *            not converted.
+     *            value to. Must not be {@code null}. If you want to return {@code null} by default
+     *            rather rely on {@link #get(String, Class)}.
      * @return Return named value converted to type T or the default value if
      *         non existing or can't be converted.
      */