#120 Moving BuildInMethod to the source model

processor/src/main/java/org/mapstruct/ap/builtin/BuiltInMappingMethods.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.HashSet;
 import org.mapstruct.ap.model.common.TypeFactory;
 

processor/src/main/java/org/mapstruct/ap/builtin/CalendarToXmlGregorianCalendar.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.Calendar;
 import java.util.GregorianCalendar;
 import java.util.Set;

processor/src/main/java/org/mapstruct/ap/builtin/DateToXmlGregorianCalendar.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.Date;
 import java.util.GregorianCalendar;
 import java.util.Set;

processor/src/main/java/org/mapstruct/ap/builtin/JaxbElemToValue.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import javax.xml.bind.JAXBElement;
 import org.mapstruct.ap.model.common.Parameter;
 import org.mapstruct.ap.model.common.Type;

processor/src/main/java/org/mapstruct/ap/builtin/ListOfJaxbElemToListOfValue.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.List;
 import javax.xml.bind.JAXBElement;
 import org.mapstruct.ap.model.common.Parameter;

processor/src/main/java/org/mapstruct/ap/builtin/StringToXmlGregorianCalendar.java

@@ -21,7 +21,7 @@ package org.mapstruct.ap.builtin;
 import java.text.DateFormat;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.GregorianCalendar;
 import java.util.Set;
 import javax.xml.datatype.DatatypeConfigurationException;

processor/src/main/java/org/mapstruct/ap/builtin/XmlGregorianCalendarToCalendar.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.Calendar;
 import javax.xml.datatype.XMLGregorianCalendar;
 import org.mapstruct.ap.model.common.Parameter;

processor/src/main/java/org/mapstruct/ap/builtin/XmlGregorianCalendarToDate.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.Date;
 import javax.xml.datatype.XMLGregorianCalendar;
 import org.mapstruct.ap.model.common.Parameter;

processor/src/main/java/org/mapstruct/ap/builtin/XmlGregorianCalendarToString.java

@@ -18,7 +18,7 @@
  */
 package org.mapstruct.ap.builtin;
 
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import javax.xml.datatype.XMLGregorianCalendar;
 import org.mapstruct.ap.model.common.ConversionContext;
 import org.mapstruct.ap.model.common.Parameter;

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

@@ -18,6 +18,7 @@
  */
 package org.mapstruct.ap.model;
 
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;

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

@@ -18,6 +18,7 @@
  */
 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;

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

@@ -26,30 +26,71 @@ import org.mapstruct.ap.model.common.Parameter;
 import org.mapstruct.ap.model.common.Type;
 
 /**
+ * This interface makes available common method properties and a matching method
  *
+ * There are 2 known implementors: {@link BuiltInMethod} and {@link Method}
  * @author Sjaak Derksen
  */
 public interface BasicMethod {
 
     /**
+     * Checks whether the provided sourceType and provided targetType match with the parameter respectively
+     * return type of the method. The check also should incorporate wild card and generic type variables
      *
-     * @param sourceType
+     * @param sourceType the sourceType to match to the parameter
-     * @param targetType
+     * @param targetType the targetType to match to the returnType
-     * @return
+     *
+     * @return true when match
      */
     boolean matches( Type sourceType, Type targetType );
 
-    List<Parameter> getSourceParameters();
+    /**
-
+     * Returns the mapper type declaring this method if it is not declared by the mapper interface currently processed
+     * but by another mapper imported via {@code Mapper#users()}.
+     *
+     * @return The declaring mapper type
+     */
     Type getDeclaringMapper();
 
+    /**
+     * Returns then name of the method.
+     *
+     * @return method name
+     */
     String getName();
 
+    /**
+     * In contrast to {@link #getSourceParameters()} this method returns all parameters
+     *
+     * @return all parameters
+     */
     List<Parameter> getParameters();
 
-    Type getReturnType();
+    /**
+     * returns the list of 'true' source parameters excluding the parameter(s) that is designated as
+     * target by means of the target annotation {@link  #getTargetParameter() }.
+     *
+     * @return list of 'true' source parameters
+     */
+    List<Parameter> getSourceParameters();
 
+    /**
+     * Returns the parameter designated as target parameter (if present) {@link #getSourceParameters() }
+     * @return target parameter (when present) null otherwise.
+     */
     Parameter getTargetParameter();
 
+    /**
+     * Returns the {@link Accessibility} of this method.
+     *
+     * @return the {@link Accessibility} of this method
+     */
     Accessibility getAccessibility();
+
+    /**
+     * Returns the return type of the method
+     *
+     * @return return type
+     */
+    Type getReturnType();
 }

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

@@ -16,7 +16,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  */
-package org.mapstruct.ap.model;
+package org.mapstruct.ap.model.source;
 
 import java.util.Arrays;
 import java.util.Collections;
