#120 Formatting and commenting

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

@@ -18,12 +18,12 @@
  */
 package org.mapstruct.ap.model;
 
-import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.HashSet;
 import java.util.Set;
-import org.mapstruct.ap.model.common.ConversionContext;
 
+import org.mapstruct.ap.model.common.ConversionContext;
 import org.mapstruct.ap.model.common.Type;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import org.mapstruct.ap.model.source.SourceMethod;
 
 /**
@@ -34,8 +34,13 @@ import org.mapstruct.ap.model.source.SourceMethod;
 public class MethodReference extends MappingMethod {
 
     private final MapperReference declaringMapper;
-    private final String contextParam;
 
+    /**
+     * In case this reference targets a built-in method, allows to pass specific context information to the invoked
+     * method. Currently this is only used to pass in the configured date format string when invoking a built-in method
+     * which requires that.
+     */
+    private final String contextParam;
 
     public MethodReference(SourceMethod method, MapperReference declaringMapper) {
         super( method );
@@ -64,11 +69,4 @@ public class MethodReference extends MappingMethod {
     public String getContextParam() {
         return contextParam;
     }
-
-    private String quoteParamWhenNotNull(String param) {
-        if (param != null ) {
-            return param != null ? "\"" + param + "\"" : "null";
-        }
-        return null;
-    }
 }

processor/src/main/java/org/mapstruct/ap/model/common/ConversionContext.java

@@ -19,7 +19,7 @@
 package org.mapstruct.ap.model.common;
 
 /**
- * ConversionContext object passed to conversion providers.
+ * Context object passed to conversion providers and built-in methods.
  *
  * @author Gunnar Morling
  */
@@ -33,11 +33,11 @@ public interface ConversionContext {
     Type getTargetType();
 
     /**
-     * Returns the date format if this conversion is from String to
-     * {@link Date} or vice versa. Returns {@code null} for other types or
-     * if not given.
+     * Returns the date format if this conversion or built-in method is from String to a date type (e.g. {@link Date})
+     * or vice versa.
      *
-     * @return The date format if this conversion.
+     * @return The date format if this conversion or built-in method is from String to a date type. {@code null} is
+     *         returned for other types or if not given.
      */
     String getDateFormat();
 

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

@@ -93,6 +93,7 @@ public abstract class BuiltInMethod extends ModelElement implements Method {
      *
      * declaring mapper is always null, being the MapperImpl itself. This method should not be overridden by
      * implementors
+     *
      * @return null
      */
     @Override
@@ -110,6 +111,7 @@ public abstract class BuiltInMethod extends ModelElement implements Method {
 
     /**
      * target parameter mechanism not supported for build-in-method
+     *
      * @return null
      */
     @Override
@@ -122,6 +124,7 @@ public abstract class BuiltInMethod extends ModelElement implements Method {
      * with context specific information such as a date format.
      *
      * @param conversionContext
+     *
      * @return null if no context parameter should be included
      *         "null" if there should be an explicit null call
      *         "'dateFormat'" for instance, to indicate how the build-in method should format the date
@@ -144,6 +147,7 @@ public abstract class BuiltInMethod extends ModelElement implements Method {
      * equals based on class
      *
      * @param obj other class
+     *
      * @return true when classes are the same
      */
     @Override
@@ -160,6 +164,7 @@ public abstract class BuiltInMethod extends ModelElement implements Method {
      *
      * @param parameter source
      * @param returnType target
+     *
      * @return
      */
     public boolean doTypeVarsMatch(Type parameter, Type returnType) {

processor/src/main/java/org/mapstruct/ap/processor/MapperCreationProcessor.java

@@ -578,18 +578,20 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
             targetType = typeFactory.getReturnType( targetAcessor );
         }
 
-        // first try the SourceMethods
+        // first try the source methods
         String mappedElement = "property '" + Executables.getPropertyName( sourceAccessor ) + "'";
         MethodReference propertyMappingMethod = getMappingMethodReference(
             getBestMatch( method, mappedElement, methods, sourceType, targetType ),
-                mapperReferences );
+            mapperReferences
+        );
 
-        // then try BuiltInMethods
+        // then try built-in methods
         if ( propertyMappingMethod == null ) {
             propertyMappingMethod = getMappingMethodReference(
                 getBestMatch( method, mappedElement, builtInMethods.getBuiltInMethods(), sourceType, targetType ),
                 targetType,
-                    dateFormat );
+                dateFormat
+            );
         }
 
         TypeConversion conversion = getConversion(
@@ -636,18 +638,22 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
             )
         );
 
-        // first try the SourceMethods
+        // first try the source methods
         MethodReference elementMappingMethod = getMappingMethodReference(
             getBestMatch( method, "collection element", methods, sourceElementType, targetElementType ),
-                mapperReferences );
+            mapperReferences
+        );
 
-        // then try BuiltInMethods
+        // then try built-in methods
         if ( elementMappingMethod == null ) {
             elementMappingMethod = getMappingMethodReference(
-                    getBestMatch( method, "collection element", builtInMethods.getBuiltInMethods(), sourceElementType,
-                            targetElementType ),
+                getBestMatch(
+                    method, "collection element", builtInMethods.getBuiltInMethods(), sourceElementType,
+                    targetElementType
+                ),
                 targetElementType,
-                    dateFormat );
+                dateFormat
+            );
         }
 
         if ( !sourceElementType.isAssignableTo( targetElementType ) && conversion == null &&
@@ -693,29 +699,39 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
             "entry.getValue()"
         );
 
-        // first try the SourceMethods
+        // first try the source methods
         MethodReference keyMappingMethod = getMappingMethodReference(
-                getBestMatch( method, "map key", methods, sourceKeyType, targetKeyType ), mapperReferences );
+            getBestMatch( method, "map key", methods, sourceKeyType, targetKeyType ), mapperReferences
+        );
 
-        // then try BuiltInMethods
+        // then try built-in methods
         if ( keyMappingMethod == null ) {
             keyMappingMethod = getMappingMethodReference(
                 getBestMatch( method, "map key", builtInMethods.getBuiltInMethods(), sourceKeyType, targetKeyType ),
                 targetKeyType,
-                    keyDateFormat );
+                keyDateFormat
+            );
         }
 
