Improve comments.

Author: cstancu

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/results/ReachabilitySimplifier.java

@@ -283,18 +283,26 @@ protected String location(Node node) {
         return "method " + StrengthenGraphs.getQualifiedName(graph) + ", node " + node;
     }
 
+    /**
+     * Tries to improve the stamp based on reachability information. It only handles
+     * {@link AbstractObjectStamp object stamps} as all primitives types are considered implicitly
+     * reachable and the analysis (reachability or points-to) doesn't track primitive ranges.
+     * <p>
+     * Returns a new {@link Stamp} if the input stamp can be improved, or {@code  null} otherwise.
+     */
     private Stamp strengthenStamp(Stamp s) {
         if (!(s instanceof AbstractObjectStamp stamp)) {
+            /* We can only strengthen object types. */
             return null;
         }
         AnalysisType originalType = (AnalysisType) stamp.type();
         if (originalType == null) {
+            /* The stamp is either empty or a non-exact java.lang.Object; nothing to strengthen. */
             return null;
         }
 
         /* In open world the type may become reachable later. */
         if (strengthenGraphs.isClosedTypeWorld && !originalType.isReachable()) {
-            /* We must be in dead code. */
             if (stamp.nonNull()) {
                 /* We must be in dead code. */
                 return StampFactory.empty(JavaKind.Object);

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/results/StrengthenGraphs.java

@@ -243,23 +243,26 @@ public final void applyResults(AnalysisMethod method) {
 
     protected abstract void persistStrengthenGraph(AnalysisMethod method);
 
-    /*
+    /**
      * Returns a type that can replace the original type in stamps as an exact type. When the
      * returned type is the original type itself, the original type has no subtype and can be used
      * as an exact type.
-     *
-     * Returns null if there is no single implementor type.
+     * <p>
+     * Returns {@code null} if there is no optimization potential, i.e., if the original type
+     * doesn't have a unique implementor type, or we cannot prove that it has a unique implementor
+     * type due to open-world analysis.
      */
     protected abstract AnalysisType getSingleImplementorType(AnalysisType originalType);
 
-    /*
+    /**
      * Returns a type that can replace the original type in stamps.
-     *
-     * Returns null if the original type has no assignable type that is instantiated, i.e., the code
-     * using the type is unreachable.
-     *
+     * <p>
+     * Returns {@code null} if the original type has no assignable type that is instantiated, i.e.,
+     * the code using the type is unreachable.
+     * <p>
      * Returns the original type itself if there is no optimization potential, i.e., if the original
-     * type itself is instantiated or has more than one instantiated direct subtype.
+     * type itself is instantiated or has more than one instantiated direct subtype, or we cannot
+     * prove that it doesn't have any instantiated subtype due to open-world analysis.
      */
     protected abstract AnalysisType getStrengthenStampType(AnalysisType originalType);
 

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/meta/HostedType.java

@@ -65,7 +65,6 @@ public abstract class HostedType extends HostedElement implements SharedType, Wr
 
     boolean loadedFromPriorLayer;
     protected int typeID;
-    protected HostedType uniqueConcreteImplementation;
     protected HostedMethod[] allDeclaredMethods;
 
     // region closed-world only fields
@@ -140,13 +139,27 @@ public abstract class HostedType extends HostedElement implements SharedType, Wr
     // endregion open-world only fields
 
     /**
-     * A more precise subtype that can replace this type as the declared type of values. Null if
-     * this type is never instantiated and does not have any instantiated subtype, i.e., if no value
-     * of this type can ever exist. Equal to this type if this type is instantiated, i.e, this type
-     * cannot be strengthened.
-     * 
-     * For open world the strengthen stamp type is equal to this type itself if the type is not a
-     * leaf type, i.e., it cannot be extended.
+     * The unique implementor of this type that can replace it in stamps as an exact type.
+     * <p>
+     * A {@code null} value means there is no unique implementor that can replace this type. The
+     * field is set to this type itself if it has no instantiated subtypes to enable its usage as an
+     * exact type, e.g., in places where the original stamp was non-exact.
+     * <p>
+     * In open-world analysis the field is set to {@code null} for non-leaf types since we have to
+     * assume that there may be some instantiated subtypes that we haven't seen yet.
+     */
+    protected HostedType uniqueConcreteImplementation;
+
+    /**
+     * A more precise subtype that can replace this type as the declared type of values.
+     * <p>
+     * A {@code null} value means that this type is never instantiated and does not have any
+     * instantiated subtype, i.e., no value of this type can ever exist and the code using this type
+     * is unreachable. It is set to this type if this type is itself instantiated or has more than
+     * one instantiated direct subtype, i.e, this type cannot be strengthened.
+     * <p>
+     * In open-world analysis the field is set to this type itself for non-leaf types since we have
+     * to assume that there may be some instantiated subtypes that we haven't seen yet.
      */
     protected HostedType strengthenStampType;