#750 Further expanding comment

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

@@ -57,11 +57,17 @@ public @interface IterableMapping {
     Class<? extends Annotation>[] qualifiedBy() default { };
 
     /**
-     * See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this iterable mapping method's
-     * is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
+     * element type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the
-     * is no need to define own annotations.
+     * class-level) a {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
      *
-     * @return the qualifiers
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
      */
     String[] qualifiedByName() default { };
 

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

@@ -66,11 +66,17 @@ public @interface MapMapping {
     Class<? extends Annotation>[] keyQualifiedBy() default { };
 
     /**
-     * See: { @link #keyQualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's key
-     * is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
+     * type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a
-     * is no need to define own annotations.
+     * {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
      *
-     * @return the qualifiers
+     * @return One or more qualifier name(s)
+     * @see #keyQualifiedBy()
+     * @see Named
      */
     String[] keyQualifiedByName() default { };
 
@@ -87,11 +93,17 @@ public @interface MapMapping {
     Class<? extends Annotation>[] valueQualifiedBy() default { };
 
     /**
-     * See: { @link #valueQualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
+     * String-based form of qualifiers; When looking for a suitable mapping method to map this map mapping method's value
-     * is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
+     * type, MapStruct will only consider those methods carrying directly or indirectly (i.e. on the class-level) a
-     * is no need to define own annotations.
+     * {@link Named} annotation for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
      *
-     * @return the qualifiers
+     * @return One or more qualifier name(s)
+     * @see #valueQualifiedBy()
+     * @see Named
      */
     String[] valueQualifiedByName() default { };
 

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

@@ -24,19 +24,14 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * String-based qualifier.
+ * Marks mapping methods with the given qualifier name. Can be used to qualify a single method or all methods of a given
- *
+ * type by specifying this annotation on the type level.
  * <p>
- * For more info see:
+ * Will be used to to select the correct mapping methods when mapping a bean property type, element of an iterable type
- * <ul>
+ * or the key/value of a map type.
- * <li>{@link Mapping#qualifiedByName() }</li>
- * <li>{@link IterableMapping#qualifiedByName() }</li>
- * <li>{@link MapMapping#keyQualifiedByName() }</li>
- * <li>{@link MapMapping#valueQualifiedByName() }</li>
- * </ul>
- *
  * <p>
- * Example:
+ * Example (both methods of {@code Titles} are capable to convert a string, but the ambiguity is resolved by applying
+ * the qualifiers in {@code @Mapping}:
  *
  * <pre>
  * <code>
@@ -61,36 +56,46 @@ import java.lang.annotation.Target;
  *    GermanRelease toGerman( OriginalRelease movies );
  *
  * }
- *
- * Will generate:
- *
- *  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.translateTitleEG( movies.getTitle() ) );
- *
- *      return germanRelease;
- *  }
  * </code>
  * </pre>
  *
+ * The following implementation of {@code MovieMapper} will be generated:
+ *
+ * <pre>
+ * <code>
+ *
+ * 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.translateTitleEG( movies.getTitle() ) );
+ *
+ *         return germanRelease;
+ *     }
+ * }
+ * </code>
+ * </pre>
  *
  * @author Sjaak Derksen
+ * @see org.mapstruct.Mapping#qualifiedByName()
+ * @see IterableMapping#qualifiedByName()
+ * @see MapMapping#keyQualifiedByName()
+ * @see MapMapping#valueQualifiedByName()
  */
 @Target( { ElementType.TYPE, ElementType.METHOD } )
 @Retention( RetentionPolicy.RUNTIME )
 @Qualifier
 public @interface Named {
+
     /**
-     *
+     * A name qualifying the annotated element
-     * @return the name
      */
     String value();
 }

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

@@ -138,11 +138,17 @@ public @interface Mapping {
     Class<? extends Annotation>[] qualifiedBy() default { };
 
     /**
-     * See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
+     * String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will
-     * is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
+     * only consider those methods carrying directly or indirectly (i.e. on the class-level) a {@link Named} annotation
-     * is no need to define own annotations.
+     * for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
      *
-     * @return the qualifiers
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
      */
     String[] qualifiedByName() default { };
 

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

@@ -136,11 +136,17 @@ public @interface Mapping {
     Class<? extends Annotation>[] qualifiedBy() default { };
 
     /**
-     * See: { @link #qualifiedBy() }. String form of a predefined { @link @Qualifier }. The { @link @Qualifier }
+     * String-based form of qualifiers; When looking for a suitable mapping method for a given property, MapStruct will
-     * is more verbose, but offers more flexibility in terms of for instance refactoring. At the other hand, there
+     * only consider those methods carrying directly or indirectly (i.e. on the class-level) a {@link Named} annotation
-     * is no need to define own annotations.
+     * for each of the specified qualifier names.
+     * <p>
+     * Note that annotation-based qualifiers are generally preferable as they allow more easily to find references and
+     * are safe for refactorings, but name-based qualifiers can be a less verbose alternative when requiring a large
+     * number of qualifiers as no custom annotation types are needed.
      *
-     * @return the qualifiers
+     * @return One or more qualifier name(s)
+     * @see #qualifiedBy()
+     * @see Named
      */
     String[] qualifiedByName() default { };