Edit docs as per Siggi's feedback.

pkg/compiler/lib/src/closure.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 import 'common/names.dart' show Identifiers;
 import 'common/resolution.dart' show ParsingContext, Resolution;
 import 'common/tasks.dart' show CompilerTask;
 import 'common.dart';
 import 'compiler.dart' show Compiler;
 import 'constants/expressions.dart';
@@ skipping 101 matching lines @@
 ///       int y;
 ///       FooClosure(this.y);
 ///       call(x) => this.y + x;
 ///    }
 ///
 ///  and then to execute this closure, for example:
 ///
 ///     var foo = new FooClosure(1);
 ///     foo.call(2);
 ///
 /// 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();
 
   /// The original local function before any translation.
   ///
   /// 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
   /// the closure class.
   FunctionEntity get callMethod => null;
 
   /// As shown in the example in the comments at the top of this class, we
   /// create fields in the closure class for each captured variable. This is an
   /// accessor to that set of fields.
   List<Local> get createdFieldEntities => const <Local>[];
@@ skipping 1296 matching lines @@
 ///
 /// Move the below classes to a JS model eventually.
 ///
 abstract class JSEntity implements MemberEntity {
   Local get declaredEntity;
 }
 
 abstract class PrivatelyNamedJSEntity implements JSEntity {
   Entity get rootOfScope;
 }