From 55c62ab43f150710e1939ed7b05b295a0d5dd8aa Mon Sep 17 00:00:00 2001 From: Filip Hrisafov Date: Sun, 13 Jun 2021 12:36:42 +0200 Subject: [PATCH] #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 --- .../java/org/mapstruct/DecoratedWith.java | 2 +- .../InheritInverseConfiguration.java | 2 +- core/src/main/java/org/mapstruct/Mapping.java | 1 - .../main/java/org/mapstruct/ValueMapping.java | 24 +++------ .../org/mapstruct/control/MappingControl.java | 2 +- distribution/pom.xml | 50 ++++++++++++++++--- .../mapstruct/ap/internal/model/Mapper.java | 4 ++ .../model/ObjectFactoryMethodResolver.java | 5 +- .../model/beanmapping/AbstractReference.java | 12 ++--- .../model/beanmapping/TargetReference.java | 2 +- .../model/source/BeanMappingOptions.java | 2 + .../internal/model/source/MappingOptions.java | 3 ++ .../model/source/SelectionParameters.java | 5 +- .../ap/internal/util/accessor/Accessor.java | 4 +- .../org/mapstruct/ap/spi/BuilderInfo.java | 11 ++++ 15 files changed, 85 insertions(+), 44 deletions(-) diff --git a/core/src/main/java/org/mapstruct/DecoratedWith.java b/core/src/main/java/org/mapstruct/DecoratedWith.java index 7f740a898..78b2c580f 100644 --- a/core/src/main/java/org/mapstruct/DecoratedWith.java +++ b/core/src/main/java/org/mapstruct/DecoratedWith.java @@ -22,7 +22,7 @@ import java.lang.annotation.Target; *

* NOTE: This annotation is not supported for the component model {@code cdi}. Use CDI's own * {@code @Decorator} feature instead. - *

+ *

*

Examples

*

* For the examples below, consider the following mapper declaration: diff --git a/core/src/main/java/org/mapstruct/InheritInverseConfiguration.java b/core/src/main/java/org/mapstruct/InheritInverseConfiguration.java index 3063ca07c..ac582a5df 100644 --- a/core/src/main/java/org/mapstruct/InheritInverseConfiguration.java +++ b/core/src/main/java/org/mapstruct/InheritInverseConfiguration.java @@ -59,7 +59,7 @@ import java.lang.annotation.Target; * } * } * - *

+ * * 


  * @Mapper
  * public interface CarMapper {
diff --git a/core/src/main/java/org/mapstruct/Mapping.java b/core/src/main/java/org/mapstruct/Mapping.java
index b4bfa30d8..0af73f368 100644
--- a/core/src/main/java/org/mapstruct/Mapping.java
+++ b/core/src/main/java/org/mapstruct/Mapping.java
@@ -372,7 +372,6 @@ public @interface Mapping {
      *     }
      *
*

- *

* Any types referenced in expressions must be given via their fully-qualified name. Alternatively, types can be * imported via {@link Mapper#imports()}. *

diff --git a/core/src/main/java/org/mapstruct/ValueMapping.java b/core/src/main/java/org/mapstruct/ValueMapping.java index 2d4a58636..21ea5f4a8 100644 --- a/core/src/main/java/org/mapstruct/ValueMapping.java +++ b/core/src/main/java/org/mapstruct/ValueMapping.java @@ -18,12 +18,9 @@ import java.lang.annotation.Target; *

    *
  1. Enumeration to Enumeration
    2. *
- *

- * Example 1: - * - * 

- * 
+ * Example 1:
  *
+ * 

  * 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;
  * +---------------------+----------------------------+
  * 

  *
- * 

- * Example 2:
- *
- * 
- * 
+ * Example 2:
  *
+ * 

  * @ValueMapping( source = MappingConstants.NULL, target = "DEFAULT" ),
  * @ValueMapping( source = "STANDARD", target = MappingConstants.NULL ),
  * @ValueMapping( source = MappingConstants.ANY_REMAINING, target = "SPECIAL" )
@@ -70,17 +64,13 @@ import java.lang.annotation.Target;
  * +---------------------+----------------------------+
  * 

  *
- * 

- * Example 3:
- * 

+ * Example 3:
  *
- * 
MapStruct will WARN on incomplete mappings. However, if for some reason no match is found, an
+ * MapStruct will WARN 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.
- * 
- * 
- *
+ * 

  * @ValueMapping( source = "STANDARD", target = "DEFAULT" ),
  * @ValueMapping( source = "C2C", target = MappingConstants.THROW_EXCEPTION )
  * ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
diff --git a/core/src/main/java/org/mapstruct/control/MappingControl.java b/core/src/main/java/org/mapstruct/control/MappingControl.java
index 1d416dafd..c44797602 100644
--- a/core/src/main/java/org/mapstruct/control/MappingControl.java
+++ b/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.
          * 

-         * 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
          */
diff --git a/distribution/pom.xml b/distribution/pom.xml
index 30beb1d31..337ad35e5 100644
--- a/distribution/pom.xml
+++ b/distribution/pom.xml
@@ -34,6 +34,11 @@
             org.freemarker
             freemarker
         
+        
+        
+            org.mapstruct.tools.gem
+            gem-api
+        
     
 
     
@@ -96,18 +101,16 @@
                             MapStruct API
                             org.mapstruct*
                         
+                        
+                            MapStruct Processor SPI
+                            org.mapstruct.ap.spi*
+                        
                         
                             MapStruct Processor
                             org.mapstruct.ap*
                         
                     
 
-                    org.jboss.apiviz.APIviz
-                    
-                        org.jboss.apiviz
-                        apiviz
-                        1.3.2.GA
-                    
                     true
                     UTF-8
                     UTF-8
@@ -116,6 +119,23 @@
                     true
                     true
                     true
+
+                    
+                    
+                        
+                            if (typeof useModuleDirectories !== 'undefined') {
+                              useModuleDirectories = false;
+                            }
+                            
+                        ]]>
+                    
+                    --allow-script-in-comments
+
                 
                 
                     
