Add a few doc comments.

pkg/front_end/lib/src/fasta/kernel/frontend_accessors.dart

 // Copyright (c) 2016, 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.
 
 // Note: copied from package:kernel at revision 7346348.
 
 /// A library to help transform compounds and null-aware accessors into
 /// let expressions.
 library kernel.frontend.accessors;
 
 import 'package:kernel/ast.dart';
 
+/// An [Accessor] represents a subexpression for which we can't yet build a
+/// kernel [Expression] because we don't yet know the context in which it is
+/// used.
+///
+/// Once the context is known, an [Accessor] can be converted into an
+/// [Expression] by calling a "build" method.
+///
+/// For example, when building a kernel representation for `a[x] = b`, after
+/// parsing `a[x]` but before parsing `= b`, we don't yet know whether to
+/// generate an invocation of `operator[]` or `operator[]=`, so we generate an
+/// [Accessor] object.  Later, after `= b` is parsed, [buildAssignment] will be
+/// called.
 abstract class Accessor {
+  /// Builds an [Expression] representing a read from the accessor.
   Expression buildSimpleRead() {
     return _finish(_makeSimpleRead());
   }
 
-  /// Returns an assignment to the accessor.
+  /// Builds an [Expression] representing an assignment with the accessor on
+  /// the LHS and [value] on the RHS.
   ///
   /// The returned expression evaluates to the assigned value, unless
   /// [voidContext] is true, in which case it may evaluate to anything.
   Expression buildAssignment(Expression value, {bool voidContext: false}) {
     return _finish(_makeSimpleWrite(value, voidContext));
   }
 
+  /// Returns an [Expression] representing a null-aware assignment (`??=`) with
+  /// the accessor on the LHS and [value] on the RHS.
+  ///
+  /// The returned expression evaluates to the assigned value, unless
+  /// [voidContext] is true, in which case it may evaluate to anything.
+  ///
+  /// [type] is the static type of the RHS.
   Expression buildNullAwareAssignment(Expression value, DartType type,
       {bool voidContext: false}) {
     if (voidContext) {
       return _finish(new ConditionalExpression(buildIsNull(_makeRead()),
           _makeWrite(value, false), new NullLiteral(), type));
     }
     var tmp = new VariableDeclaration.forValue(_makeRead());
     return _finish(makeLet(
         tmp,
         new ConditionalExpression(buildIsNull(new VariableGet(tmp)),
             _makeWrite(value, false), new VariableGet(tmp), type)));
   }
 
+  /// Returns an [Expression] representing a compound assignment (e.g. `+=`)
+  /// with the accessor on the LHS and [value] on the RHS.
   Expression buildCompoundAssignment(Name binaryOperator, Expression value,
       {bool voidContext: false, Procedure interfaceTarget}) {
     return _finish(_makeWrite(
         makeBinary(_makeRead(), binaryOperator, interfaceTarget, value),
         voidContext));
   }
 
+  /// Returns an [Expression] representing a pre-increment or pre-decrement
+  /// of the accessor.
   Expression buildPrefixIncrement(Name binaryOperator,
       {bool voidContext: false, Procedure interfaceTarget}) {
     return buildCompoundAssignment(binaryOperator, new IntLiteral(1),
         voidContext: voidContext, interfaceTarget: interfaceTarget);
   }
 
+  /// Returns an [Expression] representing a post-increment or post-decrement
+  /// of the accessor.
   Expression buildPostfixIncrement(Name binaryOperator,
       {bool voidContext: false, Procedure interfaceTarget}) {
     if (voidContext) {
       return buildPrefixIncrement(binaryOperator,
           voidContext: true, interfaceTarget: interfaceTarget);
     }
     var value = new VariableDeclaration.forValue(_makeRead());
     valueAccess() => new VariableGet(value);
     var dummy = new VariableDeclaration.forValue(_makeWrite(
         makeBinary(
             valueAccess(), binaryOperator, interfaceTarget, new IntLiteral(1)),
         true));
     return _finish(makeLet(value, makeLet(dummy, valueAccess())));
   }
 
   Expression _makeSimpleRead() => _makeRead();
 
   Expression _makeSimpleWrite(Expression value, bool voidContext) {
     return _makeWrite(value, voidContext);
   }
 
   Expression _makeRead();
 
   Expression _makeWrite(Expression value, bool voidContext);
 
   Expression _finish(Expression body) => body;
 
+  /// Returns an [Expression] representing a compile-time error.
+  ///
+  /// At runtime, an exception will be thrown.
   makeInvalidRead() => new InvalidExpression();
 
+  /// Returns an [Expression] representing a compile-time error wrapping
+  /// [value].
+  ///
+  /// At runtime, [value] will be evaluated before throwing an exception.
   makeInvalidWrite(Expression value) => wrapInvalid(value);
 }
 
 class VariableAccessor extends Accessor {
   VariableDeclaration variable;
   DartType promotedType;
 
   VariableAccessor(this.variable, [this.promotedType]);
 
   VariableAccessor.internal(this.variable, this.promotedType);
@@ skipping 329 matching lines @@
 
 VariableDeclaration makeOrReuseVariable(Expression value) {
   // TODO: Devise a way to remember if a variable declaration was reused
   // or is fresh (hence needs a let binding).
   return new VariableDeclaration.forValue(value);
 }
 
 Expression wrapInvalid(Expression e) {
   return new Let(new VariableDeclaration.forValue(e), new InvalidExpression());
 }