Note: either @BeanMapping#resultType or @BeanMapping#qualifiedBy must be specified
+ *+ * Either {@link #resultType()} or {@link #qualifiedBy()} must be specified. * * @author Sjaak Derksen */ diff --git a/core-common/src/main/java/org/mapstruct/InheritConfiguration.java b/core-common/src/main/java/org/mapstruct/InheritConfiguration.java index ccd7f57b1..d9bba63dd 100644 --- a/core-common/src/main/java/org/mapstruct/InheritConfiguration.java +++ b/core-common/src/main/java/org/mapstruct/InheritConfiguration.java @@ -24,14 +24,28 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Advises the code generator to apply all the {@link Mapping}s from a mapping method to the annotated method - * as well. The method should have the same source type and target type. + * Advises the code generator to apply the configuration (as given via {@link Mapping}, {@link IterableMapping} etc.) + * from another mapping method (declared on the same mapper type) or prototype method (declared on a mapper config class + * referenced via {@link Mapper#config()}) to the annotated method as well. *
- * A typical use case is annotating an update method (a method with the {@link MappingTarget} in which an existing - * target is updated) in order to copy all defined mappings. + * If no method can be identified unambiguously as configuration source (i.e. several candidate methods with matching + * source and target type exist), the name of the method to inherit from must be specified via {@link #name()}. *
- * If more than one matching method exists, the name of the method to inherit the configuration from must be - * specified via {@link #name()} + * A typical use case is annotating an update method so it inherits all mappings from a corresponding "standard" mapping + * method: + * + *
+ * {@code
+ * @Mapping({
+ * @Mapping(target="make", source="brand"),
+ * @Mapping(target="seatCount", source="numberOfSeats")
+ * })
+ * CarDto carToCarDto(Car car);
+ *
+ * @InheritConfiguration
+ * void updateCarDto(Car car, @MappingTarget CarDto carDto);
+ * }
+ *
*
* @author Sjaak Derksen
*/
@@ -40,8 +54,8 @@ import java.lang.annotation.Target;
public @interface InheritConfiguration {
/**
- * The name of the mapping method to inherit the mappings from. Needs only to be specified in case more than
- * one method with matching source and target type exists.
+ * The name of the mapping method to inherit the mappings from. Needs only to be specified in case more than one
+ * method with matching source and target type exists.
*
* @return The name of the mapping method to inherit the mappings from.
*/
diff --git a/core-common/src/main/java/org/mapstruct/Mapper.java b/core-common/src/main/java/org/mapstruct/Mapper.java
index f9540b6a5..1503890a0 100644
--- a/core-common/src/main/java/org/mapstruct/Mapper.java
+++ b/core-common/src/main/java/org/mapstruct/Mapper.java
@@ -26,8 +26,8 @@ import java.lang.annotation.Target;
import org.mapstruct.factory.Mappers;
/**
- * Marks an interface as mapper interface and activates the generation of a
- * mapper implementation for that interface.
+ * Marks an interface or abstract class as a mapper and activates the generation of a implementation of that type via
+ * MapStruct.
*
* @author Gunnar Morling
*/
@@ -36,7 +36,8 @@ import org.mapstruct.factory.Mappers;
public @interface Mapper {
/**
- * The mapper types used by this mapper.
+ * Other mapper types used by this mapper. May be hand-written classes or other mappers generated by MapStruct. No
+ * cycle between generated mapper classes must be created.
*
* @return The mapper types used by this mapper.
*/
diff --git a/core-common/src/main/java/org/mapstruct/MapperConfig.java b/core-common/src/main/java/org/mapstruct/MapperConfig.java
index 14ced439b..0b18b9b87 100644
--- a/core-common/src/main/java/org/mapstruct/MapperConfig.java
+++ b/core-common/src/main/java/org/mapstruct/MapperConfig.java
@@ -26,20 +26,23 @@ import java.lang.annotation.Target;
import org.mapstruct.factory.Mappers;
/**
- * Marks a class- or interface-declaration as (common) configuration.
+ * Marks a class or interface as configuration source for generated mappers. This allows to share common configurations
+ * between several mapper classes.
* - * The {@link #unmappedTargetPolicy() } and {@link #componentModel() } can be overruled by a specific {@link Mapper} - * annotation. {@link #uses() } will be used in addition to what is specified in the {@link Mapper} annotation. - *
+ * Generally, any settings given via {@link Mapper} take precedence over the settings given via the referenced + * {@code MapperConfig}. The lists of referenced mappers given via {@link Mapper#uses()} and + * {@link MapperConfig#uses()} will be merged. *- * Mapping methods defined in the annotated type can be used as prototypes from which method-level annotations - * such as {@code @Mapping}, {@code @IterableMapping}, etc. can be inherited. Depending on the configured + * Additionally, mapper configuration classes may declare one more prototype mapping methods. These methods are + * not meant to be invoked themselves (no implementation will generated for mapper config classes), but serve as + * configuration template for mapping methods declared by actual mapper classes. Depending on the configured * {@link #mappingInheritanceStrategy()}, the configuration can be inherited either explicitly using * {@link InheritConfiguration} or {@link InheritInverseConfiguration}, or automatically in case all source and target * types are assignable. *
* * @author Sjaak Derksen + * @see Mapper#config() */ @Target(ElementType.TYPE) @Retention(RetentionPolicy.CLASS) diff --git a/core-common/src/main/java/org/mapstruct/MappingInheritanceStrategy.java b/core-common/src/main/java/org/mapstruct/MappingInheritanceStrategy.java index 7f9f44d04..678dde68f 100644 --- a/core-common/src/main/java/org/mapstruct/MappingInheritanceStrategy.java +++ b/core-common/src/main/java/org/mapstruct/MappingInheritanceStrategy.java @@ -19,8 +19,8 @@ package org.mapstruct; /** - * The strategy to use for applying method-level configuration annotations of prototype methods in the interface - * specified with {@link Mapper#config()}. + * Strategy for inheriting configurations given for methods of prototype mapping methods (declared on mapper config + * classes) to actual mapping methods declared on mappers referring to such config class via {@link Mapper#config()}. * * @author Andreas Gudian */ @@ -32,8 +32,8 @@ public enum MappingInheritanceStrategy { EXPLICIT, /** - * Apply the method-level configuration annotations if source and target types of the prototype method are - * assignable from the types of a given mapping method. + * Inherit the method-level configuration annotations automatically if source and target types of the prototype + * method are assignable from the types of a given mapping method. */ AUTO_INHERIT_FROM_CONFIG,