dart2js cps: Merge JsIrBuilder and IrBuilder.

pkg/compiler/lib/src/cps_ir/cps_ir_builder.dart

 // Copyright (c) 2013, 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.
 
 library dart2js.ir_builder;
 
 import '../compile_time_constants.dart' show BackendConstantEnvironment;
 import '../constants/constant_system.dart';
 import '../constants/expressions.dart';
 import '../constants/values.dart' show ConstantValue, PrimitiveConstantValue;
@@ skipping 404 matching lines @@
   // `List` instead of `Link`.
   SubbuildFunction subbuildSequence(/*Iterable<N>*/ nodes) {
     return (IrBuilder builder) {
       return withBuilder(builder, () => builder.buildSequence(nodes, build));
     };
   }
 }
 
 /// Shared state between delimited IrBuilders within the same function.
 class IrBuilderSharedState {
+  final GlobalProgramInformation program;
+
   final BackendConstantEnvironment constants;
 
   ConstantSystem get constantSystem => constants.constantSystem;
 
   /// A stack of collectors for breaks.
   List<JumpCollector> breakCollectors = <JumpCollector>[];
 
   /// A stack of collectors for continues.
   List<JumpCollector> continueCollectors = <JumpCollector>[];
 
   final ExecutableElement currentElement;
 
   final ir.Continuation returnContinuation = new ir.Continuation.retrn();
 
   /// The target of a return from the function.
   ///
   /// A null value indicates that the target is the function's return
   /// continuation.  Otherwise, when inside the try block of try/finally
   /// a return is intercepted to give a place to generate the finally code.
   JumpCollector returnCollector = null;
 
-  ir.Parameter _thisParameter;
-  ir.Parameter enclosingMethodThisParameter;
+  /// Parameter holding the internal value of 'this' passed to the function.
+  ///
+  /// For nested functions, this is *not* captured receiver, but the function
+  /// object itself.
+  ir.Parameter thisParameter;
+
+  /// If non-null, this refers to the receiver (`this`) in the enclosing method.
+  ir.Primitive enclosingThis;
 
   final List<ir.Parameter> functionParameters = <ir.Parameter>[];
 
-  IrBuilderSharedState(this.constants, this.currentElement);
+  /// Maps boxed locals to their location. These locals are not part of
+  /// the environment.
+  final Map<Local, ClosureLocation> boxedVariables = {};
 
-  ir.Parameter get thisParameter => _thisParameter;
-  void set thisParameter(ir.Parameter value) {
-    assert(_thisParameter == null);
-    _thisParameter = value;
-  }
+  IrBuilderSharedState(this.program, this.constants, this.currentElement);
 }
 
 class ThisParameterLocal implements Local {
   final ExecutableElement executableContext;
   ThisParameterLocal(this.executableContext);
   String get name => 'this';
   toString() => 'ThisParameterLocal($executableContext)';
 }
 
-/// A factory for building the cps IR.
+/// The IR builder maintains an environment and an IR fragment.
 ///
