#168 Some JavaDoc clarifications

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

@@ -26,8 +26,8 @@ import java.lang.annotation.Target;
 
 /**
  * Configures the mapping between two bean types.
- *
- * <p>Note: either @BeanMapping#resultType or @BeanMapping#qualifiedBy must be specified</p>
+ * <p>
+ * Either {@link #resultType()} or {@link #qualifiedBy()} must be specified.
  *
  * @author Sjaak Derksen
  */

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.
  * <p>
- * 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()}.
  * <p>
- * 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:
+ *
+ * <pre>
+ * {@code
+ * &#64;Mapping({
+ *     &#64;Mapping(target="make", source="brand"),
+ *     &#64;Mapping(target="seatCount", source="numberOfSeats")
+ * })
+ * CarDto carToCarDto(Car car);
+ *
+ * &#64;InheritConfiguration
+ * void updateCarDto(Car car, &#64;MappingTarget CarDto carDto);
+ * }
+ * </pre>
  *
  * @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.
      */

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.
      */

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.
  * <p>
- * 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.
- * </p>
+ * 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.
  * <p>
- * Mapping methods defined in the annotated type can be used as <em>prototypes</em> 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 <em>prototype mapping methods</em>. 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.
  * </p>
  *
  * @author Sjaak Derksen
+ * @see Mapper#config()
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)

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,