Some javadoc

Author: DenWav

hypo-types/build.gradle.kts

@@ -35,7 +35,6 @@ val typesExport = project(":types-export")
 tasks.test {
     dependsOn(typesExport.tasks.named("buildTypesExport"))
 
-//    systemProperty("hypo.interning.disabled", "true")
     val zipFile = typesExport.layout.buildDirectory.file("types-export/types-export.zip").get().asFile.absolutePath
     systemProperty("hypo.types.zip", zipFile)
 }

hypo-types/src/main/java/dev/denwav/hypo/types/HypoTypesUtil.java

@@ -22,6 +22,9 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * General utility class used by {@code hypo-types}.
+ */
 public final class HypoTypesUtil {
 
     private HypoTypesUtil() {}

hypo-types/src/main/java/dev/denwav/hypo/types/Intern.java

@@ -28,6 +28,22 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Interning base class which enables types classes to be interned, that is to say, prevent multiple copies of equal
+ * values to exist on the heap. This is useful for two primary reasons: first, all type classes are pure data classes,
+ * their identity is meaningless. Second, and more importantly, when analyzing large jar files with many classes many of
+ * the same type descriptors will be encountered over and over again, and it would be an inefficient use of memory to
+ * store separate copies for each type when they are identical. Common examples include core Java types just as
+ * {@code Ljava/lang/Object;} and {@code Ljava/lang/String;}, but this also applies to extremely common method
+ * descriptors and signatures, such as {@code ()V}, etc.
+ *
+ * <p>This is thread-safe, and utilizes a concurrent hashmap to enable lock-less handling of value instances.
+ *
+ * <p>The internal state of the internment can be checked via two static helper methods on this class,
+ * {@link #tryFind(Class, String)} and {@link #internmentSize(Class)}.
+ *
+ * @param <T> The type of {@code this}. Any other type will result in a {@link ClassCastException} at runtime.
+ */
 public abstract class Intern<T extends Intern<T>> implements TypeRepresentable {
 
     private static final IdentityHashMap<ConcurrentHashMap<String, WeakReference<?>>, AtomicLong> interns = new IdentityHashMap<>();
@@ -45,7 +61,6 @@ public abstract class Intern<T extends Intern<T>> implements TypeRepresentable {
                     final var map = entry.getKey();
                     final AtomicLong lastSize = entry.getValue();
                     if (Math.abs(map.mappingCount() - lastSize.get()) < 10_000) {
-                        System.out.println("SKIPPED");
                         continue;
                     }
                     map.values().removeIf(r -> r.get() == null);
@@ -82,6 +97,21 @@ protected ConcurrentHashMap<String, WeakReference<?>> computeValue(final @NotNul
 
     private static final boolean interningDisabled = Boolean.getBoolean("hypo.interning.disabled");
 
+    /**
+     * Return a class which is guaranteed to have the same value as {@code this}, but may be a different instance. An
+     * interned value satisfies the following rule:
+     * <ul>
+     *     <li>{@code obj.intern().equals(obj)}</li>
+     *     <li>{@code obj.equals(obj.intern())}</li>
+     * </ul>
+     *
+     * If two objects exist, {@code o1} and {@code o2}, where {@code o1.equals(o2)}, then the following will also be true:
+     * <ul>
+     *     <li>{@code o1.intern() == o2.intern()}</li>
+     * </ul>
+     *
+     * @return Return the interned version of this object.
+     */
     public final T intern() {
         if (interningDisabled) {
             return HypoTypesUtil.cast(this);
@@ -97,15 +127,31 @@ public final T intern() {
                 return res;
             }
 
+            // Edge case, handle scenarios where the reference returned from `map` was garbage collected but was still
+            // present in the map. When that occurs, we replace the entry with our new valid entry, and return it,
+            // guaranteeing this method will never return `null`.
+            //
+            // Note that this will not result in "leaks" of this value (even though such leaks would be harmless) as
+            // the above case can only happen when the stored value was already considered weakly reachable - that is to
+            // say it was already being GCed and no longer exists on the heap.
             map.put(key, ref);
             return t;
         } finally {
             Reference.reachabilityFence(t);
         }
     }
 
-    @SuppressWarnings("TypeParameterUnusedInFormals")
-    public static <T> @Nullable T tryFind(final @NotNull Class<?> c, final @NotNull String key) {
+    /**
+     * Attempt to find the given object of the type {@code c} in the internment map by its string value, {@code key}.
+     * The key for interned objects is always {@link TypeRepresentable#asInternal()}. Returns {@code null} if the given
+     * key does not exist in the map.
+     *
+     * @param c The {@link Class} object of the type to check.
+     * @param key The {@link TypeRepresentable#asInternal()} key of the value to check.
+     * @return The currently interned value for the given key, if it exists, otherwise {@code null}.
+     * @param <T> The type of the interned value.
+     */
+    public static <T> @Nullable T tryFind(final @NotNull Class<T> c, final @NotNull String key) {
         final WeakReference<?> ref = internment.get(c).get(key);
         if (ref == null) {
             return null;
@@ -121,6 +167,12 @@ public final T intern() {
         }
     }
 
+    /**
+     * Get the current estimated size of the internment map for the given class type.
+     *
+     * @param c The class to check.
+     * @return The current estimated size of the internment map.
+     */
     public static long internmentSize(final @NotNull Class<?> c) {
         return internment.get(c).mappingCount();
     }

hypo-types/src/main/java/dev/denwav/hypo/types/PrimitiveType.java

@@ -25,14 +25,94 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * Primitive types in Java, implementation for both {@link TypeDescriptor} and
+ * {@link TypeSignature}.
+ *
+ * <p>There are 8 total primitive types in the JVM:
+ * <table>
+ *     <caption>
+ *         Java Primitive Types
+ *     </caption>
+ *     <tr>
+ *         <th>Name</th>
+ *         <th>Wrapper Type</th>
+ *         <th>Internal Name</th>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code char}</td>
+ *         <td>{@link java.lang.Character java/lang/Character}</td>
+ *         <td>{@code C}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code byte}</td>
+ *         <td>{@link java.lang.Byte java/lang/Byte}</td>
+ *         <td>{@code B}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code short}</td>
+ *         <td>{@link java.lang.Short java/lang/Short}</td>
+ *         <td>{@code S}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code int}</td>
+ *         <td>{@link java.lang.Integer java/lang/Integer}</td>
+ *         <td>{@code I}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code long}</td>
+ *         <td>{@link java.lang.Long java/lang/Long}</td>
+ *         <td>{@code J}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code float}</td>
+ *         <td>{@link java.lang.Float java/lang/Float}</td>
+ *         <td>{@code F}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code double}</td>
+ *         <td>{@link java.lang.Double java/lang/Double}</td>
+ *         <td>{@code D}</td>
+ *     </tr>
+ *     <tr>
+ *         <td>{@code boolean}</td>
+ *         <td>{@link java.lang.Boolean java/lang/Boolean}</td>
+ *         <td>{@code Z}</td>
+ *     </tr>
+ * </table>
+ */
 public enum PrimitiveType implements TypeDescriptor, TypeSignature {
+    /**
+     * {@code char}
+     */
     CHAR("char", 'C', "java/lang/Character"),
+    /**
+     * {@code byte}
+     */
     BYTE("byte", 'B', "java/lang/Byte"),
+    /**
+     * {@code short}
+     */
     SHORT("short", 'S', "java/lang/Short"),
+    /**
+     * {@code int}
+     */
     INT("int", 'I', "java/lang/Integer"),
+    /**
+     * {@code long}
+     */
     LONG("long", 'J', "java/lang/Long"),
+    /**
+     * {@code float}
+     */
     FLOAT("float", 'F', "java/lang/Float"),
+    /**
+     * {@code double}
+     */
     DOUBLE("double", 'D', "java/lang/Double"),
+    /**
+     * {@code boolean}
+     */
     BOOLEAN("boolean", 'Z', "java/lang/Boolean"),
     ;
 

hypo-types/src/main/java/dev/denwav/hypo/types/TypeBindable.java

@@ -20,6 +20,25 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * A type which can be bound to a {@link dev.denwav.hypo.types.sig.param.TypeParameter TypeParameter}, or may contain
+ * nested objects which themselves may satisfy that scenario. The intended pattern is for objects which fall in the
+ * latter category to simply recursively call this method on all matching nested values.
+ *
+ * <p>Type variable binding only applies to {@link dev.denwav.hypo.types.sig.TypeSignature TypeSignature}-based types.
+ */
 public interface TypeBindable {
+
+    /**
+     * Return a new instance of {@code this} (possibly as a different type) where all unbound type variables have been
+     * bound to their associated type parameters using the provided {@code binder}. All valid type definitions must be
+     * able to be bound, so failure to find a valid type parameter definition for an unbound type variable will result
+     * in an {@link IllegalStateException}.
+     *
+     * @param binder The {@link TypeVariableBinder} to bind with.
+     * @return A new instance of {@code this} (possibly as a different type) where all unbound type variables have been
+     *         bound to their associated type parameters
+     * @throws IllegalStateException If a type variable could not be bound to an appropriate type parameter.
+     */
     @NotNull TypeBindable bind(final @NotNull TypeVariableBinder binder);
 }

hypo-types/src/main/java/dev/denwav/hypo/types/TypeRepresentable.java

@@ -20,6 +20,24 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * A value which represents a type in Java. "types" include 5 major categories:
+ * <ul>
+ *     <li>{@link dev.denwav.hypo.types.desc.TypeDescriptor TypeDescriptor}</li>
+ *     <li>{@link dev.denwav.hypo.types.desc.MethodDescriptor MethodDescriptor}</li>
+ *     <li>{@link dev.denwav.hypo.types.sig.TypeSignature TypeSignature}</li>
+ *     <li>{@link dev.denwav.hypo.types.sig.MethodSignature MethodSignature}</li>
+ *     <li>{@link dev.denwav.hypo.types.sig.ClassSignature ClassSignature}</li>
+ * </ul>
+ *
+ * <p>All types can be represented in two different ways, {@link #asReadable()}, and {@link #asInternal()}. Generally
+ * "readable" will be in source code format, as would appear in a Java source file. Internal format matches exactly what
+ * is present in compiled Java bytecode for the given type.
+ *
+ * <p>Implementations of this interface should have their {@link Object#toString() toString()} method defer to
+ * {@link #asReadable()} to assist with debugging. {@link #asInternal()} should be used for serialization, as it matches
+ * 1:1 with corresponding {@code parse()} methods for each type.
+ */
 public interface TypeRepresentable {
 
     /**

hypo-types/src/main/java/dev/denwav/hypo/types/TypeVariableBinder.java

@@ -22,14 +22,37 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * An object which provides bindings for {@link dev.denwav.hypo.types.sig.param.TypeVariable TypeVariables}. This is
+ * generally as simple as finding the instance of {@link TypeParameter} which correspond with the given type variable
+ * name.
+ *
+ * <p>Typical usage of this class is by passing it into the {@link TypeBindable#bind(TypeVariableBinder)} method. A
+ * convenience method is also provided, {@link #bind(TypeBindable)}, which inverts that mechanism. This can make it
+ * simpler when dealing with possibly {@code null} values.
+ */
 public interface TypeVariableBinder {
 
+    /**
+     * A convenience method which inverts the typical order of the {@link TypeBindable#bind(TypeVariableBinder)} method
+     * call. This can be used to safely call the bind method on possibly {@code null} objects.
+     *
+     * @param bindable The bindable object to pass this object into.
+     * @return The result of calling {@link TypeBindable#bind(TypeVariableBinder)} if {@code bindable} is not null,
+     * @param <T> The type of the bindable.
+     */
     default <T extends TypeBindable> @Nullable T bind(final @Nullable T bindable) {
         if (bindable == null) {
             return null;
         }
         return HypoTypesUtil.cast(bindable.bind(this));
     }
 
+    /**
+     * Return the associated {@link TypeParameter} for the given variable name.
+     *
+     * @param name The variable name.
+     * @return The associated {@link TypeParameter}, or {@code null} if not found.
+     */
     @Nullable TypeParameter bindingFor(final @NotNull String name);
 }

hypo-types/src/main/java/dev/denwav/hypo/types/VoidType.java

@@ -22,7 +22,18 @@
 import dev.denwav.hypo.types.sig.TypeSignature;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * The {@code void} type in Java. This class is an implementation for both {@link TypeDescriptor} and
+ * {@link TypeSignature}. {@code void} is only void when used as the return type in a method descriptor or signature, it
+ * cannot be used as the type for any field or variable.
+ *
+ * <p>The wrapper type for {@code void} is {@link java.lang.Void java/lang/Void}. The internal name for {@code void} is
+ * {@code V}.
+ */
 public enum VoidType implements TypeDescriptor, TypeSignature {
+    /**
+     * The singleton instance of this type object.
+     */
     INSTANCE,
     ;
 

hypo-types/src/main/java/dev/denwav/hypo/types/desc/ArrayTypeDescriptor.java

@@ -26,12 +26,27 @@
 import java.util.concurrent.ConcurrentHashMap;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * A {@link TypeDescriptor} representing an array type. Array types consist of a {@link #getDimension() dimension} and a
+ * {@link #getBaseType() base type}, which can be either a {@link dev.denwav.hypo.types.PrimitiveType PrimitiveType} or
+ * a {@link ClassTypeDescriptor}.
+ *
+ * <p>Array type descriptors have the internal format of {@code [<base_type>}. The leading {@code [} is repeated to
+ * denote the dimensionality of the array, so a 3-dimension array type would start with {@code [[[}.
+ */
 public final class ArrayTypeDescriptor extends Intern<ArrayTypeDescriptor> implements TypeDescriptor {
 
     private final int dimension;
     private final @NotNull TypeDescriptor baseType;
 
-    public static @NotNull ArrayTypeDescriptor of(int dimension, @NotNull TypeDescriptor baseType) {
+    /**
+     * Create a {@link ArrayTypeDescriptor} instance.
+     *
+     * @param dimension The dimension for the new type.
+     * @param baseType The base type for the new type.
+     * @return The new {@link ArrayTypeDescriptor}.
+     */
+    public static @NotNull ArrayTypeDescriptor of(final int dimension, final @NotNull TypeDescriptor baseType) {
         return new ArrayTypeDescriptor(dimension, baseType).intern();
     }
 
@@ -68,10 +83,18 @@ public void asInternal(final @NotNull StringBuilder sb) {
         return ArrayTypeSignature.of(this.dimension, this.baseType.asSignature());
     }
 
+    /**
+     * Get the dimension of this array type.
+     * @return The dimension of this array type.
+     */
     public int getDimension() {
         return this.dimension;
     }
 
+    /**
+     * Get the base type of this array type.
+     * @return The base type of this array type.
+     */
     public @NotNull TypeDescriptor getBaseType() {
         return this.baseType;
     }