Documentation

Author: jeffgbutler

Diff for: CHANGELOG.md

@@ -82,6 +82,8 @@ Runtime behavior changes:
 2. We have updated the "ParameterTypeConverter" used in Spring applications to maintain compatibility with Spring's
    "Converter" interface. The primary change is that the framework will no longer call a type converter if the
    input value is null. This should simplify the coding of converters and foster reuse with existing Spring converters.
+3. The "map" method on the "WhenPresent" conditions will accept a mapper function that may return a null value. The
+   conditions will now properly handle this outcome 
 
 ### Other important changes:
 

Diff for: src/site/markdown/docs/conditions.md

@@ -166,8 +166,8 @@ table lists the optional conditions and shows how to use them:
 | Null                      | where(id, isNull().filter(BooleanSupplier)                             | The condition will render if BooleanSupplier.getAsBoolean() returns true                                                                           |
 
 ### "When Present" Condition Builders
-The library supplies several methods that supply conditions to be used in the common case of checking for null
-values. The table below lists the rendering rules for each of these "when present" condition builder methods.
+The library supplies conditions for use in the common case of checking for null
+values. The table below lists the rendering rules for each of these "when present" conditions.
 
 | Condition                 | Example                                           | Rendering Rules                                               |
 |---------------------------|---------------------------------------------------|---------------------------------------------------------------|
@@ -184,14 +184,20 @@ values. The table below lists the rendering rules for each of these "when presen
 | Not Like                  | where(id, isNotLikeWhenPresent(x))                | The condition will render if x is non-null                    |
 | Not Like Case Insensitive | where(id, isNotLikeCaseInsensitiveWhenPresent(x)) | The condition will render if x is non-null                    |
 
-Note that these methods simply apply a "NotNull" filter to a  condition. For example:
+With our adoption of JSpecify, it is now considered a misuse of the library to pass a null value into a condition
+unless the condition is one of the "when present" conditions. If you previously wrote code like this:
 
 ```java
-// the following two lines are functionally equivalent
-... where (id, isEqualToWhenPresent(x)) ...
 ... where (id, isEqualTo(x).filter(Objects::nonNull)) ...
 ```
 
+Starting in version 2.0.0 of the library, you will now see IDE warnings related to nullability. You should change it
+to this:
+
+```java
+... where (id, isEqualToWhenPresent(x)) ...
+```
+
 ### Optionality with the "In" Conditions
 Optionality with the "in" and "not in" conditions is a bit more complex than the other types of conditions. The rules
 are different for the base conditions ("isIn", "isNotIn", etc.) and the "when present" conditions ("isInWhenPresent",