From 228c1f9f1be3791327f7b4d61bb9fbe564446082 Mon Sep 17 00:00:00 2001
From: Filip Hrisafov <filip.hrisafov@gmail.com>
Date: Mon, 19 Dec 2016 18:51:04 +0100
Subject: [PATCH] #557 add Javadoc for the Accessor

---
 .../ap/internal/model/common/TypeFactory.java | 18 +++++----------
 .../ap/internal/util/accessor/Accessor.java   | 22 +++++++++++++++++++
 2 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/processor/src/main/java/org/mapstruct/ap/internal/model/common/TypeFactory.java b/processor/src/main/java/org/mapstruct/ap/internal/model/common/TypeFactory.java
index 83b2dd617..d53f2c3cf 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/model/common/TypeFactory.java
+++ b/processor/src/main/java/org/mapstruct/ap/internal/model/common/TypeFactory.java
@@ -261,11 +261,13 @@ 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.
      *
+     * <b>IMPORTANT:</b> This should only be used from the Processors, as they are operating over executable elements.
+     * The internals should not be using this function and should not be using the {@link ExecutableElement} directly.
+     *
      * @param includingType the type on which's scope the method type shall be evaluated
      * @param method the method
      * @return the ExecutableType representing the method as part of usedMapper
      */
-    @Deprecated
     public ExecutableType getMethodType(DeclaredType includingType, ExecutableElement method) {
         TypeMirror asMemberOf = typeUtils.asMemberOf( includingType, method );
         return (ExecutableType) asMemberOf;
@@ -301,10 +303,11 @@ public class TypeFactory {
 
     public List<Parameter> getParameters(DeclaredType includingType, Accessor accessor) {
         ExecutableElement method = accessor.getExecutable();
-        if ( method == null ) {
+        TypeMirror methodType = getMethodType( includingType, accessor.getElement() );
+        if ( method == null || methodType.getKind() != TypeKind.EXECUTABLE ) {
             return new ArrayList<Parameter>();
         }
-        return getParameters( getMethodType( includingType, method ), method );
+        return getParameters( (ExecutableType) methodType, method );
     }
 
     public List<Parameter> getParameters(ExecutableType methodType, ExecutableElement method) {
@@ -330,11 +333,6 @@ public class TypeFactory {
         return result;
     }
 
-    @Deprecated
-    public Type getReturnType(DeclaredType includingType, ExecutableElement method) {
-        return getReturnType( getMethodType( includingType, method ) );
-    }
-
     public Type getReturnType(DeclaredType includingType, Accessor accessor) {
         Type type;
         TypeMirror accessorType = getMethodType( includingType, accessor.getElement() );
@@ -356,10 +354,6 @@ public class TypeFactory {
         return getType( method.getReturnType() );
     }
 
-    public List<Type> getThrownTypes(DeclaredType includingType, ExecutableElement method) {
-        return getThrownTypes( getMethodType( includingType, method ) );
-    }
-
     public List<Type> getThrownTypes(ExecutableType method) {
         List<Type> thrownTypes = new ArrayList<Type>();
         for ( TypeMirror exceptionType : method.getThrownTypes() ) {
diff --git a/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java b/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java
index 0fa3dec8c..aaa4e49d9 100644
--- a/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java
+++ b/processor/src/main/java/org/mapstruct/ap/internal/util/accessor/Accessor.java
@@ -26,17 +26,39 @@ import javax.lang.model.element.Name;
 import javax.lang.model.type.TypeMirror;
 
 /**
+ * This represents an Accessor that can be used for writing/reading a property to/from a bean.
+ *
  * @author Filip Hrisafov
  */
 public interface Accessor {
 
+    /**
+     * This returns the type that this accessor gives as a return.
+     *
+     * e.g. The {@link ExecutableElement#getReturnType()} if this is a method accessor,
+     * or {@link javax.lang.model.element.VariableElement#asType()} for field accessors.
+     *
+     * @return the type that the accessor gives as a return
+     */
     TypeMirror getAccessedType();
 
+    /**
+     * @return the simple name of the accessor
+     */
     Name getSimpleName();
 
+    /**
+     * @return the set of modifiers that the accessor has
+     */
     Set<Modifier> getModifiers();
 
+    /**
+     * @return the {@link ExecutableElement}, or {@code null} if the accessor does not have one
+     */
     ExecutableElement getExecutable();
 
+    /**
+     * @return the underlying {@link Element}
+     */
     Element getElement();
 }