Update SubstitutionProcessor documentation.

Author: cstancu

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/infrastructure/SubstitutionProcessor.java

@@ -24,10 +24,22 @@
  */
 package com.oracle.graal.pointsto.infrastructure;
 
+import com.oracle.graal.pointsto.meta.AnalysisUniverse;
+
 import jdk.vm.ci.meta.ResolvedJavaField;
 import jdk.vm.ci.meta.ResolvedJavaMethod;
 import jdk.vm.ci.meta.ResolvedJavaType;
 
+/**
+ * A substitution processor is a facility that allows modifying code elements coming from class
+ * files without modifying the class files. It is queried by the {@link AnalysisUniverse} when
+ * creating the analysis model of a hosted element (type, method, field) to check if a substitution
+ * is available. How a substitution processor is implemented, i.e., when a processor decides to
+ * replace an element and how that element is constructed, is not specified. The substitution
+ * processors form a chain, created via {@link #chainUpInOrder(SubstitutionProcessor...)} and
+ * {@link #extendsTheChain(SubstitutionProcessor, SubstitutionProcessor[])} utility methods, and are
+ * queried in the order in which they were installed.
+ */
 public abstract class SubstitutionProcessor {
 
     /**
@@ -40,10 +52,24 @@ public ResolvedJavaType lookup(ResolvedJavaType type) {
         return type;
     }
 
+    /**
+     * Get the substitution of an original field.
+     *
+     * @param field the original field
+     * @return the substitution field, or the original field if it isn't covered by this
+     *         substitution
+     */
     public ResolvedJavaField lookup(ResolvedJavaField field) {
         return field;
     }
 
+    /**
+     * Get the substitution of an original method.
+     *
+     * @param method the original method
+     * @return the substitution method, or the original method if it isn't covered by this
+     *         substitution
+     */
     public ResolvedJavaMethod lookup(ResolvedJavaMethod method) {
         return method;
     }
@@ -80,7 +106,7 @@ public static SubstitutionProcessor chainUpInOrder(SubstitutionProcessor... proc
         return current;
     }
 
-    public static SubstitutionProcessor chain(SubstitutionProcessor first, SubstitutionProcessor second) {
+    private static SubstitutionProcessor chain(SubstitutionProcessor first, SubstitutionProcessor second) {
         if (first == IDENTITY) {
             return second;
         } else if (second == IDENTITY) {

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/substitute/AnnotationSubstitutionProcessor.java

@@ -48,7 +48,6 @@
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 
-import com.oracle.svm.hosted.SVMHost;
 import org.graalvm.nativeimage.AnnotationAccess;
 import org.graalvm.nativeimage.ImageSingletons;
 import org.graalvm.nativeimage.Platform;
@@ -58,6 +57,7 @@
 import com.oracle.graal.pointsto.BigBang;
 import com.oracle.graal.pointsto.infrastructure.SubstitutionProcessor;
 import com.oracle.graal.pointsto.meta.AnalysisField;
+import com.oracle.graal.pointsto.meta.AnalysisUniverse;
 import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.SubstrateUtil;
 import com.oracle.svm.core.Uninterruptible;
@@ -84,8 +84,10 @@
 import com.oracle.svm.hosted.ImageClassLoader;
 import com.oracle.svm.hosted.NativeImageGenerator;
 import com.oracle.svm.hosted.NativeImageOptions;
+import com.oracle.svm.hosted.SVMHost;
 import com.oracle.svm.hosted.ameta.FieldValueInterceptionSupport;
 import com.oracle.svm.hosted.classinitialization.ClassInitializationSupport;
+import com.oracle.svm.hosted.meta.HostedUniverse;
 import com.oracle.svm.util.ReflectionUtil;
 import com.oracle.svm.util.ReflectionUtil.ReflectionUtilError;
 
@@ -94,6 +96,28 @@
 import jdk.vm.ci.meta.ResolvedJavaMethod;
 import jdk.vm.ci.meta.ResolvedJavaType;
 
+/**
+ * The main substitution processor for Native Image. The annotations supported by this processor
+ * are:
+ * <ul>
+ * <li>{@link TargetClass}</li>
+ * <li>{@link Substitute}</li>
+ * <li>{@link TargetElement}</li>
+ * <li>{@link Alias}</li>
+ * <li>{@link AnnotateOriginal}</li>
+ * <li>{@link Delete}</li>
+ * <li>{@link Inject}</li>
+ * <li>{@link InjectAccessors}</li>
+ * <li>{@link KeepOriginal}</li>
+ * <li>{@link RecomputeFieldValue}</li>
+ * </ul>
+ * Code tagged with these annotations is preprocessed during Native Image setup when the processor
+ * is {@link AnnotationSubstitutionProcessor#init(FieldValueInterceptionSupport) initialized}. Then,
+ * hosted code corresponding to the substitution code is intercepted and replaced without modifying
+ * the class files during {@link AnalysisUniverse} lookups. See each annotation's JavaDoc for more
+ * details, starting with {@link TargetClass}. See also {@link HostedUniverse} for a comprehensive
+ * description of the substitution layer.
+ */
 public class AnnotationSubstitutionProcessor extends SubstitutionProcessor {
 
     /**
@@ -306,7 +330,7 @@ public void registerUnsafeAccessedFields(BigBang bb) {
     }
 
     public void init(FieldValueInterceptionSupport newFieldValueInterceptionSupport) {
-        /**
+        /*
          * Cannot set this field in the constructor due to cyclic dependencies between the two
          * classes.
          */