Fixing Javadoc issues

core-common/pom.xml

@@ -33,6 +33,10 @@
     <packaging>jar</packaging>
     <name>MapStruct Core Common</name>
 
+    <properties>
+        <maven.javadoc.skip>true</maven.javadoc.skip>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>junit</groupId>

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

@@ -44,7 +44,7 @@ public @interface Mapper {
 
     /**
      * Additional types for which an import statement is to be added to the generated mapper implementation class.
-     * This allows to refer to those types from within mapping expressions given via {@link #expression()} using
+     * This allows to refer to those types from within mapping expressions given via {@link Mapping#expression()} using
      * their simple name rather than their fully-qualified name.
      *
      * @return classes to add in the imports of the generated implementation.

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

@@ -24,29 +24,27 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Declares a target annotation to be a qualifier.
- *
+ * 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:
- * <ol>
+ * <ul>
  * <li>{@link Mapping#qualifiedBy() }</li>
  * <li>{@link IterableMapping#qualifiedBy() }</li>
  * <li>{@link MapMapping#keyQualifiedBy() }</li>
  * <li>{@link MapMapping#valueQualifiedBy() }</li>
- * </p>
- * <p>
- * <code>
- * @Qualifier
- * @Target(ElementType.METHOD)
- * @Retention(RetentionPolicy.SOURCE)
- * public @interface EnglishToGerman {
- * }
- * </code>
- * </p>
+ * </ul>
+ * Example:
+ * <pre>
+ * &#64;Qualifier
+ * &#64;Target(ElementType.METHOD)
+ * &#64;Retention(RetentionPolicy.SOURCE)
+ * public &#64;interface EnglishToGerman {}
+ * </pre>
  *
  * @author Sjaak Derksen
  */
-@Target(ElementType.ANNOTATION_TYPE)
-@Retention(RetentionPolicy.CLASS)
+@Target( ElementType.ANNOTATION_TYPE )
+@Retention( RetentionPolicy.CLASS )
 public @interface Qualifier {
 }

processor/src/main/java/org/mapstruct/ap/model/MappingBuilderContext.java

@@ -37,17 +37,6 @@ import org.mapstruct.ap.option.Options;
 
 /**
  * This class provides the context for the builders.
- *
- * <p>
- * The following builders make use of this context:
- * <ul>
- * <li>{@link BeanMappingMethod.Builder}</li>
- * <li>{@link PropertyMappingMethod.Builder}</li>
- * <li>{@link IterableMappingMethod.Builder}</li>
- * <li>{@link MapMappingMethod.Builder}</li>
- * <li>{@link EnumMappingMethod.Builder}</li>
- * </ul>
- * </p>
  * <p>
  * The context provides:
  * <ul>
@@ -56,7 +45,6 @@ import org.mapstruct.ap.option.Options;
  * <li>Means to harbor results produced by the builders, such as forged- and virtual mapping methods that should be
  * generated in a later stage.</li>
  * </ul>
- * </p>
  *
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/model/source/SourceReference.java

@@ -38,17 +38,17 @@ import org.mapstruct.ap.util.Strings;
  * It contains the source parameter, and all individual (nested) property entries. So consider the following
  * mapping method:
  *
- * {@code
- * @Mapping( source = "in.propA.propB" target = "propC" )
- * TypeB mappingMethod ( TypeA in );
- * }
+ * <pre>
+ * &#64;Mapping(source = "in.propA.propB" target = "propC")
+ * TypeB mappingMethod(TypeA in);
+ * </pre>
  *
  * Then:
- * <ol>
- * <li>{@link #parameter} will describe {@code in}</li>
- * <li>{@link #propertyEntries[0]} will describe {@code propA}</li>
- * <li>{@link #propertyEntries[1]} will describe {@code propB}</li>
- * </ol>
+ * <ul>
+ * <li>{@code parameter} will describe {@code in}</li>
+ * <li>{@code propertyEntries[0]} will describe {@code propA}</li>
+ * <li>{@code propertyEntries[1]} will describe {@code propB}</li>
+ * </ul>
  *
  * After building, {@link #isValid()} will return true when when no problems are detected during building.
  *

processor/src/main/java/org/mapstruct/ap/model/source/builtin/CalendarToZonedDateTime.java

@@ -18,6 +18,9 @@
  */
 package org.mapstruct.ap.model.source.builtin;
 
+import static org.mapstruct.ap.util.Collections.asSet;
+
+import java.time.ZonedDateTime;
 import java.util.Calendar;
 import java.util.Set;
 import java.util.TimeZone;
@@ -27,12 +30,9 @@ import org.mapstruct.ap.model.common.Type;
 import org.mapstruct.ap.model.common.TypeFactory;
 import org.mapstruct.ap.util.JavaTimeConstants;
 
-import static org.mapstruct.ap.util.Collections.asSet;
-
 /**
- * {@link BuiltInMethod} for mapping between {@link java.util.Calendar}
- * and {@link java.time.ZonedDateTime}.
- * <br />
+ * {@link BuiltInMethod} for mapping between {@link Calendar} and {@link ZonedDateTime}.
+ * <p>
  * Template is at org.mapstruct.ap.model.builtin.CalendarToZonedDateTime.ftl
  */
 public class CalendarToZonedDateTime extends BuiltInMethod {

processor/src/main/java/org/mapstruct/ap/model/source/builtin/ZonedDateTimeToCalendar.java

@@ -18,6 +18,7 @@
  */
 package org.mapstruct.ap.model.source.builtin;
 
+import java.time.ZonedDateTime;
 import java.util.Calendar;
 import java.util.Set;
 
@@ -28,9 +29,8 @@ import org.mapstruct.ap.util.Collections;
 import org.mapstruct.ap.util.JavaTimeConstants;
 
 /**
- * {@link BuiltInMethod} for mapping between {@link java.util.Calendar}
- * and {@link java.time.ZonedDateTime}.
- * <br />
+ * {@link BuiltInMethod} for mapping between {@link Calendar} and {@link ZonedDateTime}.
+ * <p>
  * Template is at org.mapstruct.ap.model.builtin.ZonedDateTimeToCalendar.ftl
  */
 public class ZonedDateTimeToCalendar extends BuiltInMethod {

processor/src/main/java/org/mapstruct/ap/model/source/selector/QualifierSelector.java

@@ -45,7 +45,6 @@ import org.mapstruct.ap.prism.QualifierPrism;
  * removed from the list of potential mapping methods</li>
  * <li>If multiple qualifiers (qualifedBy) are specified, all should match to make a match.</li>
  * </ol>
- * </p>
  *
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/util/SpecificCompilerWorkarounds.java

@@ -36,7 +36,7 @@ public class SpecificCompilerWorkarounds {
     /**
      * Tests whether one type is a subtype of another. Any type is considered to be a subtype of itself. Also see <a
      * href="http://docs.oracle.com/javase/specs/jls/se8/html/jls-4.html">JLS section 4.10, Subtyping</a>.
-     * <p />
+     * <p>
      * Work-around for a bug related to sub-typing in the Eclipse JSR 269 implementation.
      *
      * @param types the type utils
@@ -55,15 +55,15 @@ public class SpecificCompilerWorkarounds {
 
     /**
      * Returns the erasure of a type.
-     * <p/>
+     * <p>
      * Performs an additional test on the given type to check if it is not void. Calling
-     * {@link Types#erasure(TypeMirror)} with a void kind type will create a ClassCastException in Eclipse JDT.
+     * {@link Types#erasure(TypeMirror)} with a void kind type will create a ClassCastException in Eclipse JDT. See the
+     * JLS, section 4.6 Type Erasure, for reference.
      *
      * @param types the type utils
      * @param t the type to be erased
      * @return the erasure of the given type
      * @throws IllegalArgumentException if given a package type
-     * @jls 4.6 Type Erasure
      */
     public static TypeMirror erasure(Types types, TypeMirror t) {
         if ( t.getKind() == TypeKind.VOID || t.getKind() == TypeKind.NULL ) {