From 5e80b17c98f9d1bf910bd1f054b936af99286adc Mon Sep 17 00:00:00 2001
From: Peter Gafert <peter.gafert@tngtech.com>
Date: Wed, 25 Jan 2023 11:11:33 +0700
Subject: [PATCH] fix outdated Javadoc on `JavaField.getType()`

The comment on `JavaField.getType()` was a leftover from a previous time before generics support was fully implemented. Meanwhile, the described "possible" future has already become reality. I've noticed that the Javadoc on `JavaType` and `HasType` was a little sparse, so I tried to extend that instead.

Signed-off-by: Peter Gafert <peter.gafert@tngtech.com>
---
 .../tngtech/archunit/core/domain/JavaField.java |  4 ----
 .../tngtech/archunit/core/domain/JavaType.java  | 17 +++++++++++++++++
 .../core/domain/properties/HasType.java         | 13 +++++++++++++
 3 files changed, 30 insertions(+), 4 deletions(-)

diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaField.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaField.java
index 6c36ec78cb..335f0e93b5 100644
--- a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaField.java
+++ b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaField.java
@@ -50,10 +50,6 @@ public String getFullName() {
         return getOwner().getName() + "." + getName();
     }
 
-    /**
-     * Note: This is still work in progress and thus does not support generic types at the moment.
-     *       In the future the result can possibly also be a {@link JavaParameterizedType} or {@link JavaTypeVariable}
-     */
     @Override
     @PublicAPI(usage = ACCESS)
     public JavaType getType() {
diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java
index b1fdfd983a..9bd0c68dc9 100644
--- a/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java
+++ b/archunit/src/main/java/com/tngtech/archunit/core/domain/JavaType.java
@@ -15,12 +15,29 @@
  */
 package com.tngtech.archunit.core.domain;
 
+import java.lang.reflect.Type;
+
 import com.tngtech.archunit.PublicAPI;
 import com.tngtech.archunit.base.ChainableFunction;
 import com.tngtech.archunit.core.domain.properties.HasName;
 
 import static com.tngtech.archunit.PublicAPI.Usage.ACCESS;
 
+/**
+ * Represents a general Java type. This can e.g. be a class like {@code java.lang.String}, a parameterized type
+ * like {@code List<String>} or a type variable like {@code T}.<br>
+ * Besides having a {@link HasName#getName() name} and offering the possibility to being converted to an
+ * {@link #toErasure() erasure} (which is then always {@link JavaClass a raw class object}) {@link JavaType} doesn't offer
+ * an extensive API. Instead, users can check a {@link JavaType} for being an instance of a concrete subtype
+ * (like {@link JavaTypeVariable}) and then cast it to the respective subclass
+ * (same as with {@link Type} of the Java Reflection API).
+ *
+ * @see JavaClass
+ * @see JavaParameterizedType
+ * @see JavaTypeVariable
+ * @see JavaWildcardType
+ * @see JavaGenericArrayType
+ */
 @PublicAPI(usage = ACCESS)
 public interface JavaType extends HasName {
     /**
diff --git a/archunit/src/main/java/com/tngtech/archunit/core/domain/properties/HasType.java b/archunit/src/main/java/com/tngtech/archunit/core/domain/properties/HasType.java
index 4780ae49ab..beacbb4690 100644
--- a/archunit/src/main/java/com/tngtech/archunit/core/domain/properties/HasType.java
+++ b/archunit/src/main/java/com/tngtech/archunit/core/domain/properties/HasType.java
@@ -19,6 +19,7 @@
 import com.tngtech.archunit.base.ChainableFunction;
 import com.tngtech.archunit.base.DescribedPredicate;
 import com.tngtech.archunit.core.domain.JavaClass;
+import com.tngtech.archunit.core.domain.JavaParameterizedType;
 import com.tngtech.archunit.core.domain.JavaType;
 
 import static com.tngtech.archunit.PublicAPI.Usage.ACCESS;
@@ -29,9 +30,21 @@
 @PublicAPI(usage = ACCESS)
 public interface HasType {
 
+    /**
+     * @return The (possibly generic) {@link JavaType} of this object. Refer to the documentation of {@link JavaType}
+     *         for further information.
+     * @see #getRawType()
+     */
     @PublicAPI(usage = ACCESS)
     JavaType getType();
 
+    /**
+     * @return The raw type of this object. This is effectively the same as calling
+     *         {@link #getType()}.{@link JavaType#toErasure() toErasure()}. E.g. given a {@link JavaParameterizedType}
+     *         {@code java.util.List<String>} the raw type (i.e. type erasure) would be the
+     *         {@link JavaClass} {@code java.util.List}.
+     * @see #getType()
+     */
     @PublicAPI(usage = ACCESS)
     JavaClass getRawType();