Comments

compiler/src/org.graalvm.compiler.phases.common/src/org/graalvm/compiler/phases/common/IncrementalCanonicalizerPhase.java

@@ -98,6 +98,7 @@ public Apply(StructuredGraph graph, CoreProviders context, CanonicalizerPhase ca
         public void close(Throwable throwable) {
             scope.close();
             if (throwable == null) {
+                // Perform the canonicalization if the main work completed without an exception.
                 if (!listener.getNodes().isEmpty()) {
                     canonicalizer.applyIncremental(graph, context, listener.getNodes());
                 }

compiler/src/org.graalvm.compiler.phases/src/org/graalvm/compiler/phases/BasePhase.java

@@ -206,16 +206,20 @@ protected boolean shouldDumpAfterAtBasicLevel() {
         return false;
     }
 
+    /**
+     * Similar to a {@link DebugCloseable} but the {@link #close} operation gets a {@link Throwable}
+     * argument indicating whether the call to {@link #run} completed normally or with an exception.
+     */
     public interface ApplyScope {
         void close(Throwable t);
     }
 
     /**
      * An extension point for subclasses, called at the start of
      * {@link BasePhase#apply(StructuredGraph, Object, boolean)}. The return value is a
-     * {@link DebugCloseable scope} which will surround all the work performed by the
-     * {@link #apply}. This allows subclaseses to inject work which will performed before and after
-     * the application of this phase.
+     * {@link ApplyScope} which will surround all the work performed by the {@link #apply}. This
+     * allows subclaseses to inject work which will performed before and after the application of
+     * this phase.
      */
     @SuppressWarnings("unused")
     protected ApplyScope applyScope(StructuredGraph graph, C context) {
@@ -251,6 +255,8 @@ public final void apply(final StructuredGraph graph, final C context, final bool
             }
             inputNodesCount.add(debug, graph.getNodeCount());
 
+            // This is a manual version of a try/resource pattern since the close operation might
+            // want to know whether the run call completed with an exception or not.
             ApplyScope applyScope = applyScope(graph, context);
             Throwable throwable = null;
             try {