From e31296d7f9997afb2c5f1b7fefd174e4be8cc96f Mon Sep 17 00:00:00 2001
From: Andreas Gudian <agudian@apache.org>
Date: Thu, 14 May 2015 23:08:29 +0200
Subject: [PATCH] #494 Fix javadoc errors popping up during the build

---
 .../org/mapstruct/InheritConfiguration.java   |  4 +--
 core/src/main/java/org/mapstruct/Mapping.java |  1 -
 .../AbstractJodaTypeToStringConversion.java   |  4 +--
 .../mapstruct/ap/model/BeanMappingMethod.java |  2 --
 .../org/mapstruct/ap/model/MappingMethod.java |  9 ++++---
 .../mapstruct/ap/model/PropertyMapping.java   |  2 +-
 .../ap/model/assignment/Assignment.java       | 17 ++++++------
 .../org/mapstruct/ap/model/common/Type.java   | 26 +++++++++----------
 .../ap/model/common/TypeFactory.java          | 11 ++++----
 .../ap/model/dependency/GraphAnalyzer.java    |  5 ++++
 .../ap/model/source/EnumMapping.java          |  4 +--
 .../mapstruct/ap/model/source/Mapping.java    |  3 +++
 .../org/mapstruct/ap/model/source/Method.java |  8 +++---
 .../ap/model/source/MethodMatcher.java        |  5 +---
 .../ap/model/source/SourceReference.java      |  3 +++
 .../model/source/builtin/BuiltInMethod.java   | 17 +++++-------
 .../selector/XmlElementDeclSelector.java      |  3 ++-
 .../prism/NullValueMappingStrategyPrism.java  |  2 +-
 .../creation/MappingResolverImpl.java         |  4 +--
 .../org/mapstruct/ap/util/Executables.java    |  7 ++---
 .../java/org/mapstruct/ap/util/Nouns.java     |  3 +++
 .../org/mapstruct/ap/writer/Writable.java     |  3 ++-
 22 files changed, 75 insertions(+), 68 deletions(-)

diff --git a/core-common/src/main/java/org/mapstruct/InheritConfiguration.java b/core-common/src/main/java/org/mapstruct/InheritConfiguration.java
index b39ab60ea..69f455c00 100644
--- a/core-common/src/main/java/org/mapstruct/InheritConfiguration.java
+++ b/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
diff --git a/core/src/main/java/org/mapstruct/Mapping.java b/core/src/main/java/org/mapstruct/Mapping.java
index 5f7539c69..e9f2eface 100644
--- a/core/src/main/java/org/mapstruct/Mapping.java
+++ b/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(
diff --git a/processor/src/main/java/org/mapstruct/ap/conversion/AbstractJodaTypeToStringConversion.java b/processor/src/main/java/org/mapstruct/ap/conversion/AbstractJodaTypeToStringConversion.java
index 541060705..f2347a5d0 100755
--- a/processor/src/main/java/org/mapstruct/ap/conversion/AbstractJodaTypeToStringConversion.java
+++ b/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();
 }
diff --git a/processor/src/main/java/org/mapstruct/ap/model/BeanMappingMethod.java b/processor/src/main/java/org/mapstruct/ap/model/BeanMappingMethod.java
index 0ce5e1275..87c33fd76 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/BeanMappingMethod.java
+++ b/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() {
diff --git a/processor/src/main/java/org/mapstruct/ap/model/MappingMethod.java b/processor/src/main/java/org/mapstruct/ap/model/MappingMethod.java
index 2e01439f8..a3ab0320e 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/MappingMethod.java
+++ b/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.
-     * for property mappings). It is supposed to be initialized with at least the parameter names.
+     * constructor to be overloaded when local variable names are required prior to calling this constructor. (e.g. for
+     * property mappings). It is supposed to be initialized with at least the parameter names.
      *
