#166 Add code-examples to Javadoc of org.mapstruct.* annotations (#1876)

core/src/main/java/org/mapstruct/BeanMapping.java

@@ -18,6 +18,34 @@ import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
  * <p>
  * Either {@link #resultType()}, {@link #qualifiedBy()} or {@link #nullValueMappingStrategy()} must be specified.
  * </p>
+ * <p><strong>Example:</strong> Determining the result type</p>
+ * <pre><code class='java'>
+ * // When result types have an inheritance relation, selecting either mapping method {@link Mapping} or factory method
+ * // {@link BeanMapping} can be become ambiguous. Parameter  {@link BeanMapping#resultType()} can be used.
+ * public class FruitFactory {
+ *     public Apple createApple() {
+ *         return new Apple();
+ *     }
+ *     public Orange createOrange() {
+ *         return new Orange();
+ *     }
+ * }
+ * &#64;Mapper(uses = FruitFactory.class)
+ * public interface FruitMapper {
+ *     &#64;BeanMapping(resultType = Apple.class)
+ *     Fruit toFruit(FruitDto fruitDto);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class FruitMapperImpl implements FruitMapper {
+ *      &#64;Override
+ *      public Fruit toFruit(FruitDto fruitDto) {
+ *          Apple fruit = fruitFactory.createApple();
+ *          // ...
+ *      }
+ * }
+ * </code></pre>
  *
  * @author Sjaak Derksen
  */
@@ -40,9 +68,9 @@ public @interface BeanMapping {
      * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
      *
      * @return the qualifiers
-     * @see BeanMapping#qualifiedByName()
+     * @see Qualifier
      */
-    Class<? extends Annotation>[] qualifiedBy() default { };
+    Class<? extends Annotation>[] qualifiedBy() default {};
 
     /**
      * Similar to {@link #qualifiedBy()}, but used in combination with {@code @}{@link Named} in case no custom

core/src/main/java/org/mapstruct/Builder.java

@@ -14,6 +14,32 @@ import org.mapstruct.util.Experimental;
 /**
  * Configuration of builders, e.g. the name of the final build method.
  *
+ * <p>
+ * <strong>Example:</strong> Using builder
+ * </p>
+ * <pre><code class='java'>
+ * // Mapper
+ * &#64;Mapper
+ * public interface SimpleBuilderMapper {
+ *      &#64;Mapping(target = "name", source = "fullName"),
+ *      &#64;Mapping(target = "job", constant = "programmer"),
+ *      SimpleImmutablePerson toImmutable(SimpleMutablePerson source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public SimpleImmutablePerson toImmutable(SimpleMutablePerson source) {
+ *      // name method can be changed with parameter {@link #buildMethod()}
+ *      Builder simpleImmutablePerson = SimpleImmutablePerson.builder();
+ *      simpleImmutablePerson.name( source.getFullName() );
+ *      simpleImmutablePerson.age( source.getAge() );
+ *      simpleImmutablePerson.address( source.getAddress() );
+ *      simpleImmutablePerson.job( "programmer" );
+ *      // ...
+ * }
+ * </code></pre>
+ *
  * @author Filip Hrisafov
  *
  * @since 1.3

core/src/main/java/org/mapstruct/InheritInverseConfiguration.java

@@ -22,6 +22,41 @@ import java.lang.annotation.Target;
  * If more than one matching inverse method exists, the name of the method to inherit the configuration from must be
  * specified via {@link #name()}
  *
+ * <p>
+ * <strong>Example</strong>
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *      Human toHuman(HumanDto humanDto);
+ *      &#64;InheritInverseConfiguration
+ *      HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class HumanMapperImpl implements HumanMapper {
+ *      &#64;Override
+ *      public Human toHuman(HumanDto humanDto) {
+ *          if ( humanDto == null ) {
+ *              return null;
+ *           }
+ *          Human human = new Human();
+ *          human.setName( humanDto.getName() );
+ *          return human;
+ *      }
+ *      &#64;Override
+ *      public HumanDto toHumanDto(Human human) {
+ *          if ( human == null ) {
+ *              return null;
+ *          }
+ *          HumanDto humanDto = new HumanDto();
+ *          humanDto.setName( human.getName() );
+ *          return humanDto;
+ *      }
+ * }
+ * </code></pre>
+ *
  * @author Sjaak Derksen
  */
 @Target(ElementType.METHOD)

core/src/main/java/org/mapstruct/IterableMapping.java

@@ -18,9 +18,33 @@ import java.util.Date;
  * Configures the mapping between two iterable like types, e.g. {@code List<String>} and {@code List<Date>}.
  *
  *
- * <p>Note: either  @IterableMapping#dateFormat, @IterableMapping#resultType or @IterableMapping#qualifiedBy
+ * <p>Note: either  {@link #dateFormat()}, {@link #elementTargetType()} or {@link #qualifiedBy() }
  * must be specified</p>
  *
+ * <p>
+ * <strong>Example:</strong> Convert List&lt;Float&gt; to List&lt;String&gt;
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface FloatToStringMapper {
+ *      &#64;IterableMapping( numberFormat = "##.00" )
+ *      List&lt;String&gt; sourceToTarget(List&lt;Float&gt; source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class FloatToStringMapperImpl implements FloatToStringMapper {
+ *      &#64;Override
+ *      public List&lt;String&gt; sourceToTarget(List&lt;Float&gt; source) {
+ *          List&lt;String&gt; list = new ArrayList&lt;String&gt;( source.size() );
+ *          for ( Float float1 : source ) {
+ *              list.add( new DecimalFormat( "##.00" ).format( float1 ) );
+ *          }
+ *     // ...
+ *      }
+ * }
+ * </code></pre>
+ *
  * Supported mappings are:
  * <ul>
  *     <li>{@code Iterable<A>} to/from {@code Iterable<B>}/{@code Iterable<A>}</li>
@@ -60,6 +84,7 @@ public @interface IterableMapping {
      * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
      *
      * @return the qualifiers
+     * @see Qualifier
      */
     Class<? extends Annotation>[] qualifiedBy() default { };
 

core/src/main/java/org/mapstruct/MapMapping.java

@@ -15,9 +15,35 @@ import java.text.DecimalFormat;
 import java.util.Date;
 
 /**
- * Configures the mapping between two map types, e.g. {@code Map<String, String>} and {@code Map<Long, Date>}.
+ * Configures the mapping between two map types, e.g. Map&lt;String, String&gt; and Map&lt;Long, Date&gt;.
  *
- * <p>Note: at least one element needs to be specified</p>
+ * <p>
+ * <strong>Example</strong>:
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface SimpleMapper {
+ *       &#64;MapMapping(valueDateFormat = "dd.MM.yyyy")
+ *       Map&lt;String, String&gt; longDateMapToStringStringMap(Map&lt;Long, Date&gt; source);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class SimpleMapperImpl implements SimpleMapper {
+ *      &#64;Override
+ *      public Map&lt;String, String&gt; longDateMapToStringStringMap(Map&lt;Long, Date&gt; source) } {
+ *          Map&lt;String, String&gt; map = new HashMap&lt;String, String&gt;(); }
+ *          for ( java.util.Map.Entry&lt;Long, Date&gt; entry : source.entrySet() ) } {
+ *              String key = new DecimalFormat( "" ).format( entry.getKey() );
+ *              String value = new SimpleDateFormat( "dd.MM.yyyy" ).format( entry.getValue() );
+ *              map.put( key, value );
+ *          }
+ *          // ...
+ *      }
+ * }
+ * </code></pre>
+ *
+ * <p><strong>NOTE:</strong> at least one element needs to be specified</p>
  *
  * @author Gunnar Morling
  */
@@ -66,6 +92,7 @@ public @interface MapMapping {
      * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
      *
      * @return the qualifiers
+     * @see Qualifier
      */
     Class<? extends Annotation>[] keyQualifiedBy() default { };
 
@@ -93,6 +120,7 @@ public @interface MapMapping {
      * A qualifier is a custom annotation and can be placed on either a hand written mapper class or a method.
      *
      * @return the qualifiers
+     * @see Qualifier
      */
     Class<? extends Annotation>[] valueQualifiedBy() default { };
 

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

@@ -18,6 +18,58 @@ import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
  * Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via
  * MapStruct.
  *
+ * <p>
+ * <strong>Example 1:</strong> Creating mapper
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface CarMapper {
+ *     CarDto toCarDto(Car source);
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 2:</strong> Use additional mappers with parameters {@link #uses()}, {@link #componentModel()}
+ * and {@link #injectionStrategy()}
+ * </p>
+ * <pre><code class='java'>
+ * // we have MarkMapper (map field "mark" to field "name" to upper case)
+ * &#64;Mapper(componentModel = "spring")
+ * public class MarkMapper {
+ *     public String mapMark(String mark) {
+ *         return mark.toUpperCase();
+ *     }
+ * }
+ * // we have CarMapper
+ * &#64;Mapper(
+ *      componentModel = "spring",
+ *      uses = MarkMapper.class,
+ *      injectionStrategy = InjectionStrategy.CONSTRUCTOR)
+ * public interface CarMapper {
+ *     &#64;Mapping(source = "mark", target = "name")
+ *     CarDto convertMap(CarEntity carEntity);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Component
+ * public class CarMapperImpl implements CarMapper {
+ *     private final MarkMapper markMapper;
+ *     &#64;Autowired
+ *     public CarMapperImpl(MarkMapper markMapper) {
+ *         this.markMapper = markMapper;
+ *     }
+ *     &#64;Override
+ *     public CarDto convertMap(CarEntity carEntity) {
+ *         if ( carEntity == null ) {
+ *             return null;
+ *         }
+ *         CarDto carDto = new CarDto();
+ *         carDto.setName( markMapper.mapMark( carEntity.getMark() ) );
+ *         return carDto;
+ *     }
+ * }
+ * </code></pre>
+ *
  * @author Gunnar Morling
  */
 @Target(ElementType.TYPE)

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

@@ -30,6 +30,36 @@ import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
  * types are assignable.
  * </p>
  *
+ * <p>
+ * <strong>Example:</strong>
+ * </p>
+ * <pre><code class='java'>
+ * // create config
+ * &#64;MapperConfig(
+ *     uses = CustomMapperViaMapperConfig.class,
+ *     unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface CentralConfig {
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // use config
+ * &#64;Mapper(config = CentralConfig.class, uses = { CustomMapperViaMapper.class } )
+ * public interface SourceTargetMapper {
+ *   // ...
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // result after applying CentralConfig
+ * &#64;Mapper(
+ *     uses = { CustomMapperViaMapper.class, CustomMapperViaMapperConfig.class },
+ *     unmappedTargetPolicy = ReportingPolicy.ERROR
+ * )
+ * public interface SourceTargetMapper {
+ *    // ...
+ * }
+ * </code></pre>
+ *
  * @author Sjaak Derksen
  * @see Mapper#config()
  */

core/src/main/java/org/mapstruct/Mapping.java

@@ -16,17 +16,124 @@ import java.text.SimpleDateFormat;
 import java.util.Date;
 
 import static org.mapstruct.NullValueCheckStrategy.ON_IMPLICIT_CONVERSION;
+
 /**
  * Configures the mapping of one bean attribute or enum constant.
  * <p>
  * The name of the mapped attribute or constant is to be specified via {@link #target()}. For mapped bean attributes it
  * is assumed by default that the attribute has the same name in the source bean. Alternatively, one of
  * {@link #source()}, {@link #expression()} or {@link #constant()} can be specified to define the property source.
+ * </p>
  * <p>
  * In addition, the attributes {@link #dateFormat()} and {@link #qualifiedBy()} may be used to further define the
  * mapping.
+ * </p>
  *
  * <p>
+ * <strong>Example 1:</strong> Implicitly mapping fields with the same name:
+ * </p>
+ * <pre><code class='java'>
+ * // Both classes HumanDto and Human have property with name "fullName"
+ * // properties with the same name will be mapped implicitly
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    humanDto.setFullName( human.getFullName() );
+ *    // ...
+ * }
+ * </code></pre>
+ *
+ * <p><strong>Example 2:</strong> Mapping properties with different names</p>
+ * <pre><code class='java'>
+ * // We need map Human.companyName to HumanDto.company
+ * // we can use &#64;Mapping with parameters {@link #source()} and {@link #source()}
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(source="companyName", target="company")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *     humanDto.setCompany( human.getCompanyName() );
+ *      // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 3:</strong> Mapping with expression
+ * <b>IMPORTANT NOTE:</b> Now it works only for Java
+ * </p>
+ * <pre><code class='java'>
+ * // We need map Human.name to HumanDto.countNameSymbols.
+ * // we can use {@link #expression()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(target="countNameSymbols", expression="java(human.getName().length())")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates:
+ *&#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    humanDto.setCountNameSymbols( human.getName().length() );
+ *    //...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 4:</strong> Mapping to constant
+ * </p>
+ * <pre><code class='java'>
+ * // We need map HumanDto.name to string constant "Unknown"
+ * // we can use {@link #constant()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(target="name", constant="Unknown")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *   humanDto.setName( "Unknown" );
+ *   // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 5:</strong> Mapping with default value
+ * </p>
+ * <pre><code class='java'>
+ * // We need map Human.name to HumanDto.fullName, but if Human.name == null, then set value "Somebody"
+ * // we can use {@link #defaultValue()} or {@link #defaultExpression()} for it
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *    &#64;Mapping(source="name", target="name", defaultValue="Somebody")
+ *    HumanDto toHumanDto(Human human)
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public HumanDto toHumanDto(Human human) {
+ *    if ( human.getName() != null ) {
+ *       humanDto.setFullName( human.getName() );
+ *    }
+ *    else {
+ *       humanDto.setFullName( "Somebody" );
+ *    }
+ *   // ...
+ * }
+ * </code></pre>
+ *
  * <b>IMPORTANT NOTE:</b> the enum mapping capability is deprecated and replaced by {@link ValueMapping} it
  * will be removed in subsequent versions.
  *
@@ -188,6 +295,7 @@ public @interface Mapping {
      * error. A qualifier is a custom annotation and can be placed on a hand written mapper class or a method.
      *
      * @return the qualifiers
+     * @see Qualifier
      */
     Class<? extends Annotation>[] qualifiedBy() default { };
 

core/src/main/java/org/mapstruct/MappingTarget.java

@@ -17,6 +17,43 @@ import java.lang.annotation.Target;
  * <p>
  * <b>NOTE:</b> The parameter passed as a mapping target <b>must</b> not be {@code null}.
  *
+ * <p>
+ * <strong>Example 1:</strong> Update exist bean without return value
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *     void updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * &#64;Override
+ * public void updateHuman(HumanDto humanDto, Human human) {
+ *     human.setName( humanDto.getName() );
+ *     // ...
+ * }
+ * </code></pre>
+ * <p>
+ * <strong>Example 2:</strong> Update exist bean and return it
+ * </p>
+ * <pre><code class='java'>
+ * &#64;Mapper
+ * public interface HumanMapper {
+ *     Human updateHuman(HumanDto humanDto, @MappingTarget Human human);
+ * }
+ * </code></pre>
+ * // generates:
+ * <pre><code class='java'>
+ * &#64;Override
+ * public Human updateHuman(HumanDto humanDto, Human human) {
+ *     // ...
+ *     human.setName( humanDto.getName() );
+ *     return human;
+ * }
+ *</code></pre>
+ *
+ *
  * @author Andreas Gudian
  */
 @Target(ElementType.PARAMETER)

core/src/main/java/org/mapstruct/Mappings.java

@@ -12,6 +12,32 @@ import java.lang.annotation.Target;
 
 /**
  * Configures the mappings of several bean attributes.
+ * <p>
+ * <strong>TIP: When using Java 8 or later, you can omit the @Mappings
+ * wrapper annotation and directly specify several @Mapping annotations on one method.</strong>
+ *
+ * <p>These two examples are equal.
+ * </p>
+ * <pre><code class='java'>
+ * // before Java 8
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;Mappings({
+ *         &#64;Mapping(source = "first", target = "firstProperty"),
+ *         &#64;Mapping(source = "second", target = "secondProperty")
+ *     })
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // Java 8 and later
+ * &#64;Mapper
+ * public interface MyMapper {
+ *     &#64;Mapping(source = "first", target = "firstProperty"),
+ *     &#64;Mapping(source = "second", target = "secondProperty")
+ *     HumanDto toHumanDto(Human human);
+ * }
+ * </code></pre>
  *
  * @author Gunnar Morling
  */

core/src/main/java/org/mapstruct/Qualifier.java

@@ -14,7 +14,7 @@ import java.lang.annotation.Target;
  * Declares an annotation type to be a qualifier. Qualifier annotations allow unambiguously identify a suitable mapping
  * method in case several methods qualify to map a bean property, iterable element etc.
  * <p>
- * For more info see:
+ * Can be used in:
  * <ul>
  * <li>{@link Mapping#qualifiedBy() }</li>
  * <li>{@link BeanMapping#qualifiedBy() }</li>
@@ -22,15 +22,61 @@ import java.lang.annotation.Target;
  * <li>{@link MapMapping#keyQualifiedBy() }</li>
  * <li>{@link MapMapping#valueQualifiedBy() }</li>
  * </ul>
- * Example:
+ * <p><strong>Example:</strong></p>
+ * <pre><code class='java'>
+ * // create qualifiers
+ * &#64;Qualifier
+ * &#64;Target(ElementType.TYPE)
+ * &#64;Retention(RetentionPolicy.CLASS)
+ * public &#64;interface TitleTranslator {}
  *
- * <pre>
  * &#64;Qualifier
  * &#64;Target(ElementType.METHOD)
  * &#64;Retention(RetentionPolicy.CLASS)
- * public &#64;interface EnglishToGerman {
+ * public @interface EnglishToGerman {}
+ *
+ * &#64;Qualifier
+ * &#64;Target(ElementType.METHOD)
+ * &#64;Retention(RetentionPolicy.CLASS)
+ * public @interface GermanToEnglish {}
+ * </code></pre>
+ * <pre><code class='java'>
+ * // we can create class with map methods
+ * &#64;TitleTranslator
+ * public class Titles {
+ *     &#64;EnglishToGerman
+ *     public String translateTitleEnglishToGerman(String title) {
+ *         // some mapping logic
+ *     }
+ *     &#64;GermanToEnglish
+ *     public String translateTitleGermanToEnglish(String title) {
+ *         // some mapping logic
+ *     }
  * }
- * </pre>
+ * </code></pre>
+ * <pre><code class='java'>
+ * // usage
+ * &#64;Mapper( uses = Titles.class )
+ * public interface MovieMapper {
+ *      &#64;Mapping( target = "title", qualifiedBy = { TitleTranslator.class, EnglishToGerman.class } )
+ *      GermanRelease toGerman( OriginalRelease movies );
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class MovieMapperImpl implements MovieMapper {
+ *      private final Titles titles = new Titles();
+ *      &#64;Override
+ *      public GermanRelease toGerman(OriginalRelease movies) {
+ *          if ( movies == null ) {
+ *              return null;
+ *          }
+ *          GermanRelease germanRelease = new GermanRelease();
+ *          germanRelease.setTitle( titles.translateTitleEnglishToGerman( movies.getTitle() ) );
+ *          return germanRelease;
+ *     }
+ * }
+ * </code></pre>
  *
  * <b>NOTE:</b> Qualifiers should have {@link RetentionPolicy#CLASS}.
  *

core/src/main/java/org/mapstruct/TargetType.java

@@ -16,6 +16,35 @@ import java.lang.annotation.Target;
  * Not more than one parameter can be declared as {@code TargetType} and that parameter needs to be of type
  * {@link Class} (may be parameterized), or a super-type of it.
  *
+ * <p>
+ * <strong>Example:</strong>
+ * </p>
+ * <pre><code class='java'>
+ * public class EntityFactory {
+ *    public &lt;T extends BaseEntity&gt; T createEntity(@TargetType Class&lt;T&gt; entityClass) {
+ *         return // ... custom factory logic
+ *    }
+ * }
+ * &#64;Mapper(uses = EntityFactory.class)
+ * public interface CarMapper {
+ *     CarEntity carDtoToCar(CarDto dto);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * // generates
+ * public class CarMapperImpl implements CarMapper {
+ *     private final EntityFactory entityFactory = new EntityFactory();
+ *     &#64;Override
+ *     public CarEntity carDtoToCar(CarDto dto) {
+ *         if ( dto == null ) {
+ *             return null;
+ *         }
+ *         CarEntity carEntity = entityFactory.createEntity( CarEntity.class );
+ *         return carEntity;
+ *     }
+ * }
+ * </code></pre>
+ *
  * @author Andreas Gudian
  */
 @Target(ElementType.PARAMETER)

core/src/main/java/org/mapstruct/ValueMappings.java

@@ -12,6 +12,31 @@ import java.lang.annotation.Target;
 
 /**
  * Constructs a set of value (constant) mappings.
+ * <p>
+ * <strong>TIP: When using Java 8 or later, you can omit the @ValueMappings
+ * wrapper annotation and directly specify several @ValueMapping annotations on one method.</strong>
+ *
+ * <p>These two examples are equal</p>
+ * <pre><code class='java'>
+ * // before Java 8
+ * &#64;Mapper
+ * public interface GenderMapper {
+ *     &#64;ValueMappings({
+ *         &#64;ValueMapping(source = "MALE", target = "M"),
+ *         &#64;ValueMapping(source = "FEMALE", target = "F")
+ *     })
+ *     GenderDto mapToDto(Gender gender);
+ * }
+ * </code></pre>
+ * <pre><code class='java'>
+ * //Java 8 and later
+ * &#64;Mapper
+ * public interface GenderMapper {
+ *     &#64;ValueMapping(source = "MALE", target = "M"),
+ *     &#64;ValueMapping(source = "FEMALE", target = "F")
+ *     GenderDto mapToDto(Gender gender);
+ * }
+ * </code></pre>
  *
  * @author Sjaak Derksen
  */