Edit docs as per Siggi's feedback.

pkg/compiler/lib/src/closure.dart

Index: pkg/compiler/lib/src/closure.dart
diff --git a/pkg/compiler/lib/src/closure.dart b/pkg/compiler/lib/src/closure.dart
index 32fe9398c7e1691fefb0bdc4568fcae7dc905ffe..2a54748c75bb31113dbf7456af1a8301903b3496 100644
--- a/pkg/compiler/lib/src/closure.dart
+++ b/pkg/compiler/lib/src/closure.dart
@@ -121,6 +121,10 @@ class LoopClosureRepresentationInfo extends ClosureAnalysisInfo {
 ///
 /// if y is modified elsewhere within its scope, accesses to y anywhere in the

[Siggi Cherem (dart-lang), 2017/06/15 00:12:24]

just noticed, maybe quote `y` here as well.

[Emily Fortuna, 2017/06/15 00:13:35]

thx!

 /// code will be controlled via a box object.
+///
+/// Because in these examples `y` was declared in some other, outer scope, but
+/// used in the inner scope of this closure, we say `y` is a "captured"
+/// variable.
 /// TODO(efortuna): Make interface simpler in subsequent refactorings.
 class ClosureRepresentationInfo {
   const ClosureRepresentationInfo();
@@ -130,11 +134,11 @@ class ClosureRepresentationInfo {
   /// Will be null for methods.
   Local get closureEntity => null;
 
+  /// The entity for the class used to represent the rewritten closure in the
+  /// emitted JavaScript.
+  ///
   /// Closures are rewritten in the form of classes that have fields to control
-  /// the redirection and editing of variables that are "captured" inside a
-  /// scope (declared in an outer scope but used in an inside scope). So this
-  /// returns the class entity that represents this particular rewritten
-  /// closure.
+  /// the redirection and editing of captured variables.
   ClassEntity get closureClassEntity => null;
 
   /// The function that implements the [local] function as a `call` method on