@@ -28,7 +28,6 @@ import org.mapstruct.ap.model.common.ConversionContext;
 import org.mapstruct.ap.model.common.ModelElement;
 import org.mapstruct.ap.model.common.Parameter;
 import org.mapstruct.ap.model.common.Type;
-import org.mapstruct.ap.model.source.BasicMethod;
 import org.mapstruct.ap.util.Strings;
 
 /**
@@ -43,8 +42,9 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
 
 
     /**
-     * method name
+     * {@inheritDoc }
-     * @return default method name is equal to class name of build in mehtod
+     *
+     * @return default method name is equal to class name of build in method name
      */
     @Override
     public String getName() {
@@ -52,16 +52,23 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
     }
 
     /**
-     * imported types default. Only used types should be added. Source and Target types are coming via
+     * {@inheritDoc} {@link ModelElement}
-     * the MethodReference
      *
-     * @return set of used types.
+     * This method acts as a template. It should be overridden by implementors if deviation is required.
+     *
+     * @return set of used types. Default an empty set.
      */
     @Override
     public Set<Type> getImportTypes() {
         return Collections.<Type>emptySet();
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     *
+     * Default the targetType should be assignable to the returnType and the sourceType to the parameter,
+     * excluding generic type variables. When the implementor sees a need for this, this method can be overridden.
+     */
     @Override
     public boolean matches( Type sourceType, Type targetType ) {
         if ( targetType.erasure().isAssignableTo( getReturnType().erasure() )
@@ -72,6 +79,7 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
     }
 
     /**
+     * {@inheritDoc} {@link BasicMethod}
      *
      * @return all parameters are source parameters for build-in methods.
      */
@@ -81,7 +89,10 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
     }
 
     /**
-     * declaring mapper is always null, being the MapperImpl
+     * {@inheritDoc} {@link BasicMethod}
+     *
+     * declaring mapper is always null, being the MapperImpl itself. This method should not be overridden by
+     * implementors
      * @return null
      */
     @Override
@@ -89,6 +100,9 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
         return null;
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public List<Parameter> getParameters() {
         return Arrays.asList( new Parameter[] { getParameter() } );
@@ -117,7 +131,7 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
     }
 
     /**
-     * hashCode
+     * hashCode based on class
      *
      * @return hashCode
      */
@@ -141,7 +155,7 @@ public abstract class BuiltInMethod extends ModelElement implements BasicMethod
     }
 
     /**
-     * Analyzes the Java Generics type variables in the parameter do match the type variables in the build in method
+     * Analyzes the Java Generic type variables in the parameter do match the type variables in the build in method
      * same goes for the returnType.
      *
      * @param parameter source

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

@@ -132,10 +132,7 @@ public class Method implements BasicMethod {
     }
 
     /**
-     * Returns the mapper type declaring this method if it is not declared by the mapper interface currently processed
+     * {@inheritDoc} {@link BasicMethod}
-     * but by another mapper imported via {@code Mapper#users()}.
-     *
-     * @return The declaring mapper type
      */
     @Override
     public Type getDeclaringMapper() {
@@ -146,16 +143,25 @@ public class Method implements BasicMethod {
         return executable;
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public String getName() {
         return executable.getSimpleName().toString();
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public List<Parameter> getParameters() {
         return parameters;
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public List<Parameter> getSourceParameters() {
         List<Parameter> sourceParameters = new ArrayList<Parameter>();
@@ -183,11 +189,15 @@ public class Method implements BasicMethod {
         return targetParameter != null ? targetParameter.getType() : returnType;
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public Type getReturnType() {
         return returnType;
     }
 
+    @Override
     public Accessibility getAccessibility() {
         return accessibility;
     }
@@ -225,6 +235,9 @@ public class Method implements BasicMethod {
             && equals( getResultType(), method.getSourceParameters().iterator().next().getType() );
     }
 
+    /**
+     * {@inheritDoc} {@link BasicMethod}
+     */
     @Override
     public Parameter getTargetParameter() {
         return targetParameter;
@@ -298,10 +311,7 @@ public class Method implements BasicMethod {
     }
 
     /**
-     *
+     * {@inheritDoc} {@link BasicMethod}
-     * @param sourceType
-     * @param targetType
-     * @return
      */
     @Override
     public boolean matches( Type sourceType, Type targetType ) {

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

@@ -41,7 +41,7 @@ import org.mapstruct.ap.model.common.ConversionContext;
 import org.mapstruct.ap.conversion.ConversionProvider;
 import org.mapstruct.ap.conversion.Conversions;
 import org.mapstruct.ap.model.common.DefaultConversionContext;
-import org.mapstruct.ap.model.BuiltInMethod;
+import org.mapstruct.ap.model.source.BuiltInMethod;
 import org.mapstruct.ap.builtin.BuiltInMappingMethods;
 import org.mapstruct.ap.model.BeanMappingMethod;
 import org.mapstruct.ap.model.DefaultMapperReference;