Cleanup Types interface / add forName

jakartaee · Aug 11, 2021 · 6639f58 · 6639f58
1 parent c43240d
commit 6639f58
Showing 1 changed file with 61 additions and 4 deletions.
diff --git a/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Types.java b/api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Types.java
@@ -1,13 +1,30 @@
 package jakarta.enterprise.inject.build.compatible.spi;
 
 import jakarta.enterprise.lang.model.declarations.ClassInfo;
+import jakarta.enterprise.lang.model.types.ArrayType;
 import jakarta.enterprise.lang.model.types.PrimitiveType;
 import jakarta.enterprise.lang.model.types.Type;
+import jakarta.enterprise.lang.model.types.VoidType;
 
 // TODO move to jakarta.enterprise.lang.model.types? probably not, it doesn't model any part of Java language
+
+/**
+ * A factory interface for creating instances of {@link Type}.
+ */
 public interface Types {
+
+    /**
+     * Returns the type for the given canonical name as defined by {@link Class#getCanonicalName()} or {@code null}
+     * if the type is not present on the classpath or cannot be resolved.
+     *
+     * @param name The name of the type, never {@code null}
+     * @return {@link Type} object representing the type or {@code null}
+     */
+    Type forName(String name);
+
     /**
-     * Returns a type from given class literal.
+     * Returns a type from the given class literal.
+     * 
      * For example:
      * <ul>
      * <li>{@code of(void.class)}: same as {@code ofVoid()}</li>
@@ -22,18 +39,58 @@ public interface Types {
      */
     Type of(Class<?> clazz);
 
-    Type ofVoid();
+    /**
+     * @return An instance of {@link jakarta.enterprise.lang.model.types.VoidType}, never {@code null}
+     */
+    VoidType ofVoid();
 
-    Type ofPrimitive(PrimitiveType.PrimitiveKind kind);
+    /**
+     * Returns a {@link PrimitiveType} for the given {@link jakarta.enterprise.lang.model.types.PrimitiveType.PrimitiveKind kind}.
+     * @param kind The kind, never {@code null}
+     * @return The {@link PrimitiveType}, never {@code null}
+     */
+    PrimitiveType ofPrimitive(PrimitiveType.PrimitiveKind kind);
 
+    /**
+     * Returns a {@link Type} for the given {@link ClassInfo clazz}.
+     * @param clazz The {@link ClassInfo}, never {@code null}
+     * @return A {@link Type}, never {@code null}
+     */
     Type ofClass(ClassInfo clazz);
 
-    Type ofArray(Type componentType, int dimensions);
+    /**
+     * Returns an {@link ArrayType} for the given {@link Type componentType} and dimensions
+     * @param componentType The component {@link Type}
+     * @param dimensions The dimensions
+     * @return The {@link ArrayType}, never {@code null}
+     */
+    ArrayType ofArray(Type componentType, int dimensions);
 
+    /**
+     * Returns a parameterized {@link Type} for the given type and type arguments.
+     *
+     * @param parameterizedType The type to parametrize, never {@code null}
+     * @param typeArguments Zero or more type arguments
+     * @return A potentially parameterized type, never {@code null}
+     */
     Type parameterized(Class<?> parameterizedType, Class<?>... typeArguments);
 
+    /**
+     * Returns a parameterized {@link Type} for the given type and type arguments.
+     *
+     * @param parameterizedType The type to parametrize, never {@code null}
+     * @param typeArguments Zero or more type arguments
+     * @return A potentially parameterized type, never {@code null}
+     */
     Type parameterized(Class<?> parameterizedType, Type... typeArguments);
 
+    /**
+     * Returns a parameterized {@link Type} for the given type and type arguments.
+     *
+     * @param parameterizedType The type to parametrize, never {@code null}
+     * @param typeArguments Zero or more type arguments
+     * @return A potentially parameterized type, never {@code null}
+     */
     Type parameterized(Type parameterizedType, Type... typeArguments);
 
     /**