-        // first try the SourceMethods
+        // first try the source methods
         MethodReference valueMappingMethod = getMappingMethodReference(
             getBestMatch( method, "map value", methods, sourceValueType, targetValueType ),
-                mapperReferences );
+            mapperReferences
+        );
 
-        // then try BuiltInMethods
+        // then try built-in methods
         if ( valueMappingMethod == null ) {
             valueMappingMethod = getMappingMethodReference(
-                    getBestMatch( method, "map value", builtInMethods.getBuiltInMethods(), sourceValueType, targetValueType ),
+                getBestMatch(
+                    method,
+                    "map value",
+                    builtInMethods.getBuiltInMethods(),
+                    sourceValueType,
+                    targetValueType
+                ),
                 targetValueType,
-                    valueDateFormat );
+                valueDateFormat
+            );
         }
 
         if ( !sourceKeyType.isAssignableTo( targetKeyType ) && keyConversion == null && keyMappingMethod == null ) {
@@ -764,7 +780,6 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
     }
 
 
-
     private <T extends Method> T getBestMatch(SourceMethod mappingMethod, String mappedElement,
                                               Iterable<T> methods, Type parameterType,
                                               Type returnType) {
@@ -820,7 +835,8 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
 
 
     private <T extends Method> int addToCandidateListIfMinimal(List<T> candidatesWithBestMathingType,
-                                            int bestMatchingTypeDistance, T method, int currentTypeDistance) {
+                                                               int bestMatchingTypeDistance, T method,
+                                                               int currentTypeDistance) {
         if ( currentTypeDistance == bestMatchingTypeDistance ) {
             candidatesWithBestMathingType.add( method );
         }
@@ -980,7 +996,7 @@ public class MapperCreationProcessor implements ModelElementProcessor<List<Sourc
 
     /**
      * A getter could be an alternative getReturnType-accessor if a setter is not available, and the
- getReturnType is a collection.
+     * getReturnType is a collection.
      *
      * Provided such a getter is initialized lazy by the getReturnType class, e.g. in generated JAXB beans.
      *