-/// [DartIrBuilder] and [JsIrBuilder] implement nested functions and captured
-/// variables in different ways.
-abstract class IrBuilder {
-  IrBuilder _makeInstance();
-
-  void declareLocalVariable(LocalVariableElement element,
-                            {ir.Primitive initialValue});
-
-  /// Called when entering a nested function with free variables.
-  ///
-  /// The free variables must subsequently be accessible using [buildLocalGet]
-  /// and [buildLocalSet].
-  void _enterClosureEnvironment(ClosureEnvironment env);
-
-  /// Called when entering a function body or loop body.
-  ///
-  /// This is not called for for-loops, which instead use the methods
-  /// [_enterForLoopInitializer], [_enterForLoopBody], and [_enterForLoopUpdate]
-  /// due to their special scoping rules.
-  ///
-  /// The boxed variables declared in this scope must subsequently be available
-  /// using [buildLocalGet], [buildLocalSet], etc.
-  void _enterScope(ClosureScope scope);
-
-  /// Called before building the initializer of a for-loop.
-  ///
-  /// The loop variables will subsequently be declared using
-  /// [declareLocalVariable].
-  void _enterForLoopInitializer(ClosureScope scope,
-                                List<LocalElement> loopVariables);
-
-  /// Called before building the body of a for-loop.
-  void _enterForLoopBody(ClosureScope scope,
-                         List<LocalElement> loopVariables);
-
-  /// Called before building the update of a for-loop.
-  void _enterForLoopUpdate(ClosureScope scope,
-                           List<LocalElement> loopVariables);
-
-  /// Add the given function parameter to the IR, and bind it in the environment
-  /// or put it in its box, if necessary.
-  void _createFunctionParameter(Local parameterElement);
-  void _createThisParameter();
-
-  /// Reifies the value of [variable] on the current receiver object.
-  ir.Primitive buildReifyTypeVariable(TypeVariableType variable);
-
-  /// Creates an access to the receiver from the current (or enclosing) method.
-  ///
-  /// If inside a closure class, [buildThis] will redirect access through
-  /// closure fields in order to access the receiver from the enclosing method.
-  ir.Primitive buildThis();
-
-  /// Creates a type test or type cast of [value] against [type].
-  ir.Primitive buildTypeOperator(ir.Primitive value,
-                                 DartType type,
-                                 {bool isTypeTest});
-
-  // TODO(johnniwinther): Make these field final and remove the default values
-  // when [IrBuilder] is a property of [IrBuilderVisitor] instead of a mixin.
-
+/// The IR fragment is an expression with a hole in it. The hole represents
+/// the focus where new expressions can be added. The fragment is implemented
+/// by [_root] which is the root of the expression and [_current] which is the
+/// expression that immediately contains the hole. Not all expressions have a
+/// hole (e.g., invocations, which always occur in tail position, do not have a
+/// hole). Expressions with a hole have a plug method.
+///
+/// The environment maintains the reaching definition of each local variable,
+/// including some synthetic locals such as [TypeVariableLocal].
+///
+/// Internally, IR builders also maintains a [JumpCollector] stack and tracks
+/// which variables are currently boxed or held in a mutable local variable.
+class IrBuilder {
   final List<ir.Parameter> _parameters = <ir.Parameter>[];
 
-  IrBuilderSharedState state;
+  final IrBuilderSharedState state;
 
   /// A map from variable indexes to their values.
   ///
   /// [BoxLocal]s map to their box. [LocalElement]s that are boxed are not
   /// in the map; look up their [BoxLocal] instead.
   Environment environment;
 
   /// A map from mutable local variables to their [ir.MutableVariable]s.
   ///
   /// Mutable variables are treated as boxed.  Writes to them are observable
   /// side effects.
   Map<Local, ir.MutableVariable> mutableVariables;
 
+  ir.Expression _root = null;
+  ir.Expression _current = null;
+
+  GlobalProgramInformation get program => state.program;
+
+  IrBuilder(GlobalProgramInformation program,
+            BackendConstantEnvironment constants,
+            ExecutableElement currentElement)
+    : state = new IrBuilderSharedState(program, constants, currentElement),
+      environment = new Environment.empty(),
+      mutableVariables = <Local, ir.MutableVariable>{};
+
+  IrBuilder._internal(this.state, this.environment, this.mutableVariables);
+
+  /// Construct a delimited visitor for visiting a subtree.
+  ///
+  /// Build a subterm that is not (yet) connected to the CPS term.  The
+  /// delimited visitor has its own has its own context for building an IR
+  /// expression, so the built expression is not plugged into the parent's
+  /// context.  It has its own compile-time environment mapping local
+  /// variables to their values.  If an optional environment argument is
+  /// supplied, it is used as the builder's initial environment.  Otherwise
+  /// the environment is initially a copy of the parent builder's environment.
+  IrBuilder makeDelimitedBuilder([Environment env = null]) {
+    return new IrBuilder._internal(
+        state,
+        env != null ? env : new Environment.from(environment),
+        mutableVariables);
+  }
+
   /// True if [local] should currently be accessed from a [ir.MutableVariable].
   bool isInMutableVariable(Local local) {
     return mutableVariables.containsKey(local);
   }
 
   /// Creates a [ir.MutableVariable] for the given local.
   void makeMutableVariable(Local local) {
     mutableVariables[local] = new ir.MutableVariable(local);
   }
 
   /// Remove an [ir.MutableVariable] for a local.
   ///
   /// Subsequent access to the local will be direct rather than through the
   /// mutable variable.
   void removeMutableVariable(Local local) {
     mutableVariables.remove(local);
   }
 
   /// Gets the [MutableVariable] containing the value of [local].
   ir.MutableVariable getMutableVariable(Local local) {
     return mutableVariables[local];
   }
 
-  // The IR builder maintains a context, which is an expression with a hole in
-  // it.  The hole represents the focus where new expressions can be added.
-  // The context is implemented by 'root' which is the root of the expression
-  // and 'current' which is the expression that immediately contains the hole.
-  // Not all expressions have a hole (e.g., invocations, which always occur in
-  // tail position, do not have a hole).  Expressions with a hole have a plug
-  // method.
-  //
-  // Conceptually, visiting a statement takes a context as input and returns
-  // either a new context or else an expression without a hole if all
-  // control-flow paths through the statement have exited.  An expression
-  // without a hole is represented by a (root, current) pair where root is the
-  // expression and current is null.
-  //
-  // Conceptually again, visiting an expression takes a context as input and
-  // returns either a pair of a new context and a definition denoting
-  // the expression's value, or else an expression without a hole if all
-  // control-flow paths through the expression have exited.
-  //
-  // We do not pass contexts as arguments or return them.  Rather we use the
-  // current context (root, current) as the visitor state and mutate current.
-  // Visiting a statement returns null; visiting an expression returns the
-  // primitive denoting its value.
-
-  ir.Expression _root = null;
-  ir.Expression _current = null;
-
-  /// Initialize a new top-level IR builder.
-  void _init(BackendConstantEnvironment constants,
-             ExecutableElement currentElement) {
-    state = new IrBuilderSharedState(constants, currentElement);
-    environment = new Environment.empty();
-    mutableVariables = <Local, ir.MutableVariable>{};
-  }
-
-  /// Construct a delimited visitor for visiting a subtree.
-  ///
-  /// Build a subterm that is not (yet) connected to the CPS term.  The
-  /// delimited visitor has its own has its own context for building an IR
-  /// expression, so the built expression is not plugged into the parent's
-  /// context.  It has its own compile-time environment mapping local
-  /// variables to their values.  If an optional environment argument is
-  /// supplied, it is used as the builder's initial environment.  Otherwise
-  /// the environment is initially a copy of the parent builder's environment.
-  IrBuilder makeDelimitedBuilder([Environment env = null]) {
-    return _makeInstance()
-        ..state = state
-        ..environment = env != null ? env : new Environment.from(environment)
-        ..mutableVariables = mutableVariables;
-  }
-
   bool get isOpen => _root == null || _current != null;
 
   List<ir.Primitive> buildFunctionHeader(Iterable<Local> parameters,
                                         {ClosureScope closureScope,
                                          ClosureEnvironment env}) {
     _createThisParameter();
     _enterClosureEnvironment(env);
     _enterScope(closureScope);
     parameters.forEach(_createFunctionParameter);
     return _parameters;
   }
 
   /// Creates a parameter for [local] and adds it to the current environment.
-  ir.Parameter createLocalParameter(Local local) {
+  ir.Parameter _createLocalParameter(Local local) {
     ir.Parameter parameter = new ir.Parameter(local);
     _parameters.add(parameter);
     environment.extend(local, parameter);
     return parameter;
   }
 
   /// Plug an expression into the 'hole' in the context being accumulated.  The
   /// empty context (just a hole) is represented by root (and current) being
   /// null.  Since the hole in the current context is filled by this function,
   /// the new hole must be in the newly added expression---which becomes the
@@ skipping 207 matching lines @@
                                           CallStructure callStructure,
                                           List<ir.Primitive> arguments) {
     // TODO(johnniwinther): This shouldn't be necessary.
     SelectorKind kind = Elements.isOperatorName(method.name)
         ? SelectorKind.OPERATOR : SelectorKind.CALL;
     Selector selector =
         new Selector(kind, method.memberName, callStructure);
     return _buildInvokeSuper(method, selector, arguments);
   }
 
-  /// Create a read access of the [field] on the super class.
-  ir.Primitive buildSuperFieldGet(FieldElement field) {
-    // TODO(johnniwinther): This should have its own ir node.
-    return _buildInvokeSuper(
-        field,
-        new Selector.getter(field.name, field.library),
-        const <ir.Primitive>[]);
-  }
-
   /// Create a read access of the [method] on the super class, i.e. a
   /// closurization of [method].
   ir.Primitive buildSuperMethodGet(MethodElement method) {
     // TODO(johnniwinther): This should have its own ir node.
     return _buildInvokeSuper(
         method,
         new Selector.getter(method.name, method.library),
         const <ir.Primitive>[]);
   }
 
   /// Create a getter invocation of the [getter] on the super class.
   ir.Primitive buildSuperGetterGet(MethodElement getter) {
     // TODO(johnniwinther): This should have its own ir node.
     return _buildInvokeSuper(
         getter,
         new Selector.getter(getter.name, getter.library),
         const <ir.Primitive>[]);
   }
 
-  /// Create a write access to the [field] on the super class of with [value].
-  ir.Primitive buildSuperFieldSet(Element field, ir.Primitive value) {
-    // TODO(johnniwinther): This should have its own ir node.
-    _buildInvokeSuper(
-        field,
-        new Selector.setter(field.name, field.library),
-        <ir.Primitive>[value]);
-    return value;
-  }
-
   /// Create an setter invocation of the [setter] on the super class with
   /// [value].
   ir.Primitive buildSuperSetterSet(MethodElement setter,
                                           ir.Primitive value) {
     // TODO(johnniwinther): This should have its own ir node.
     _buildInvokeSuper(
         setter,
         new Selector.setter(setter.name, setter.library),
         <ir.Primitive>[value]);
     return value;
@@ skipping 19 matching lines @@
 
   /// Create a dynamic invocation on [receiver] where the method name and
   /// argument structure are defined by [selector] and the argument values are
   /// defined by [arguments].
   ir.Primitive buildDynamicInvocation(ir.Primitive receiver,
                                       Selector selector,
                                       List<ir.Primitive> arguments) {
     return _buildInvokeDynamic(receiver, selector, arguments);
   }
 
-  /// Create an if-null expression. This is equivalent to a conditional
-  /// expression whose result is either [value] if [value] is not null, or
-  /// `right` if [value] is null. Only when [value] is null, [buildRight] is
-  /// evaluated to produce the `right` value.
-  ir.Primitive buildIfNull(ir.Primitive value,
-                           ir.Primitive buildRight(IrBuilder builder));
-
-  /// Create a conditional send. This is equivalent to a conditional expression
-  /// that checks if [receiver] is null, if so, it returns null, otherwise it
-  /// evaluates the [buildSend] expression.
-  ir.Primitive buildIfNotNullSend(ir.Primitive receiver,
-                                  ir.Primitive buildSend(IrBuilder builder));
-
   /// Create a dynamic getter invocation on [receiver] where the getter name is
   /// defined by [selector].
   ir.Primitive buildDynamicGet(ir.Primitive receiver, Selector selector) {
     assert(selector.isGetter);
     return _buildInvokeDynamic(receiver, selector, const <ir.Primitive>[]);
   }
 
   /// Create a dynamic setter invocation on [receiver] where the setter name and
   /// argument are defined by [selector] and [value], respectively.
   ir.Primitive buildDynamicSet(ir.Primitive receiver,
                                Selector selector,
                                ir.Primitive value) {
     assert(selector.isSetter);
     _buildInvokeDynamic(receiver, selector, <ir.Primitive>[value]);
     return value;
   }
 
   /// Create a dynamic index set invocation on [receiver] with the provided
   /// [index] and [value].
-  ir.Primitive  buildDynamicIndexSet(ir.Primitive receiver,
-                                     ir.Primitive index,
-                                     ir.Primitive value) {
+  ir.Primitive buildDynamicIndexSet(ir.Primitive receiver,
+                                    ir.Primitive index,
+                                    ir.Primitive value) {
     _buildInvokeDynamic(
         receiver, new Selector.indexSet(), <ir.Primitive>[index, value]);
     return value;
   }
 
-  ir.Primitive _buildLocalGet(LocalElement element);
-
   /// Create a read access of the [local] variable or parameter.
   ir.Primitive buildLocalVariableGet(LocalElement local) {
     // TODO(johnniwinther): Separate function access from variable access.
     return _buildLocalGet(local);
   }
 
   /// Create a read access of the local [function], i.e. closurization of
   /// [function].
   ir.Primitive buildLocalFunctionGet(LocalFunctionElement function) {
     // TODO(johnniwinther): Separate function access from variable access.
     return _buildLocalGet(function);
   }
 
-  /// Create a write access to the [local] variable or parameter with the
-  /// provided [value].
-  ir.Primitive buildLocalVariableSet(LocalElement local, ir.Primitive value);
-
   /// Create an invocation of the the [local] variable or parameter where
   /// argument structure is defined by [callStructure] and the argument values
   /// are defined by [arguments].
   ir.Primitive buildLocalVariableInvocation(LocalVariableElement local,
                                             CallStructure callStructure,
                                             List<ir.Primitive> arguments) {
     return buildCallInvocation(
         buildLocalVariableGet(local), callStructure, arguments);
   }
 
@@ skipping 74 matching lines @@
   /// [selector] and the argument values are defined by [arguments].
   // TODO(johnniwinther): Make this more fine-grained.
   ir.Primitive buildErroneousInvocation(
       Element element,
       Selector selector,
       List<ir.Primitive> arguments) {
     // TODO(johnniwinther): This should have its own ir node.
     return _buildInvokeStatic(element, selector, arguments, null);
   }
 
-  /// Create a constructor invocation of [element] on [type] where the
-  /// constructor name and argument structure are defined by [callStructure] and
-  /// the argument values are defined by [arguments].
-  ir.Primitive buildConstructorInvocation(FunctionElement element,
-                                          CallStructure callStructure,
-                                          DartType type,
-                                          List<ir.Primitive> arguments);
-
-  ir.Primitive buildStringify(ir.Primitive argument);
-
   /// Concatenate string values.
   ///
   /// The arguments must be strings; usually a call to [buildStringify] is
   /// needed to ensure the proper conversion takes places.
   ir.Primitive buildStringConcatenation(List<ir.Primitive> arguments) {
     assert(isOpen);
     return addPrimitive(new ir.ApplyBuiltinOperator(
         ir.BuiltinOperator.StringConcatenate,
         arguments));
   }
@@ skipping 1111 matching lines @@
                               leftTrueContinuation,
                               leftFalseContinuation))));
     environment = join.environment;
     return environment.discard(1);
   }
 
   ir.Primitive buildIdentical(ir.Primitive x, ir.Primitive y) {
     return addPrimitive(new ir.ApplyBuiltinOperator(
         ir.BuiltinOperator.Identical, <ir.Primitive>[x, y]));
   }
