From a6a1664a659243677476ab80e4b17d40865fecdb Mon Sep 17 00:00:00 2001
From: Tom Rodriguez <tom.rodriguez@oracle.com>
Date: Wed, 1 Jun 2022 23:26:16 -0700
Subject: [PATCH] Comments

---
 .../phases/common/IncrementalCanonicalizerPhase.java |  1 +
 .../src/org/graalvm/compiler/phases/BasePhase.java   | 12 +++++++++---
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/compiler/src/org.graalvm.compiler.phases.common/src/org/graalvm/compiler/phases/common/IncrementalCanonicalizerPhase.java b/compiler/src/org.graalvm.compiler.phases.common/src/org/graalvm/compiler/phases/common/IncrementalCanonicalizerPhase.java
index 1e9e838e3863..db81b4355e63 100644
--- a/compiler/src/org.graalvm.compiler.phases.common/src/org/graalvm/compiler/phases/common/IncrementalCanonicalizerPhase.java
+++ b/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());
                 }
diff --git a/compiler/src/org.graalvm.compiler.phases/src/org/graalvm/compiler/phases/BasePhase.java b/compiler/src/org.graalvm.compiler.phases/src/org/graalvm/compiler/phases/BasePhase.java
index 125ad33947a2..4a315f65ae2a 100644
--- a/compiler/src/org.graalvm.compiler.phases/src/org/graalvm/compiler/phases/BasePhase.java
+++ b/compiler/src/org.graalvm.compiler.phases/src/org/graalvm/compiler/phases/BasePhase.java
@@ -206,6 +206,10 @@ 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);
     }
@@ -213,9 +217,9 @@ public interface ApplyScope {
     /**
      * 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 {