From 40669a0f8a19de4ab406a0adc6e50fd1a0088b64 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 22 Feb 2014 22:29:59 +0100 Subject: [PATCH] #120 Minor doc improvements --- .../org/mapstruct/ap/model/source/Method.java | 4 +- .../ap/model/source/MethodMatcher.java | 27 ++++------ .../model/source/builtin/BuiltInMethod.java | 51 ++++++++----------- 3 files changed, 34 insertions(+), 48 deletions(-) diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/Method.java b/processor/src/main/java/org/mapstruct/ap/model/source/Method.java index 473133022..7ad65143a 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/Method.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/Method.java @@ -30,6 +30,7 @@ import org.mapstruct.ap.model.source.builtin.BuiltInMethod; * 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 Method { @@ -43,7 +44,7 @@ public interface Method { * * @return true when match */ - boolean matches( Type sourceType, Type targetType ); + boolean matches(Type sourceType, Type targetType); /** * Returns the mapper type declaring this method if it is not declared by the mapper interface currently processed @@ -77,6 +78,7 @@ public interface Method { /** * Returns the parameter designated as target parameter (if present) {@link #getSourceParameters() } + * * @return target parameter (when present) null otherwise. */ Parameter getTargetParameter(); diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/MethodMatcher.java b/processor/src/main/java/org/mapstruct/ap/model/source/MethodMatcher.java index 222396817..b488774ce 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/MethodMatcher.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/MethodMatcher.java @@ -40,11 +40,11 @@ import org.mapstruct.ap.model.common.Type; * SourceMethodMatcher $8.4 of the JavaLanguage specification describes a method body as such: * * 
- SourceMethodDeclaration: SourceMethodHeader SourceMethodBody
- SourceMethodHeader: SourceMethodModifiers TypeParameters Result SourceMethodDeclarator Throws
- SourceMethodDeclarator: Identifier ( FormalParameterList )
-
- example <T extends String & Serializable>  T   getResult(? extends T) throws Exception
+ * SourceMethodDeclaration: SourceMethodHeader SourceMethodBody
+ * SourceMethodHeader: SourceMethodModifiers TypeParameters Result SourceMethodDeclarator Throws
+ * SourceMethodDeclarator: Identifier ( FormalParameterList )
+ *
+ * example <T extends String & Serializable>  T   getResult(? extends T) throws Exception
  *         \-------------------------------/ \-/            \---------/
  *               TypeParameters             Result        ParameterList
  *
@@ -66,26 +66,21 @@ public class MethodMatcher { private final Types typeUtils; private final Map genericTypesMap = new HashMap(); - /** - * package scope constructor - * - * @param typeUtils - * @param candidateMethod - */ MethodMatcher(Types typeUtils, SourceMethod candidateMethod) { this.typeUtils = typeUtils; this.candidateMethod = candidateMethod; } /** - * package scoped method + * Whether the given source and target type are matched by this matcher's candidate method. * - * @param sourceType - * @param targetType + * @param sourceType the source type + * @param targetType the target type * - * @return true when both, sourceType and targetType matches the signature. + * @return {@code true} when both, source type and target type match the signature of this matcher's method; + * {@code false} otherwise. */ - boolean matches( Type sourceType, Type targetType ) { + boolean matches(Type sourceType, Type targetType) { // check & collect generic types. List candidateParameters = candidateMethod.getExecutable().getParameters(); diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/builtin/BuiltInMethod.java b/processor/src/main/java/org/mapstruct/ap/model/source/builtin/BuiltInMethod.java index 673fb8d10..95588492a 100644 --- a/processor/src/main/java/org/mapstruct/ap/model/source/builtin/BuiltInMethod.java +++ b/processor/src/main/java/org/mapstruct/ap/model/source/builtin/BuiltInMethod.java @@ -23,24 +23,22 @@ import java.util.Collections; import java.util.List; import java.util.Set; +import org.mapstruct.ap.conversion.SimpleConversion; import org.mapstruct.ap.model.common.Accessibility; 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.Method; import org.mapstruct.ap.util.Strings; /** - * Implementations create: - * 1) an implementation of this build in method. - * 2) a reference to a build in method, to use in property mappings - * 3) a name for logging purposes. + * Represents a "built-in" mapping method which will be added as private method to the generated mapper. Built-in + * methods are used in cases where a {@link SimpleConversion} doesn't suffice, e.g. as several lines of source code or a + * try/catch block are required. * * @author Sjaak Derksen */ -public abstract class BuiltInMethod extends ModelElement implements Method { - +public abstract class BuiltInMethod implements Method { /** * {@inheritDoc } @@ -53,20 +51,19 @@ public abstract class BuiltInMethod extends ModelElement implements Method { } /** - * {@inheritDoc} {@link ModelElement} + * Returns the types used by this method for which import statements need to be generated. Defaults to the empty + * set. To be overridden by implementations in case they make use of additional types (note that the parameter and + * return type don't need to be added). * - * 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. + * @return the types used by this method for which import statements need to be generated */ - @Override public Set getImportTypes() { return Collections.emptySet(); } /** - * {@inheritDoc} {@link Method} - * + * {@inheritDoc} + *

* 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. */ @@ -79,41 +76,33 @@ public abstract class BuiltInMethod extends ModelElement implements Method { return false; } - /** - * {@inheritDoc} {@link Method} - * - * @return all parameters are source parameters for build-in methods. - */ @Override public List getSourceParameters() { return getParameters(); } /** - * {@inheritDoc} {@link Method} + * {@inheritDoc} + *

+ * For built-in methods, the declaring mapper is always {@code null} as they will be added as private methods to the + * generated mapper. * - * declaring mapper is always null, being the MapperImpl itself. This method should not be overridden by - * implementors - * - * @return null + * @return {@code null} */ @Override - public Type getDeclaringMapper() { + public final Type getDeclaringMapper() { return null; } - /** - * {@inheritDoc} {@link Method} - */ @Override public List getParameters() { - return Arrays.asList( new Parameter[] { getParameter() } ); + return Arrays.asList( getParameter() ); } /** - * target parameter mechanism not supported for build-in-method + * target parameter mechanism not supported for built-in methods * - * @return null + * @return {@code null} */ @Override public Parameter getTargetParameter() {