-     * @param method
-     * @param existingVariableNames
+     * @param method method
+     * @param existingVariableNames existingVariableNames
      */
     protected MappingMethod(Method method, Collection<String> existingVariableNames ) {
         this.name = method.getName();
diff --git a/processor/src/main/java/org/mapstruct/ap/model/PropertyMapping.java b/processor/src/main/java/org/mapstruct/ap/model/PropertyMapping.java
index 23ecc7d81..cbda3550b 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/PropertyMapping.java
+++ b/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;
diff --git a/processor/src/main/java/org/mapstruct/ap/model/assignment/Assignment.java b/processor/src/main/java/org/mapstruct/ap/model/assignment/Assignment.java
index 00f43d2eb..a22fa0b0d 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/assignment/Assignment.java
+++ b/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.:
-      * <ul>
-      * <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>
-      * </ul>
-      *
-      * @param assignment
-      */
+     * An assignment in itself can wrap another assignment. E.g.:
+     * <ul>
+     * <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>
+     * </ul>
+     *
+     * @param assignment the assignment to set
+     */
      void setAssignment( Assignment assignment );
 
      /**
diff --git a/processor/src/main/java/org/mapstruct/ap/model/common/Type.java b/processor/src/main/java/org/mapstruct/ap/model/common/Type.java
index 6fdd4f083..31074d036 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/common/Type.java
+++ b/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.
-     *
-     * These accessors include:
-     *
+     * getPropertyWriteAccessors returns a map of the write accessors according to the CollectionMappingStrategy. These
+     * accessors include:
      * <ul>
-     *  <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>setters, the obvious candidate :-), {@link #getSetters() }</li>
+     * <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
-     * from FTL.
+     * @return A valid Java expression most suitable for representing null - useful for dealing with primitives from
+     *         FTL.
      */
     public String getNull() {
         if ( !isPrimitive() || isArrayType() ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/model/common/TypeFactory.java b/processor/src/main/java/org/mapstruct/ap/model/common/TypeFactory.java
index 8e9f69add..7b137c75e 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/common/TypeFactory.java
+++ b/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 method
+     * @param usedMapper the type declaring the 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
-     *         Map<K,V> respectively.
+     * @return the type representing {@code Collection<T>} or {@code Map<K,V>}, if the argument type is a subtype of
+     *         {@code Collection<T>} or of {@code Map<K,V>} respectively.
      */
     public Type asCollectionOrMap(Type collectionOrMap) {
         List<Type> originalParameters = collectionOrMap.getTypeParameters();
diff --git a/processor/src/main/java/org/mapstruct/ap/model/dependency/GraphAnalyzer.java b/processor/src/main/java/org/mapstruct/ap/model/dependency/GraphAnalyzer.java
index 2b5fe4652..24f7bdd5b 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/dependency/GraphAnalyzer.java
+++ b/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 );
diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/EnumMapping.java b/processor/src/main/java/org/mapstruct/ap/model/source/EnumMapping.java
index 91c50c3a1..31c8ee5b5 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/source/EnumMapping.java
+++ b/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;
diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/Mapping.java b/processor/src/main/java/org/mapstruct/ap/model/source/Mapping.java
index 694a7d66d..b6cfbe2af 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/source/Mapping.java
+++ b/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(
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 0fdd84a50..0dd7b3135 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
@@ -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},
-     * or in absence the return type.
-     *
-     * @return
+     * @return result type
      */
     Type getResultType();
 
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 ca3c25cf7..a1f65b108 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
@@ -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) {
diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/SourceReference.java b/processor/src/main/java/org/mapstruct/ap/model/source/SourceReference.java
index db163524b..c65bb3e1d 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/source/SourceReference.java
+++ b/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>();
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 fa70e5f1c..4086b0545 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
@@ -135,13 +135,11 @@ public abstract class BuiltInMethod implements Method {
     }
 
     /**
-     * the conversion context is used to format an auxiliary parameter in the method call
-     * with context specific information such as a date format.
+     * the conversion context is used to format an auxiliary parameter in the method call 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
+     * @param conversionContext context
+     * @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
-     * same goes for the returnType.
+     * 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
      * @param returnType target
-     *
-     * @return
+     * @return {@code true}, iff the the type variables match
      */
     public boolean doTypeVarsMatch(Type parameter, Type returnType) {
         return true;
diff --git a/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java b/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java
index d82e9c3e5..e84faa8b9 100644
--- a/processor/src/main/java/org/mapstruct/ap/model/source/selector/XmlElementDeclSelector.java
+++ b/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
  */
diff --git a/processor/src/main/java/org/mapstruct/ap/prism/NullValueMappingStrategyPrism.java b/processor/src/main/java/org/mapstruct/ap/prism/NullValueMappingStrategyPrism.java
index 4962fda89..897075cac 100644
--- a/processor/src/main/java/org/mapstruct/ap/prism/NullValueMappingStrategyPrism.java
+++ b/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
  */
diff --git a/processor/src/main/java/org/mapstruct/ap/processor/creation/MappingResolverImpl.java b/processor/src/main/java/org/mapstruct/ap/processor/creation/MappingResolverImpl.java
index 29da3e555..01ac2bd5f 100755
--- a/processor/src/main/java/org/mapstruct/ap/processor/creation/MappingResolverImpl.java
+++ b/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) {
diff --git a/processor/src/main/java/org/mapstruct/ap/util/Executables.java b/processor/src/main/java/org/mapstruct/ap/util/Executables.java
index dc410800f..0b6b91a4e 100644
--- a/processor/src/main/java/org/mapstruct/ap/util/Executables.java
+++ b/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
-     * {@code addChild(Child v)}, the element name would be 'Child'.
+     * @param adderMethod the adder method
+     * @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
diff --git a/processor/src/main/java/org/mapstruct/ap/util/Nouns.java b/processor/src/main/java/org/mapstruct/ap/util/Nouns.java
index a91ed1543..7fb737246 100644
--- a/processor/src/main/java/org/mapstruct/ap/util/Nouns.java
+++ b/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 ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/writer/Writable.java b/processor/src/main/java/org/mapstruct/ap/writer/Writable.java
index cb22e8a6e..3c47c2a01 100644
--- a/processor/src/main/java/org/mapstruct/ap/writer/Writable.java
+++ b/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;
 }