Document copy_captured_locals in the source code

PullRequest: truffleruby/599

src/main/java/org/truffleruby/extra/TruffleGraalNodes.java

@@ -77,7 +77,16 @@ public DynamicObject splitProc(DynamicObject rubyProc) {
         }
     }
 
-    // Like Smalltalk's fixTemps but not mutating the Proc
+    /**
+     * This method creates a new Proc with a copy of the captured variables' values, which is
+     * correct if these variables are not changed in the parent scope later on. It works by
+     * replacing {@link ReadDeclarationVariableNode} with the captured variables' values. This
+     * avoids constantly reading from the declaration frame (which always escapes in a
+     * define_method) and folds many checks on these captured variables since their values become
+     * compilation constants.
+     * <p>
+     * Similar to Smalltalk's fixTemps, but not mutating the Proc.
+     */
     @CoreMethod(names = "copy_captured_locals", onSingleton = true, required = 1)
     public abstract static class CopyCapturedLocalsNode extends CoreMethodArrayArgumentsNode {