-}
 
-/// State shared between JsIrBuilders within the same function.
-///
-/// Note that this is not shared between builders of nested functions.
-class JsIrBuilderSharedState {
-  /// Maps boxed locals to their location. These locals are not part of
-  /// the environment.
-  final Map<Local, ClosureLocation> boxedVariables = {};
-
-  /// If non-null, this refers to the receiver (`this`) in the enclosing method.
-  ir.Primitive receiver;
-
-  /// `true` when we are currently building expressions inside the initializer
-  /// list of a constructor.
-  bool inInitializers = false;
-}
-
-/// JS-specific subclass of [IrBuilder].
-///
-/// Inner functions are represented by a [ClosureClassElement], and captured
-/// variables are boxed as necessary using [CreateBox], [GetField], [SetField].
-class JsIrBuilder extends IrBuilder {
-  final JsIrBuilderSharedState jsState;
-  final GlobalProgramInformation program;
-
-  IrBuilder _makeInstance() => new JsIrBuilder._blank(program, jsState);
-  JsIrBuilder._blank(this.program, this.jsState);
-
-  JsIrBuilder(this.program, BackendConstantEnvironment constants,
-      ExecutableElement currentElement)
-      : jsState = new JsIrBuilderSharedState() {
-    _init(constants, currentElement);
-  }
-
-  void enterInitializers() {
-    assert(jsState.inInitializers == false);
-    jsState.inInitializers = true;
-  }
-
-  void leaveInitializers() {
-    assert(jsState.inInitializers == true);
-    jsState.inInitializers = false;
-  }
-
+  /// Called when entering a nested function with free variables.
+  ///
+  /// The free variables must subsequently be accessible using [buildLocalGet]
+  /// and [buildLocalSet].
   void _enterClosureEnvironment(ClosureEnvironment env) {
     if (env == null) return;
 
     // Obtain a reference to the function object (this).
     ir.Parameter thisPrim = state.thisParameter;
 
     // Obtain access to the free variables.
     env.freeVariables.forEach((Local local, ClosureLocation location) {
       if (location.isBox) {
         // Boxed variables are loaded from their box on-demand.
-        jsState.boxedVariables[local] = location;
+        state.boxedVariables[local] = location;
       } else {
         // Unboxed variables are loaded from the function object immediately.
         // This includes BoxLocals which are themselves unboxed variables.
         environment.extend(local,
             addPrimitive(new ir.GetField(thisPrim, location.field)));
       }
     });
 
     // If the function captures a reference to the receiver from the
     // enclosing method, remember which primitive refers to the receiver object.
     if (env.thisLocal != null && env.freeVariables.containsKey(env.thisLocal)) {
-      jsState.receiver = environment.lookup(env.thisLocal);
+      state.enclosingThis = environment.lookup(env.thisLocal);
     }
 
     // If the function has a self-reference, use the value of `this`.
     if (env.selfReference != null) {
       environment.extend(env.selfReference, thisPrim);
     }
   }
 
   /// Creates a box for [scope.box] and binds the captured variables to
   /// that box.
   ///
   /// The captured variables can subsequently be manipulated with
   /// [declareLocalVariable], [buildLocalGet], and [buildLocalSet].
   void enterScope(ClosureScope scope) => _enterScope(scope);
 
+  /// Called when entering a function body or loop body.
+  ///
+  /// This is not called for for-loops, which instead use the methods
+  /// [_enterForLoopInitializer], [_enterForLoopBody], and [_enterForLoopUpdate]
+  /// due to their special scoping rules.
+  ///
+  /// The boxed variables declared in this scope must subsequently be available
+  /// using [buildLocalGet], [buildLocalSet], etc.
   void _enterScope(ClosureScope scope) {
     if (scope == null) return;
     ir.CreateBox boxPrim = addPrimitive(new ir.CreateBox());
     environment.extend(scope.box, boxPrim);
     boxPrim.useElementAsHint(scope.box);
     scope.capturedVariables.forEach((Local local, ClosureLocation location) {
-      assert(!jsState.boxedVariables.containsKey(local));
+      assert(!state.boxedVariables.containsKey(local));
       if (location.isBox) {
-        jsState.boxedVariables[local] = location;
+        state.boxedVariables[local] = location;
       }
     });
   }
 
+  /// Add the given function parameter to the IR, and bind it in the environment
+  /// or put it in its box, if necessary.
   void _createFunctionParameter(Local parameterElement) {
     ir.Parameter parameter = new ir.Parameter(parameterElement);
     _parameters.add(parameter);
     state.functionParameters.add(parameter);
-    ClosureLocation location = jsState.boxedVariables[parameterElement];
+    ClosureLocation location = state.boxedVariables[parameterElement];
     if (location != null) {
       add(new ir.SetField(environment.lookup(location.box),
                           location.field,
                           parameter));
     } else {
       environment.extend(parameterElement, parameter);
     }
   }
 
   void _createThisParameter() {
+    assert(state.thisParameter == null);
     if (Elements.isStaticOrTopLevel(state.currentElement)) return;
     if (state.currentElement.isLocal) return;
     state.thisParameter =
         new ir.Parameter(new ThisParameterLocal(state.currentElement));
   }
 
   void declareLocalVariable(LocalElement variableElement,
                             {ir.Primitive initialValue}) {
     assert(isOpen);
     if (initialValue == null) {
       initialValue = buildNullConstant();
     }
-    ClosureLocation location = jsState.boxedVariables[variableElement];
+    ClosureLocation location = state.boxedVariables[variableElement];
     if (location != null) {
       add(new ir.SetField(environment.lookup(location.box),
                           location.field,
                           initialValue));
     } else if (isInMutableVariable(variableElement)) {
       add(new ir.LetMutable(getMutableVariable(variableElement),
                             initialValue));
     } else {
       initialValue.useElementAsHint(variableElement);
       environment.extend(variableElement, initialValue);
@@ skipping 15 matching lines @@
       ir.Primitive value = field.local is ThisLocal
           ? buildThis()
           : environment.lookup(field.local);
       arguments.add(value);
     }
     return addPrimitive(
         new ir.CreateInstance(classElement, arguments, const <ir.Primitive>[]));
   }
 
   /// Create a read access of [local] variable or parameter.
-  @override
   ir.Primitive _buildLocalGet(LocalElement local) {
     assert(isOpen);
-    ClosureLocation location = jsState.boxedVariables[local];
+    ClosureLocation location = state.boxedVariables[local];
     if (location != null) {
       ir.Primitive result = new ir.GetField(environment.lookup(location.box),
                                             location.field);
       result.useElementAsHint(local);
       return addPrimitive(result);
     } else if (isInMutableVariable(local)) {
       return addPrimitive(new ir.GetMutableVariable(getMutableVariable(local)));
     } else {
       return environment.lookup(local);
     }
   }
 
   /// Create a write access to [local] variable or parameter with the provided
   /// [value].
-  @override
   ir.Primitive buildLocalVariableSet(LocalElement local, ir.Primitive value) {
     assert(isOpen);
-    ClosureLocation location = jsState.boxedVariables[local];
+    ClosureLocation location = state.boxedVariables[local];
     if (location != null) {
       add(new ir.SetField(environment.lookup(location.box),
                           location.field,
                           value));
     } else if (isInMutableVariable(local)) {
       add(new ir.SetMutableVariable(getMutableVariable(local), value));
     } else {
       value.useElementAsHint(local);
       environment.update(local, value);
     }
     return value;
   }
 
+  /// Called before building the initializer of a for-loop.
+  ///
+  /// The loop variables will subsequently be declared using
+  /// [declareLocalVariable].
   void _enterForLoopInitializer(ClosureScope scope,
                                 List<LocalElement> loopVariables) {
     if (scope == null) return;
     // If there are no boxed loop variables, don't create the box here, let
     // it be created inside the body instead.
     if (scope.boxedLoopVariables.isEmpty) return;
     _enterScope(scope);
   }
 
+  /// Called before building the body of a for-loop.
   void _enterForLoopBody(ClosureScope scope,
                          List<LocalElement> loopVariables) {
     if (scope == null) return;
     // If there are boxed loop variables, the box has already been created
     // at the initializer.
     if (!scope.boxedLoopVariables.isEmpty) return;
     _enterScope(scope);
   }
 
+  /// Called before building the update of a for-loop.
   void _enterForLoopUpdate(ClosureScope scope,
                            List<LocalElement> loopVariables) {
     if (scope == null) return;
     // If there are no boxed loop variables, then the box is created inside the
     // body, so there is no need to explicitly renew it.
     if (scope.boxedLoopVariables.isEmpty) return;
     ir.Primitive box = environment.lookup(scope.box);
     ir.Primitive newBox = addPrimitive(new ir.CreateBox());
     newBox.useElementAsHint(scope.box);
     for (VariableElement loopVar in scope.boxedLoopVariables) {
       ClosureLocation location = scope.capturedVariables[loopVar];
       ir.Primitive value = addPrimitive(new ir.GetField(box, location.field));
       add(new ir.SetField(newBox, location.field, value));
     }
     environment.update(scope.box, newBox);
   }
 
+  /// Creates an access to the receiver from the current (or enclosing) method.
+  ///
+  /// If inside a closure class, [buildThis] will redirect access through
+  /// closure fields in order to access the receiver from the enclosing method.
   ir.Primitive buildThis() {
-    if (jsState.receiver != null) return jsState.receiver;
+    if (state.enclosingThis != null) return state.enclosingThis;
     assert(state.thisParameter != null);
     return state.thisParameter;
   }
 
-  @override
   ir.Primitive buildSuperFieldGet(FieldElement target) {
     return addPrimitive(new ir.GetField(buildThis(), target));
   }
 
-  @override
   ir.Primitive buildSuperFieldSet(FieldElement target, ir.Primitive value) {
     add(new ir.SetField(buildThis(), target, value));
     return value;
   }
 
   ir.Primitive buildInvokeDirectly(FunctionElement target,
                                    ir.Primitive receiver,
                                    List<ir.Primitive> arguments) {
     assert(isOpen);
     Selector selector =
         new Selector.call(target.name, target.library, arguments.length);
     return _continueWithExpression(
         (k) => new ir.InvokeMethodDirectly(
             receiver, target, selector, arguments, k));
   }
 
   /// Loads parameters to a constructor body into the environment.
   ///
   /// The header for a constructor body differs from other functions in that
   /// some parameters are already boxed, and the box is passed as an argument
   /// instead of being created in the header.
   void buildConstructorBodyHeader(Iterable<Local> parameters,
                                   ClosureScope closureScope) {
     _createThisParameter();
     for (Local param in parameters) {
-      ir.Parameter parameter = createLocalParameter(param);
+      ir.Parameter parameter = _createLocalParameter(param);
       state.functionParameters.add(parameter);
     }
     if (closureScope != null) {
-      jsState.boxedVariables.addAll(closureScope.capturedVariables);
+      state.boxedVariables.addAll(closureScope.capturedVariables);
     }
   }
 
-  @override
+  /// Create a constructor invocation of [element] on [type] where the
+  /// constructor name and argument structure are defined by [callStructure] and
+  /// the argument values are defined by [arguments].
   ir.Primitive buildConstructorInvocation(ConstructorElement element,
                                           CallStructure callStructure,
                                           DartType type,
                                           List<ir.Primitive> arguments) {
     assert(isOpen);
     Selector selector =
         new Selector(SelectorKind.CALL, element.memberName, callStructure);
     ClassElement cls = element.enclosingClass;
     if (program.requiresRuntimeTypesFor(cls)) {
       InterfaceType interface = type;
@@ skipping 52 matching lines @@
   }
 
   /// Make the given type variable accessible through the local environment
   /// with the value of [binding].
   void declareTypeVariable(TypeVariableType variable, DartType binding) {
     environment.extend(
         new TypeVariableLocal(variable, state.currentElement),
         buildTypeExpression(binding));
   }
 
-  @override
+  /// Reifies the value of [variable] on the current receiver object.
   ir.Primitive buildReifyTypeVariable(TypeVariableType variable) {
     ir.Primitive typeArgument = buildTypeVariableAccess(variable);
     return addPrimitive(new ir.ReifyRuntimeType(typeArgument));
   }
 
   ir.Primitive buildInvocationMirror(Selector selector,
                                      List<ir.Primitive> arguments) {
     return addPrimitive(new ir.CreateInvocationMirror(selector, arguments));
   }
 
   ir.Primitive buildForeignCode(js.Template codeTemplate,
                                 List<ir.Primitive> arguments,
                                 NativeBehavior behavior,
                                 {Element dependency}) {
     types.TypeMask type = program.getTypeMaskForForeign(behavior);
     if (codeTemplate.isExpression) {
       return _continueWithExpression((k) => new ir.ForeignCode(
         codeTemplate,
         type,
         arguments,
         behavior,
         continuation: k,
         dependency: dependency));
     } else {
       assert(isOpen);
       add(new ir.ForeignCode(codeTemplate, type, arguments, behavior,
           dependency: dependency));
       _current = null;
+      return null;
     }
   }
 
-  @override
+  /// Creates a type test or type cast of [value] against [type].
   ir.Primitive buildTypeOperator(ir.Primitive value,
                                  DartType type,
                                  {bool isTypeTest}) {
     assert(isOpen);
     assert(isTypeTest != null);
 
     type = program.unaliasType(type);
 
     if (type.isMalformed) {
       FunctionElement helper = program.throwTypeErrorHelper;
@@ skipping 27 matching lines @@
         // `x is Null` is true if and only if x is null.
         return _buildCheckNull(value);
       }
       return addPrimitive(new ir.TypeTest(value, type, typeArguments));
     } else {
       return _continueWithExpression(
               (k) => new ir.TypeCast(value, type, typeArguments, k));
     }
   }
 
-  @override
+  /// Create an if-null expression. This is equivalent to a conditional
+  /// expression whose result is either [value] if [value] is not null, or
+  /// `right` if [value] is null. Only when [value] is null, [buildRight] is
+  /// evaluated to produce the `right` value.
   ir.Primitive buildIfNull(ir.Primitive value,
                            ir.Primitive buildRight(IrBuilder builder)) {
     ir.Primitive condition = _buildCheckNull(value);
     return buildConditional(condition, buildRight, (_) => value);
   }
 
-  @override
+  /// Create a conditional send. This is equivalent to a conditional expression
+  /// that checks if [receiver] is null, if so, it returns null, otherwise it
+  /// evaluates the [buildSend] expression.
   ir.Primitive buildIfNotNullSend(ir.Primitive receiver,
                                   ir.Primitive buildSend(IrBuilder builder)) {
     ir.Primitive condition = _buildCheckNull(receiver);
     return buildConditional(condition, (_) => receiver, buildSend);
   }
 
   /// Creates a type test checking whether [value] is null.
   ir.Primitive _buildCheckNull(ir.Primitive value) {
     assert(isOpen);
     return buildIdentical(value, buildNullConstant());
@@ skipping 80 matching lines @@
 }
 
 class SwitchCaseInfo {
   final List<ir.Primitive> constants = <ir.Primitive>[];
   final SubbuildFunction buildBody;
 
   SwitchCaseInfo(this.buildBody);
 
   void addConstant(ir.Primitive constant) => constants.add(constant);
 }