WIP: Add jDoc comments to public API

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/FunctionType.java

@@ -40,5 +40,4 @@ public interface FunctionType extends AnnotatableType {
     Type getRestType();
 
     Parameter[] getParameters();
-
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Atom.java

@@ -21,9 +21,15 @@
 /**
  * Represent the BDD atom.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public sealed interface Atom permits RecAtom, TypeAtom {
 
+    /**
+     * Get the index of the atom. For {@code TypeAtoms} this is a unique index within the {@code Env}. Each
+     * {@code RecAtom} that points to the same {@code TypeAtom} will have the same index.
+     *
+     * @return index of the atom
+     */
     int index();
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/AtomicType.java

@@ -26,7 +26,7 @@
 /**
  * Marker type representing AtomicType.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public sealed interface AtomicType permits CellAtomicType, FunctionAtomicType, ListAtomicType, MappingAtomicType {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BasicTypeCode.java

@@ -21,7 +21,7 @@
 /**
  * Represent bit field that indicate which basic type a semType belongs to.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class BasicTypeCode {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Bdd.java

@@ -23,10 +23,12 @@
 import static io.ballerina.runtime.api.types.semtype.Conjunction.and;
 
 /**
- * Represent BDD node. Subtypes that uses BDDs to represent subtypes such as list, mapping and cell should implement
- * their own {@code SubType} implementation that wraps an implementation of this class.
+ * Represent BDD node. Subtypes that uses BDDs to represent subtypes such as
+ * list, mapping and cell should implement
+ * their own {@code SubType} implementation that wraps an implementation of this
+ * class.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public abstract sealed class Bdd extends SubType implements SubTypeData permits BddAllOrNothing, BddNode {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddAllOrNothing.java

@@ -21,7 +21,7 @@
 /**
  * Represent the leaf node of a Bdd.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class BddAllOrNothing extends Bdd {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddIsEmptyPredicate.java

@@ -18,8 +18,20 @@
 
 package io.ballerina.runtime.api.types.semtype;
 
+/**
+ * Predicate to check if a BDD is empty.
+ *
+ * @since 2201.11.0
+ */
 @FunctionalInterface
 public interface BddIsEmptyPredicate {
 
+    /**
+     * Check if the given BDD is empty.
+     *
+     * @param cx  Type check context
+     * @param bdd BDD to check
+     * @return true if the BDD is empty, false otherwise
+     */
     boolean apply(Context cx, Bdd bdd);
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddNode.java

@@ -1,5 +1,10 @@
 package io.ballerina.runtime.api.types.semtype;
 
+/**
+ * Internal node of a BDD, which represents a disjunction of conjunctions of atoms.
+ *
+ * @since 2201.11.0
+ */
 public abstract sealed class BddNode extends Bdd permits BddNodeImpl, BddNodeSimple {
 
     private volatile Integer hashCode = null;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddNodeImpl.java

@@ -19,9 +19,9 @@
 package io.ballerina.runtime.api.types.semtype;
 
 /**
- * Internal node of a BDD, which represents a disjunction of conjunctions of atoms.
+ * Generalized implementation of {@code BddNode}.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 final class BddNodeImpl extends BddNode {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddNodeSimple.java

@@ -1,5 +1,11 @@
 package io.ballerina.runtime.api.types.semtype;
 
+/**
+ * Represent a Bdd node that contains a single atom as positive. This is used to reduce the memory overhead of
+ * BddNodeImpl in representing such nodes
+ *
+ * @since 2201.11.0
+ */
 final class BddNodeSimple extends BddNode {
 
     private final Atom atom;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/BddPredicate.java

@@ -22,7 +22,7 @@
 /**
  * Represents a predicate that can be applied to a BDD conjunction.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 @FunctionalInterface
 public interface BddPredicate {

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Builder.java

@@ -61,7 +61,7 @@
 /**
  * Utility class for creating semtypes.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class Builder {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/CacheableTypeDescriptor.java

@@ -11,9 +11,31 @@
  */
 public interface CacheableTypeDescriptor extends Type {
 
+    /**
+     * Check whether the type check result of this type descriptor should be cached. Can be used to avoid caching in
+     * cases where either directly doing the type check is cheaper or we can't determine if two instances of a type
+     * descriptor are equal without doing a type check.
+     *
+     * @return true if the type check result should be cached, false otherwise
+     */
     boolean shouldCache();
 
+    /**
+     * Check whether the type check result of this type descriptor is cached for the given type descriptor.
+     *
+     * @param cx    Context in which the type check is performed
+     * @param other Type descriptor to check the cached result for
+     * @return Optional containing the cached result if it is cached, empty otherwise
+     */
     Optional<Boolean> cachedTypeCheckResult(Context cx, CacheableTypeDescriptor other);
 
+    /**
+     * Cache the type check result of this type descriptor for the given type descriptor. Note that implementations of
+     * this method could choose to not cache the result if {@link #shouldCache()} returns false. In such cases, even
+     * after calling this method, {@link #cachedTypeCheckResult(Context, CacheableTypeDescriptor)} could return empty.
+     *
+     * @param other  Type descriptor to cache the result for
+     * @param result Result of the type check
+     */
     void cacheTypeCheckResult(CacheableTypeDescriptor other, boolean result);
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/ConcurrentLazySupplier.java

@@ -2,6 +2,12 @@
 
 import java.util.function.Supplier;
 
+/**
+ * A thread-safe single lazy supplier that initialize the value only once.
+ *
+ * @param <E> type of the value
+ * @since 2201.11.0
+ */
 public class ConcurrentLazySupplier<E> implements Supplier<E> {
 
     private Supplier<E> initializer;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/ConcurrentLazySupplierWithCallback.java

@@ -21,6 +21,12 @@
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 
+/**
+ * A thread-safe lazy supplier that initializes the value on the first call to {@link #get()} and calls the callback.
+ *
+ * @param <E> the type of the value
+ * @since 2201.11.0
+ */
 public class ConcurrentLazySupplierWithCallback<E> implements Supplier<E> {
 
     private volatile E value = null;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Conjunction.java

@@ -23,8 +23,9 @@
  * Represents the Conjunction in the BDD.
  *
  * @param atom Atom of this node
- * @param next Next node in the conjunction, will be {@code null} if this is the last node
- * @since 2201.10.0
+ * @param next Next node in the conjunction, will be {@code null} if this is the
+ *             last node
+ * @since 2201.11.0
  */
 public record Conjunction(Atom atom, Conjunction next) {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Context.java

@@ -31,10 +31,12 @@
 import java.util.WeakHashMap;
 
 /**
- * Context in which type checking operations are performed. Note context is not thread safe, and multiple type check
- * operations should not use the same context concurrently. Multiple contexts may share same environment without issue.
+ * Context in which type checking operations are performed. Note context is not
+ * thread safe, and multiple type check operations should not use the same
+ * context concurrently. Multiple contexts may share same environment without
+ * issue.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class Context {
 
@@ -53,6 +55,8 @@ private Context(Env env) {
     }
 
     private static Map<CacheableTypeDescriptor, TypeCheckCache<CacheableTypeDescriptor>> createTypeCheckCacheMemo() {
+        // This is fine since this map is not going to get leaked out of the context and
+        // context is unique to a thread. So there will be no concurrent modifications
         return new LinkedHashMap<>(MAX_CACHE_SIZE, 1f, true) {
             @Override
             protected boolean removeEldestEntry(
@@ -87,11 +91,14 @@ public boolean memoSubtypeIsEmpty(Map<Bdd, BddMemo> memoTable, BddIsEmptyPredica
     }
 
     private boolean memoSubTypeIsEmptyInner(BddIsEmptyPredicate isEmptyPredicate, Bdd bdd, BddMemo m) {
+        // We are staring the type check with the assumption our type is empty (see: inductive type)
         m.isEmpty = BddMemo.Status.PROVISIONAL;
         int initStackDepth = memoStack.size();
         memoStack.add(m);
         boolean isEmpty = isEmptyPredicate.apply(this, bdd);
         boolean isLoop = m.isEmpty == BddMemo.Status.LOOP;
+        // if not empty our assumption is wrong so we need to reset the memoized values, otherwise we cleanup the stack
+        // at the end
         if (!isEmpty || initStackDepth == 0) {
             resetMemoizedValues(initStackDepth, isEmpty, isLoop, m);
         }
@@ -103,16 +110,19 @@ private void resetMemoizedValues(int initStackDepth, boolean isEmpty, boolean is
             BddMemo.Status memoStatus = memoStack.get(i).isEmpty;
             if (Objects.requireNonNull(memoStatus) == BddMemo.Status.PROVISIONAL ||
                     memoStatus == BddMemo.Status.LOOP || memoStatus == BddMemo.Status.CYCLIC) {
+                // We started with the assumption our type is empty. Now we know for sure if we are empty or not
+                // if we are empty all of these who don't have anything except us should be empty as well.
+                // Otherwise, we don't know if they are empty or not
                 memoStack.get(i).isEmpty = isEmpty ? BddMemo.Status.TRUE : BddMemo.Status.NULL;
             }
         }
         if (memoStack.size() > initStackDepth) {
             memoStack.subList(initStackDepth, memoStack.size()).clear();
         }
-        // The only way that we have found that this can be empty is by going through a loop.
-        // This means that the shapes in the type would all be infinite.
-        // But we define types inductively, which means we only consider finite shapes.
         if (isLoop && isEmpty) {
+            // The only way that we have found that this can be empty is by going through a loop.
+            // This means that the shapes in the type would all be infinite.
+            // But we define types inductively, which means we only consider finite shapes.
             m.isEmpty = BddMemo.Status.CYCLIC;
         } else {
             m.isEmpty = isEmpty ? BddMemo.Status.TRUE : BddMemo.Status.FALSE;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Core.java

@@ -61,7 +61,7 @@
 /**
  * Contain functions defined in `core.bal` file.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class Core {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Definition.java

@@ -18,8 +18,17 @@
 
 package io.ballerina.runtime.api.types.semtype;
 
-// NOTE: definitions are not thread safe
+/**
+ * Represent a type definition which will act as a layer of indirection between {@code Env} and the type descriptor.
+ *
+ * @since 2201.11.0
+ */
 public interface Definition {
 
+    /**
+     * Get the {@code SemType} of this definition in the given environment.
+     *
+     * @param env type environment
+     */
     SemType getSemType(Env env);
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Env.java

@@ -37,9 +37,12 @@
 import java.util.function.Supplier;
 
 /**
- * Represent the environment in which {@code SemTypes} are defined in. Type checking types defined in different
- * environments with each other in undefined. This is safe to be shared between multiple threads.
- * @since 2201.10.0
+ * Represent the environment in which {@code SemTypes} are defined in. Type
+ * checking types defined in different
+ * environments with each other in undefined. This is safe to be shared between
+ * multiple threads.
+ * 
+ * @since 2201.11.0
  */
 public final class Env {
     // Currently there is no reason to worry about above restrictions since Env is a singleton, but strictly speaking
@@ -48,7 +51,8 @@ public final class Env {
     private static final Env INSTANCE = new Env();
 
     // Each atom is created once but will be accessed multiple times during type checking. Also in perfect world we
-    //  will create atoms at the beginning of the execution and will eventually reach a steady state.
+    // will create atoms at the beginning of the execution and will eventually reach
+    // a steady state.
     private final ReadWriteLock atomLock = new ReentrantReadWriteLock();
     private final Map<AtomicType, Reference<TypeAtom>> atomTable;
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/FieldPair.java

@@ -18,6 +18,17 @@
 
 package io.ballerina.runtime.api.types.semtype;
 
+/**
+ * Represent the matching fields types of two mapping atomic types.
+ *
+ * @param name   name of the field
+ * @param type1  type of the field in the first mapping
+ * @param type2  type of the field in teh second mapping
+ * @param index1 corresponding index of the field in the first mapping. If matching field is rest value is {@code null}
+ * @param index2 corresponding index of the field in the second mapping. If matching field is rest value is
+ *               {@code null}
+ * @since 2201.11.0
+ */
 public record FieldPair(String name, SemType type1, SemType type2, Integer index1, Integer index2) {
 
 }

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/FieldPairs.java

@@ -26,6 +26,11 @@
 import java.util.Objects;
 import java.util.Optional;
 
+/**
+ * {@code Iterable} over the matching fields of two mapping atomic types.
+ *
+ * @since 2201.11.0
+ */
 public class FieldPairs implements Iterable<FieldPair> {
 
     MappingAtomicType m1;

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/ListProj.java

@@ -23,7 +23,7 @@
 /**
  * Utility class for list type projection.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class ListProj {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/MappingProj.java

@@ -24,7 +24,7 @@
 /**
  * Utility class for mapping type projection.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class MappingProj {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/Pair.java

@@ -25,7 +25,7 @@
  * @param <E2>   type of second value
  * @param first  first values
  * @param second second value
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public record Pair<E1, E2>(E1 first, E2 second) {
 

bvm/ballerina-runtime/src/main/java/io/ballerina/runtime/api/types/semtype/RecAtom.java

@@ -22,7 +22,7 @@
 /**
  * Represent a recursive type atom.
  *
- * @since 2201.10.0
+ * @since 2201.11.0
  */
 public final class RecAtom implements Atom {