#295 Improving wording in JavaDocs, making @NullValueMapping#value() mandatory

core-common/src/main/java/org/mapstruct/Mapper.java

@@ -105,9 +105,11 @@ public @interface Mapper {
     CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
 
     /**
-     * The strategy to be applied when for returning a target when the source equals null.
+     * The strategy to be applied when {@code null} is passed as source value to the methods of this mapper. If no
+     * strategy is configured, the strategy given via {@link MapperConfig#nullValueMappingStrategy()} will be applied,
+     * using {@link NullValueMappingStrategy#RETURN_NULL} by default.
      *
-     * @return The strategy applied when determining whether to return null or an empty object, list or map.
+     * @return The strategy to be applied when {@code null} is passed as source value to the methods of this mapper.
      */
     NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT;
 }

core-common/src/main/java/org/mapstruct/MapperConfig.java

@@ -83,9 +83,10 @@ public @interface MapperConfig {
     CollectionMappingStrategy collectionMappingStrategy() default CollectionMappingStrategy.DEFAULT;
 
     /**
-     * The strategy to be applied when for returning a target when the source equals null.
+     * The strategy to be applied when {@code null} is passed as source value to mapping methods. If no strategy is
+     * configured, {@link NullValueMappingStrategy#RETURN_NULL} will be used by default.
      *
-     * @return The strategy applied when determining whether to return null or an empty object, list or map.
+     * @return The strategy to be applied when {@code null} is passed as source value to mapping methods.
      */
     NullValueMappingStrategy nullValueMappingStrategy() default NullValueMappingStrategy.DEFAULT;
 }

core-common/src/main/java/org/mapstruct/NullValueMapping.java

@@ -24,17 +24,10 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Determines what kind to return in case of a null source argument.
+ * Specifies how the annotated method should deal with {@code null} values.
  * <p>
- * For:
+ * If no strategy is configured explicitly for a given method, the configuration from the enclosing mapper will be
- * <ol>
+ * applied, using {@link NullValueMappingStrategy#RETURN_NULL} by default.
- * <li>Bean Mapping: an 'empty' target bean, except for expressions and constants</li>
- * <li>Iterable Mapping: an 'empty' list</li>
- * <li>Map Mapping: an 'empty' map</li>
- * </ol>
- *
- * The user has a choice to use this annotation. When its used, it is used to either override a more global
- * setting, or in the most common case, to set the specific behavior to map null to default
  *
  * @author Sjaak Derksen
  */
@@ -42,5 +35,10 @@ import java.lang.annotation.Target;
 @Retention( RetentionPolicy.SOURCE )
 public @interface NullValueMapping {
 
-    NullValueMappingStrategy value() default NullValueMappingStrategy.RETURN_DEFAULT;
+    /**
+     * The strategy for mapping null values.
+     *
+     * @return The strategy for mapping null values
+     */
+    NullValueMappingStrategy value();
 }

core-common/src/main/java/org/mapstruct/NullValueMappingStrategy.java

@@ -19,34 +19,35 @@
 package org.mapstruct;
 
 /**
- * Strategy for propagating the value of collection-typed properties from source to target.
+ * Strategy for dealing with {@code null} values passed to mapping methods.
  *
  * @author Sjaak Derksen
  */
 public enum NullValueMappingStrategy {
 
     /**
-     * A null source argument of a mapping method will be mapped to a null target result
+     * If {@code null} is passed to a mapping method, {@code null} will be returned. That's the default behavior if no
+     * alternative strategy is configured globally, for given mapper or method.
      */
     RETURN_NULL,
 
     /**
-     * A null source argument of a mapping method will be mapped to a default target result
+     * If {@code null} is passed to a mapping method, a default value will be returned. The value depends on the kind of
-     * <p>
+     * the annotated method:
-     * <ol>
+     * <ul>
-     * <li>For a bean mapping this means a target object will be returned. {@link Mapping#expression()} and
+     * <li>For bean mapping method the target type will be instantiated and returned. {@link Mapping#expression()} and
-     * {@link Mapping#constant()} will be added to the target<\li>
+     * {@link Mapping#constant()} will be added to the target</li>
-     * <li>For an iterable mapping this means a {@link java.util.Collections#emptyList() } will be returned<\li>
+     * <li>For iterable mapping methods an immutable empty collection will be returned.</li>
-     * <li>For an map mapping this means a {@link java.util.Collections#emptyMap() } will be returned<\li>
+     * <li>For map mapping methods an immutable empty map will be returned.</li>
-     * </ol>
+     * </ul>
      */
     RETURN_DEFAULT,
 
     /**
-     * When given via {@link Mapper#nullValueMappingStrategy() ()}, causes the setting specified via
+     * When given via {@link Mapper#nullValueMappingStrategy()}, causes the setting specified via
-     * {@link MapperConfig#nullValueMappingStrategy() ()} to be applied, if present.
+     * {@link MapperConfig#nullValueMappingStrategy()} to be applied, if present.
      * <p>
-     * When given via {@link NullValueMapping#value() ()}, causes the setting specified via
+     * When given via {@link NullValueMapping#value()}, causes the setting specified via
      * {@link Mapper#nullValueMappingStrategy() ()} to be applied, if present.
      * <p>
      * Otherwise causes {@link #RETURN_NULL} to be applied.

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapper.java

@@ -18,14 +18,16 @@
  */
 package org.mapstruct.ap.test.mapnulltodefault;
 
+import static org.mapstruct.NullValueMappingStrategy.RETURN_DEFAULT;
+
 import java.util.List;
 import java.util.Map;
 import java.util.UUID;
 
 import org.mapstruct.Mapper;
-import org.mapstruct.NullValueMapping;
 import org.mapstruct.Mapping;
 import org.mapstruct.Mappings;
+import org.mapstruct.NullValueMapping;
 import org.mapstruct.ap.test.mapnulltodefault.source.Car;
 import org.mapstruct.ap.test.mapnulltodefault.target.CarDto;
 import org.mapstruct.factory.Mappers;
@@ -35,7 +37,7 @@ public interface CarMapper {
 
     CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
 
-    @NullValueMapping
+    @NullValueMapping(RETURN_DEFAULT)
     @Mappings({
         @Mapping(target = "seatCount", source = "numberOfSeats"),
         @Mapping(target = "model", constant = "ModelT"),
@@ -43,7 +45,7 @@ public interface CarMapper {
     })
     CarDto carToCarDto(Car car);
 
-    @NullValueMapping
+    @NullValueMapping(RETURN_DEFAULT)
     @Mappings({
         @Mapping(target = "seatCount", source = "car.numberOfSeats"),
         @Mapping(target = "model", source = "model"), // TODO,  should not be needed, must be made based on name only
@@ -52,10 +54,9 @@ public interface CarMapper {
     CarDto carToCarDto(Car car, String model);
 
 
-    @NullValueMapping
+    @NullValueMapping(RETURN_DEFAULT)
     List<CarDto> carsToCarDtos(List<Car> cars);
 
-
+    @NullValueMapping(RETURN_DEFAULT)
-    @NullValueMapping
     Map<Integer, CarDto> carsToCarDtoMap(Map<Integer, Car> cars);
 }

processor/src/test/java/org/mapstruct/ap/test/mapnulltodefault/CarMapperTest.java

@@ -122,6 +122,7 @@ public class CarMapperTest {
     }
 
     @Test
+    @SuppressWarnings( { "rawtypes", "unchecked" } )
     public void shouldMapMapWithNullArg() {
 
         //given