#2108 Make sure Javadoc can be generated with Java 11

Remove the org.jboss.apiviz.APIviz doclet since it is no longer compatible with Java 11.
Add new group in the Javadoc for the MapStruct Processor SPI
Fix Javadoc warnings

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

@@ -22,7 +22,7 @@ import java.lang.annotation.Target;
  * <p>
  * <b>NOTE:</b> This annotation is not supported for the component model {@code cdi}. Use CDI's own
  * <a href="https://docs.jboss.org/cdi/spec/1.0/html/decorators.html">{@code @Decorator}</a> feature instead.
- * <p>
+ * </p>
  * <h2>Examples</h2>
  * <p>
  * For the examples below, consider the following mapper declaration:

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

@@ -59,7 +59,7 @@ import java.lang.annotation.Target;
  *      }
  * }
  * </code></pre>
- * <p>
+ *
  * <pre><code class='java'>
  * &#64;Mapper
  * public interface CarMapper {

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

@@ -372,7 +372,6 @@ public @interface Mapping {
      *     }
      * </code></pre>
      * <p>
-     * <p>
      * Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be
      * imported via {@link Mapper#imports()}.
      * <p>

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

@@ -18,12 +18,9 @@ import java.lang.annotation.Target;
  * <ol>
  * <li>Enumeration to Enumeration</li>
  * </ol>
- * <p>
+ * <b>Example 1:</b>
- * <B>Example 1:</B>
- *
- * <pre>
- * <code>
  *
+ * <pre><code>
  * public enum OrderType { RETAIL, B2B, C2C, EXTRA, STANDARD, NORMAL }
  *
  * public enum ExternalOrderType { RETAIL, B2B, SPECIAL, DEFAULT }
@@ -46,12 +43,9 @@ import java.lang.annotation.Target;
  * +---------------------+----------------------------+
  * </pre>
  *
- * <p>
+ * <b>Example 2:</b>
- * <B>Example 2:</B>
- *
- * <pre>
- * <code>
  *
+ * <pre><code>
  * &#64;ValueMapping( source = MappingConstants.NULL, target = "DEFAULT" ),
  * &#64;ValueMapping( source = "STANDARD", target = MappingConstants.NULL ),
  * &#64;ValueMapping( source = MappingConstants.ANY_REMAINING, target = "SPECIAL" )
@@ -70,17 +64,13 @@ import java.lang.annotation.Target;
  * +---------------------+----------------------------+
  * </pre>
  *
- * <p>
+ * <b>Example 3:</b>
- * <B>Example 3:</B>
- * </p>
  *
- * <p></p>MapStruct will <B>WARN</B> on incomplete mappings. However, if for some reason no match is found, an
+ * MapStruct will <B>WARN</B> on incomplete mappings. However, if for some reason no match is found, an
  * {@link java.lang.IllegalStateException} will be thrown. This compile-time error can be avoided by
  * using {@link MappingConstants#THROW_EXCEPTION} for {@link ValueMapping#target()}. It will result an
  * {@link java.lang.IllegalArgumentException} at runtime.
- * <pre>
+ * <pre><code>
- * <code>
- *
  * &#64;ValueMapping( source = "STANDARD", target = "DEFAULT" ),
  * &#64;ValueMapping( source = "C2C", target = MappingConstants.THROW_EXCEPTION )
  * ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);

core/src/main/java/org/mapstruct/control/MappingControl.java

@@ -132,7 +132,7 @@ public @interface MappingControl {
          * This means if source type and target type are of the same type, MapStruct will not perform
          * any mappings anymore and assign the target to the source direct.
          * <p>
-         * An exception are types from the package {@link java}, which will be mapped always directly.
+         * An exception are types from the package {@code java}, which will be mapped always directly.
          *
          * @since 1.4
          */

distribution/pom.xml

@@ -34,6 +34,11 @@
             <groupId>org.freemarker</groupId>
             <artifactId>freemarker</artifactId>
         </dependency>
+        <!-- Needed here so references to MapStruct Gem classes can be resolved during JavaDoc generation -->
+        <dependency>
+            <groupId>org.mapstruct.tools.gem</groupId>
+            <artifactId>gem-api</artifactId>
+        </dependency>
     </dependencies>
 
     <build>
@@ -96,18 +101,16 @@
                             <title>MapStruct API</title>
                             <packages>org.mapstruct*</packages>
                         </group>
+                        <group>
+                            <title>MapStruct Processor SPI</title>
+                            <packages>org.mapstruct.ap.spi*</packages>
+                        </group>
                         <group>
                             <title>MapStruct Processor</title>
                             <packages>org.mapstruct.ap*</packages>
                         </group>
                     </groups>
 
-                    <doclet>org.jboss.apiviz.APIviz</doclet>
-                    <docletArtifact>
-                        <groupId>org.jboss.apiviz</groupId>
-                        <artifactId>apiviz</artifactId>
-                        <version>1.3.2.GA</version>
-                    </docletArtifact>
                     <useStandardDocletOptions>true</useStandardDocletOptions>
                     <charset>UTF-8</charset>
                     <encoding>UTF-8</encoding>
@@ -116,6 +119,23 @@
                     <version>true</version>
                     <author>true</author>
                     <keywords>true</keywords>
+
+                    <!--
+                        There is a bug in JDK 11 (https://bugs.openjdk.java.net/browse/JDK-8215291) which doesn't work correctly when searching and adds undefined.
+                        It has been fixed since JDK 12, but not yet backported to JDK 11 (https://bugs.openjdk.java.net/browse/JDK-8244171).
+                        One workardound is https://stackoverflow.com/a/57284322/1115491.
+                         -->
+                    <bottom>
+                        <![CDATA[
+                            <script>
+                            if (typeof useModuleDirectories !== 'undefined') {
+                              useModuleDirectories = false;
+                            }
+                            </script>
+                        ]]>
+                    </bottom>
+                    <additionalJOption>--allow-script-in-comments</additionalJOption>
+
                 </configuration>
                 <executions>
                     <execution>
@@ -156,4 +176,22 @@
             </plugin>
         </plugins>
     </build>
+
+    <profiles>
+        <profile>
+            <id>jdk-11-or-newer</id>
+            <activation>
+                <jdk>[11</jdk>
+            </activation>
+            <dependencies>
+                <dependency>
+                    <groupId>javax.xml.bind</groupId>
+                    <artifactId>jaxb-api</artifactId>
+                    <version>2.3.1</version>
+                    <scope>provided</scope>
+                    <optional>true</optional>
+                </dependency>
+            </dependencies>
+        </profile>
+    </profiles>
 </project>

processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java

@@ -162,6 +162,10 @@ public class Mapper extends GeneratedType {
 
     /**
      * Returns the same as {@link Class#getName()} but without the package declaration.
+     *
+     * @param element the element that should be flattened
+     *
+     * @return the flat name for the type element
      */
     public static String getFlatName(TypeElement element) {
         if (!(element.getEnclosingElement() instanceof TypeElement)) {

processor/src/main/java/org/mapstruct/ap/internal/model/ObjectFactoryMethodResolver.java

@@ -40,10 +40,9 @@ public class ObjectFactoryMethodResolver {
      *
      * @param method target mapping method
      * @param selectionParameters parameters used in the selection process
-     * @param ctx
+     * @param ctx the mapping builder context
      *
      * @return a method reference to the factory method, or null if no suitable, or ambiguous method found
-     *
      */
     public static MethodReference getFactoryMethod( Method method,
                                                     SelectionParameters selectionParameters,
@@ -57,7 +56,7 @@ public class ObjectFactoryMethodResolver {
      * @param method target mapping method
      * @param alternativeTarget alternative to {@link Method#getResultType()} e.g. when target is abstract
      * @param selectionParameters parameters used in the selection process
-     * @param ctx
+     * @param ctx the mapping builder context
      *
      * @return a method reference to the factory method, or null if no suitable, or ambiguous method found
      *

processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/AbstractReference.java

@@ -56,8 +56,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the shallowest nesting level
+     * @return the property name on the shallowest nesting level
-     * @return
      */
     public PropertyEntry getShallowestProperty() {
         if ( propertyEntries.isEmpty() ) {
@@ -67,8 +66,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the shallowest nesting level
+     * @return the property name on the shallowest nesting level
-     * @return
      */
     public String getShallowestPropertyName() {
         if ( propertyEntries.isEmpty() ) {
@@ -78,8 +76,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the deepest nesting level
+     * @return the property name on the deepest nesting level
-     * @return
      */
     public PropertyEntry getDeepestProperty() {
         if ( propertyEntries.isEmpty() ) {
@@ -89,8 +86,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the deepest nesting level
+     * @return the property name on the deepest nesting level
-     * @return
      */
     public String getDeepestPropertyName() {
         if ( propertyEntries.isEmpty() ) {

processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/TargetReference.java

@@ -80,7 +80,7 @@ public class TargetReference {
     }
 
     /**
-     * returns the property name on the shallowest nesting level
+     * @return the property name on the shallowest nesting level
      */
     public String getShallowestPropertyName() {
         if ( propertyEntries.isEmpty() ) {

processor/src/main/java/org/mapstruct/ap/internal/model/source/BeanMappingOptions.java

@@ -39,6 +39,8 @@ public class BeanMappingOptions extends DelegatingOptions {
     /**
      * creates a mapping for inheritance. Will set
      *
+     * @param beanMapping the bean mapping options that should be used
+     *
      * @return new mapping
      */
     public static BeanMappingOptions forInheritance(BeanMappingOptions beanMapping) {

processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java

@@ -502,6 +502,9 @@ public class MappingOptions extends DelegatingOptions {
     /**
      * Creates a copy of this mapping
      *
+     * @param templateMethod the template method for the inheritance
+     * @param beanMappingOptions the bean mapping options
+     *
      * @return the copy
      */
     public MappingOptions copyForForwardInheritance(SourceMethod templateMethod,

processor/src/main/java/org/mapstruct/ap/internal/model/source/SelectionParameters.java

@@ -34,8 +34,9 @@ public class SelectionParameters {
      *
      * ResultType is not inherited.
      *
-     * @param selectionParameters
+     * @param selectionParameters the selection parameters that need to be copied
-     * @return
+     *
+     * @return the selection parameters based on the given ones
      */
     public static SelectionParameters forInheritance(SelectionParameters selectionParameters) {
         return new SelectionParameters(

processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java

@@ -45,9 +45,7 @@ public interface Accessor {
     Element getElement();
 
     /**
-     * The accessor type
+     * @return type of the accessor
-     *
-     * @return
      */
     AccessorType getAccessorType();
 }

processor/src/main/java/org/mapstruct/ap/spi/BuilderInfo.java

@@ -54,6 +54,10 @@ public class BuilderInfo {
         private Collection<ExecutableElement> buildMethods;
 
         /**
+         * @param method The creation method for the builder
+         *
+         * @return the builder for chaining
+         *
          * @see BuilderInfo#getBuilderCreationMethod()
          */
         public Builder builderCreationMethod(ExecutableElement method) {
@@ -62,6 +66,10 @@ public class BuilderInfo {
         }
 
         /**
+         * @param methods the build methods for the type
+         *
+         * @return the builder for chaining
+         *
          * @see BuilderInfo#getBuildMethods()
          */
         public Builder buildMethod(Collection<ExecutableElement> methods) {
@@ -71,6 +79,9 @@ public class BuilderInfo {
 
         /**
          * Create the {@link BuilderInfo}.
+         *
+         * @return the created {@link BuilderInfo}
+         *
          * @throws IllegalArgumentException if the builder creation or build methods are {@code null}
          */
         public BuilderInfo build() {