#494 Fix javadoc errors popping up during the build

core-common/src/main/java/org/mapstruct/InheritConfiguration.java

@@ -35,7 +35,7 @@ import java.lang.annotation.Target;
  * method:
  *
  * <pre>
- * {@code
+ * <code>
  * &#64;Mappings({
  *     &#64;Mapping(target="make", source="brand"),
  *     &#64;Mapping(target="seatCount", source="numberOfSeats")
@@ -44,7 +44,7 @@ import java.lang.annotation.Target;
  *
  * &#64;InheritConfiguration
  * void updateCarDto(Car car, &#64;MappingTarget CarDto carDto);
- * }
+ * </code>
  * </pre>
  *
  * @author Sjaak Derksen

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

@@ -94,7 +94,6 @@ public @interface Mapping {
      * <p>
      * Currently, Java is the only supported "expression language" and expressions must be given in form of Java
      * expressions using the following format: {@code java(<EXPRESSION>)}. For instance the mapping
-     * <p>
      *
      * <pre>
      * {@code @Mapping(

processor/src/main/java/org/mapstruct/ap/conversion/AbstractJodaTypeToStringConversion.java

@@ -110,12 +110,12 @@ public abstract class AbstractJodaTypeToStringConversion extends SimpleConversio
     }
 
     /**
-     * Returns the default format style to be applied if non is given explicitly.
+     * @return the default format style to be applied if non is given explicitly.
      */
     protected abstract String formatStyle();
 
     /**
-     * Returns the name of the parse method for converting a String into a specific Joda-Time type.
+     * @return the name of the parse method for converting a String into a specific Joda-Time type.
      */
     protected abstract String parseMethod();
 }

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

@@ -528,8 +528,6 @@ public class BeanMappingMethod extends MappingMethod {
          * be returned. If that is not set either, the default value from {@code Mapper#unmappedTargetPolicy()} will be
          * returned.
          *
-         * @param element The type declaring the generated mapper type
-         *
          * @return The effective policy for reporting unmapped target properties.
          */
         private ReportingPolicy getEffectiveUnmappedTargetPolicy() {

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

@@ -29,6 +29,7 @@ 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 static org.mapstruct.ap.util.Strings.getSaveVariableName;
 import static org.mapstruct.ap.util.Strings.join;
 
@@ -49,11 +50,11 @@ public abstract class MappingMethod extends ModelElement {
     private final String resultName;
 
     /**
-     * constructor to be overloaded when local variable names are required prior to calling this constructor. (e.g.
+     * constructor to be overloaded when local variable names are required prior to calling this constructor. (e.g. for
-     * for property mappings). It is supposed to be initialized with at least the parameter names.
+     * property mappings). It is supposed to be initialized with at least the parameter names.
      *
-     * @param method
+     * @param method method
-     * @param existingVariableNames
+     * @param existingVariableNames existingVariableNames
      */
     protected MappingMethod(Method method, Collection<String> existingVariableNames ) {
         this.name = method.getName();

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

@@ -680,7 +680,7 @@ public class PropertyMapping extends ModelElement {
     }
 
     /**
-     * Returns the name of this mapping (property name on the target side)
+     * @return the name of this mapping (property name on the target side)
      */
     public String getName() {
         return name;

processor/src/main/java/org/mapstruct/ap/model/assignment/Assignment.java

@@ -20,6 +20,7 @@ package org.mapstruct.ap.model.assignment;
 
 import java.util.List;
 import java.util.Set;
+
 import org.mapstruct.ap.model.common.Type;
 
 /**
@@ -59,14 +60,14 @@ public interface Assignment {
      List<Type> getExceptionTypes();
 
      /**
-      * An assignment in itself can wrap another assignment. E.g.:
+     * An assignment in itself can wrap another assignment. E.g.:
-      * <ul>
+     * <ul>
-      * <li>a MethodReference can wrap a TypeConversion, another MethodReference and ultimately a Simple</li>
+     * <li>a MethodReference can wrap a TypeConversion, another MethodReference and ultimately a Simple</li>
-      * <li>a TypeConversion can wrap a MethodReference, and ultimately a Simple</li>
+     * <li>a TypeConversion can wrap a MethodReference, and ultimately a Simple</li>
-      * </ul>
+     * </ul>
-      *
+     *
-      * @param assignment
+     * @param assignment the assignment to set
-      */
+     */
      void setAssignment( Assignment assignment );
 
      /**

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

@@ -185,7 +185,7 @@ public class Type extends ModelElement implements Comparable<Type> {
     }
 
     /**
-     * Returns this type's enum constants in case it is an enum, an empty list otherwise.
+     * @return this type's enum constants in case it is an enum, an empty list otherwise.
      */
     public List<String> getEnumConstants() {
         return enumConstants;
@@ -256,7 +256,7 @@ public class Type extends ModelElement implements Comparable<Type> {
     }
 
     /**
-     * The name of this type as to be used within import statements.
+     * @return The name of this type as to be used within import statements.
      */
     public String getImportName() {
         return isArrayType() ? qualifiedName.substring( 0, qualifiedName.length() - 2 ) : qualifiedName;
@@ -369,18 +369,16 @@ public class Type extends ModelElement implements Comparable<Type> {
     }
 
     /**
-     * getPropertyWriteAccessors returns a map of the write accessors according to the CollectionMappingStrategy.
+     * getPropertyWriteAccessors returns a map of the write accessors according to the CollectionMappingStrategy. These
-     *
+     * accessors include:
-     * These accessors include:
-     *
      * <ul>
-     *  <li>setters, the obvious candidate :-), {@link #getSetters() }</li>
+     * <li>setters, the obvious candidate :-), {@link #getSetters() }</li>
-     *  <li>getters, for collections that do not have a setter, e.g. for JAXB generated collection attributes
+     * <li>getters, for collections that do not have a setter, e.g. for JAXB generated collection attributes
      * {@link #getPropertyReadAccessors() }</li>
-     *  <li>adders, typically for from table generated entities, {@link #getAdders() }</li>
+     * <li>adders, typically for from table generated entities, {@link #getAdders() }</li>
      * </ul>
      *
-     * @param cmStrategy
+     * @param cmStrategy collection mapping strategy
      * @return an unmodifiable map of all write accessors indexed by property name
      */
     public Map<String, ExecutableElement> getPropertyWriteAccessors( CollectionMappingStrategyPrism cmStrategy ) {
@@ -619,7 +617,9 @@ public class Type extends ModelElement implements Comparable<Type> {
     }
 
     /**
-     * Whether this type can access the given method declared on the given type.
+     * @param type the type declaring the method
+     * @param method the method to check
+     * @return Whether this type can access the given method declared on the given type.
      */
     public boolean canAccess(Type type, ExecutableElement method) {
         if ( method.getModifiers().contains( Modifier.PRIVATE ) ) {
@@ -637,8 +637,8 @@ public class Type extends ModelElement implements Comparable<Type> {
     }
 
     /**
-     * @return A valid Java expression most suitable for representing null - useful for dealing with primitives
+     * @return A valid Java expression most suitable for representing null - useful for dealing with primitives from
-     * from FTL.
+     *         FTL.
      */
     public String getNull() {
         if ( !isPrimitive() || isArrayType() ) {

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

@@ -254,8 +254,8 @@ public class TypeFactory {
      * Get the ExecutableType for given method as part of usedMapper. Possibly parameterized types in method declaration
      * will be evaluated to concrete types then.
      *
-     * @param usedMapper
+     * @param usedMapper the type declaring the method
-     * @param method
+     * @param method the method
      * @return the ExecutableType representing the method as part of usedMapper
      */
     public ExecutableType getMethodType(TypeElement usedMapper, ExecutableElement method) {
@@ -458,11 +458,12 @@ public class TypeFactory {
     }
 
     /**
-     * Converts any collection type, e.g. List<T> to Collection<T> and any map type, e.g. HashMap<K,V> to Map<K,V>.
+     * Converts any collection type, e.g. {@code List<T>} to {@code Collection<T>} and any map type, e.g.
+     * {@code HashMap<K,V>} to {@code Map<K,V>}.
      *
      * @param collectionOrMap any collection or map type
-     * @return the type representing Collection<T> or Map<K,V>, if the argument type is a subtype of Collection<T> or of
+     * @return the type representing {@code Collection<T>} or {@code Map<K,V>}, if the argument type is a subtype of
-     *         Map<K,V> respectively.
+     *         {@code Collection<T>} or of {@code Map<K,V>} respectively.
      */
     public Type asCollectionOrMap(Type collectionOrMap) {
         List<Type> originalParameters = collectionOrMap.getTypeParameters();

processor/src/main/java/org/mapstruct/ap/model/dependency/GraphAnalyzer.java

@@ -67,6 +67,9 @@ public class GraphAnalyzer {
      * Returns all the descendants of the given node, either direct or transitive ones.
      * <p>
      * <b>Note</b>:The list will only be complete if the graph contains no cycles.
+     *
+     * @param name the node name to get the descendants for
+     * @return the descendants
      */
     public Set<String> getAllDescendants(String name) {
         Node node = nodes.get( name );
@@ -140,6 +143,8 @@ public class GraphAnalyzer {
         /**
          * Builds the analyzer and triggers traversal of all nodes for detecting potential cycles and calculates the
          * full list of descendants of each node.
+         *
+         * @return the analyzer
          */
         public GraphAnalyzer build() {
             GraphAnalyzer graphAnalyzer = new GraphAnalyzer( nodes );

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

@@ -34,14 +34,14 @@ public class EnumMapping {
     }
 
     /**
-     * Returns the name of the constant in the source enum.
+     * @return the name of the constant in the source enum.
      */
     public String getSource() {
         return source;
     }
 
     /**
-     * Returns the name of the constant in the target enum.
+     * @return the name of the constant in the target enum.
      */
     public String getTarget() {
         return target;

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

@@ -322,6 +322,9 @@ public class Mapping {
 
     /**
      * Creates a copy of this mapping, which is adapted to the given method
+     *
+     * @param method the method to create the copy for
+     * @return the copy
      */
     public Mapping copyForInheritanceTo(SourceMethod method) {
         Mapping mapping = new Mapping(

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

@@ -115,12 +115,10 @@ public interface Method {
     List<Type> getThrownTypes();
 
     /**
-     * Returns the type of the result.
+     * Returns the type of the result. The result is defined as the type of the parameter designated with
+     * {@link org.mapstruct.MappingTarget}, or in absence the return type.
      *
-     * The result is defined as the type of the parameter designated with {@link org.mapstruct.MappingTarget},
+     * @return result type
-     * or in absence the return type.
-     *
-     * @return
      */
     Type getResultType();
 

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

@@ -33,8 +33,8 @@ import javax.lang.model.type.TypeVariable;
 import javax.lang.model.type.WildcardType;
 import javax.lang.model.util.SimpleTypeVisitor6;
 import javax.lang.model.util.Types;
-import org.mapstruct.ap.model.common.Parameter;
 
+import org.mapstruct.ap.model.common.Parameter;
 import org.mapstruct.ap.model.common.Type;
 import org.mapstruct.ap.model.common.TypeFactory;
 
@@ -376,9 +376,6 @@ public class MethodMatcher {
     /**
      * checks whether a type t is in bounds of the typeParameter tpe
      *
-     * @param t
-     * @param tpe
-     *
      * @return true if within bounds
      */
     private boolean isWithinBounds(TypeMirror t, TypeParameterElement tpe) {

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

@@ -292,6 +292,9 @@ public class SourceReference {
 
     /**
      * Creates a copy of this reference, which is adapted to the given method
+     *
+     * @param method the method to create the copy for
+     * @return the copy
      */
     public SourceReference copyForInheritanceTo(SourceMethod method) {
         List<Parameter> replacementParamCandidates = new ArrayList<Parameter>();

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

@@ -135,13 +135,11 @@ public abstract class BuiltInMethod implements Method {
     }
 
     /**
-     * the conversion context is used to format an auxiliary parameter in the method call
+     * the conversion context is used to format an auxiliary parameter in the method call with context specific
-     * with context specific information such as a date format.
+     * information such as a date format.
      *
-     * @param conversionContext
+     * @param conversionContext context
-     *
+     * @return null if no context parameter should be included "null" if there should be an explicit null call
-     * @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
      */
     public String getContextParameter(ConversionContext conversionContext) {
@@ -174,13 +172,12 @@ public abstract class BuiltInMethod implements Method {
     }
 
     /**
-     * Analyzes the Java Generic 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
-     * same goes for the returnType.
+     * goes for the returnType.
      *
      * @param parameter source
      * @param returnType target
-     *
+     * @return {@code true}, iff the the type variables match
-     * @return
      */
     public boolean doTypeVarsMatch(Type parameter, Type returnType) {
         return true;

processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java

@@ -20,6 +20,7 @@ package org.mapstruct.ap.model.source.selector;
 
 import java.util.ArrayList;
 import java.util.List;
+
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.Types;
 import javax.xml.bind.annotation.XmlElementDecl;
@@ -38,7 +39,7 @@ import org.mapstruct.ap.prism.XmlElementDeclPrism;
  * <li>Name matches</li>
  * </ol>
  * If there are name and scope matches, only those will be returned, otherwise the next in line (scope matches), etc. If
- * the given method is not annotated with {@code} XmlElementDecl} it will be considered as matching.
+ * the given method is not annotated with {@code XmlElementDecl} it will be considered as matching.
  *
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/prism/NullValueMappingStrategyPrism.java

@@ -19,7 +19,7 @@
 package org.mapstruct.ap.prism;
 
 /**
- * Prism for the enum {@link org.mapstruct.MapNullToDefaultStrategy}
+ * Prism for the enum {@link org.mapstruct.NullValueMappingStrategy}
  *
  * @author Sjaak Derksen
  */

processor/src/main/java/org/mapstruct/ap/processor/creation/MappingResolverImpl.java

@@ -23,7 +23,6 @@ import java.util.HashSet;
 import java.util.List;
 import java.util.Set;
 
-import org.mapstruct.ap.util.FormattingMessager;
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.Elements;
 import javax.lang.model.util.Types;
@@ -46,6 +45,7 @@ import org.mapstruct.ap.model.source.builtin.BuiltInMappingMethods;
 import org.mapstruct.ap.model.source.builtin.BuiltInMethod;
 import org.mapstruct.ap.model.source.selector.MethodSelectors;
 import org.mapstruct.ap.model.source.selector.SelectionCriteria;
+import org.mapstruct.ap.util.FormattingMessager;
 import org.mapstruct.ap.util.Message;
 import org.mapstruct.ap.util.Strings;
 
@@ -499,8 +499,6 @@ public class MappingResolverImpl implements MappingResolver {
          * implementation type) accepts the source type.</li>
          * </ul>
          *
-         * @param property The property mapping to check.
-         *
          * @return {@code true} if the specified property can be mapped, {@code false} otherwise.
          */
         private boolean isPropertyMappable(Type sourceType, Type targetType) {

processor/src/main/java/org/mapstruct/ap/util/Executables.java

@@ -114,8 +114,9 @@ public class Executables {
     }
 
     /**
-     * Returns the 'element name' to which an adder method applies. If. e.g. an adder method is named
+     * @param adderMethod the adder method
-     * {@code addChild(Child v)}, the element name would be 'Child'.
+     * @return the 'element name' to which an adder method applies. If. e.g. an adder method is named
+     *         {@code addChild(Child v)}, the element name would be 'Child'.
      */
     public static String getElementNameForAdder(ExecutableElement adderMethod) {
         if ( isAdderMethod( adderMethod ) ) {
@@ -255,7 +256,7 @@ public class Executables {
 
     /**
      * @param elementUtils the elementUtils
-     * @param methods the list of already collected methods of one type hierarchy (order is from sub-types to
+     * @param alreadyAdded the list of already collected methods of one type hierarchy (order is from sub-types to
      *            super-types)
      * @param executable the method to check
      * @param parentType the type for which elements are collected

processor/src/main/java/org/mapstruct/ap/util/Nouns.java

@@ -88,6 +88,9 @@ public class Nouns {
     /**
      * Converts given pluralized noun into the singular form. If no singular form could be determined, the given word
      * itself is returned.
+     *
+     * @param plural plural word
+     * @return singular form, if available
      */
     public static String singularize(String plural) {
         for ( ReplaceRule replaceRule : SINGULAR_RULES ) {

processor/src/main/java/org/mapstruct/ap/writer/Writable.java

@@ -39,7 +39,7 @@ public interface Writable {
          * Retrieves the object with the given type from this context.
          *
          * @param type The type of the object to retrieve from this context.
-         *
+         * @param <T> the type
          * @return The object with the given type from this context.
          */
         <T> T get(Class<T> type);
@@ -50,6 +50,7 @@ public interface Writable {
      *
      * @param context Provides additional data specific to the used implementation of the serialization mechanism.
      * @param writer The writer to write this element to. Must not be closed by implementations.
+     * @throws Exception in case of an error
      */
     void write(Context context, Writer writer) throws Exception;
 }