@@ -156,4 +176,22 @@
             
         
     
+
+    
+        
+            jdk-11-or-newer
+            
+                [11
+            
+            
+                
+                    javax.xml.bind
+                    jaxb-api
+                    2.3.1
+                    provided
+                    true
+                
+            
+        
+    
 
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java b/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java
index db63a8431..a066b123c 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/Mapper.java
+++ b/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)) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/ObjectFactoryMethodResolver.java b/processor/src/main/java/org/mapstruct/ap/internal/model/ObjectFactoryMethodResolver.java
index f0bd9c4df..397a001a4 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/ObjectFactoryMethodResolver.java
+++ b/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
      *
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/AbstractReference.java b/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/AbstractReference.java
index 4db93505e..72f2b8c8f 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/AbstractReference.java
+++ b/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
+     * @return the property name on the shallowest nesting level
      */
     public PropertyEntry getShallowestProperty() {
         if ( propertyEntries.isEmpty() ) {
@@ -67,8 +66,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the shallowest nesting level
-     * @return
+     * @return the property name on the shallowest nesting level
      */
     public String getShallowestPropertyName() {
         if ( propertyEntries.isEmpty() ) {
@@ -78,8 +76,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the deepest nesting level
-     * @return
+     * @return the property name on the deepest nesting level
      */
     public PropertyEntry getDeepestProperty() {
         if ( propertyEntries.isEmpty() ) {
@@ -89,8 +86,7 @@ public abstract class AbstractReference {
     }
 
     /**
-     * returns the property name on the deepest nesting level
-     * @return
+     * @return the property name on the deepest nesting level
      */
     public String getDeepestPropertyName() {
         if ( propertyEntries.isEmpty() ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/TargetReference.java b/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/TargetReference.java
index 22bfd6343..961e51956 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/beanmapping/TargetReference.java
+++ b/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() ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/source/BeanMappingOptions.java b/processor/src/main/java/org/mapstruct/ap/internal/model/source/BeanMappingOptions.java
index 78800e605..9567dd80b 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/source/BeanMappingOptions.java
+++ b/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) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java b/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java
index d7d6ad629..cb496a3a3 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/source/MappingOptions.java
+++ b/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,
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/source/SelectionParameters.java b/processor/src/main/java/org/mapstruct/ap/internal/model/source/SelectionParameters.java
index 697f0d9e4..fb76c1362 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/source/SelectionParameters.java
+++ b/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
-     * @return
+     * @param selectionParameters the selection parameters that need to be copied
+     *
+     * @return the selection parameters based on the given ones
      */
     public static SelectionParameters forInheritance(SelectionParameters selectionParameters) {
         return new SelectionParameters(
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java b/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java
index 314302a14..d624b7788 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java
+++ b/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
+     * @return type of the accessor
      */
     AccessorType getAccessorType();
 }
diff --git a/processor/src/main/java/org/mapstruct/ap/spi/BuilderInfo.java b/processor/src/main/java/org/mapstruct/ap/spi/BuilderInfo.java
index 0f9556748..5e37987f7 100644
--- a/processor/src/main/java/org/mapstruct/ap/spi/BuilderInfo.java
+++ b/processor/src/main/java/org/mapstruct/ap/spi/BuilderInfo.java
@@ -54,6 +54,10 @@ public class BuilderInfo {
         private Collection 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 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() {