Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/lib/src/generated/resolver.dart

 // Copyright (c) 2014, 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.
 
 // This code was auto-generated, is not intended to be edited, and is subject to
 // significant change. Please see the README file for more information.
 
 library engine.resolver;
 
 import 'dart:collection';
@@ skipping 52 matching lines @@
 
   static String _NG_CALLBACK = "NgCallback";
 
   static String _NG_ONE_WAY = "NgOneWay";
 
   static String _NG_ONE_WAY_ONE_TIME = "NgOneWayOneTime";
 
   static String _NG_TWO_WAY = "NgTwoWay";
 
   static Element getElement(ASTNode node, int offset) {
+    // maybe no node
     if (node == null) {
       return null;
     }
+    // prepare enclosing ClassDeclaration
     ClassDeclaration classDeclaration = node.getAncestor(ClassDeclaration);
     if (classDeclaration == null) {
       return null;
     }
+    // prepare ClassElement
     ClassElement classElement = classDeclaration.element;
     if (classElement == null) {
       return null;
     }
+    // check toolkit objects
     for (ToolkitObjectElement toolkitObject in classElement.toolkitObjects) {
       List<AngularPropertyElement> properties = AngularPropertyElement.EMPTY_ARRAY;
+      // try properties of AngularComponentElement
       if (toolkitObject is AngularComponentElement) {
         AngularComponentElement component = toolkitObject;
         properties = component.properties;
       }
+      // try properties of AngularDirectiveElement
       if (toolkitObject is AngularDirectiveElement) {
         AngularDirectiveElement directive = toolkitObject;
         properties = directive.properties;
       }
+      // check properties
       for (AngularPropertyElement property in properties) {
+        // property name (use complete node range)
         int propertyOffset = property.nameOffset;
         int propertyEnd = propertyOffset + property.name.length;
         if (node.offset <= propertyOffset && propertyEnd < node.end) {
           return property;
         }
+        // field name (use complete node range, including @, => and <=>)
         FieldElement field = property.field;
         if (field != null) {
           int fieldOffset = property.fieldNameOffset;
           int fieldEnd = fieldOffset + field.name.length;
           if (node.offset <= fieldOffset && fieldEnd < node.end) {
             return field;
           }
         }
       }
     }
+    // no Element
     return null;
   }
 
   /**
    * Checks if given [Type] is an Angular <code>Module</code> or its subclass.
    */
   static bool isModule(Type2 type) {
     if (type is! InterfaceType) {
       return false;
     }
     InterfaceType interfaceType = type as InterfaceType;
+    // check hierarchy
     Set<Type2> seenTypes = new Set();
     while (interfaceType != null) {
+      // check for recursion
       if (!seenTypes.add(interfaceType)) {
         return false;
       }
+      // check for "Module"
       if (interfaceType.element.name == "Module") {
         return true;
       }
+      // try supertype
       interfaceType = interfaceType.superclass;
     }
+    // no
     return false;
   }
 
   /**
    * Parses given selector text and returns [AngularSelectorElement]. May be `null` if
    * cannot parse.
    */
   static AngularSelectorElement parseSelector(int offset, String text) {
     if (text.startsWith("[") && text.endsWith("]")) {
       int nameOffset = offset + "[".length;
       String attributeName = text.substring(1, text.length - 1);
+      // TODO(scheglov) report warning if there are spaces between [ and identifier
       return new HasAttributeSelectorElementImpl(attributeName, nameOffset);
     }
     if (StringUtilities.isTagName(text)) {
       return new IsTagSelectorElementImpl(text, offset);
     }
     return null;
   }
 
   /**
    * Returns the [FieldElement] of the first field in the given [FieldDeclaration].
@@ skipping 79 matching lines @@
     this._errorListener = errorListener;
     this._source = source;
   }
 
   /**
    * Builds Angular specific element models and adds them to the existing Dart elements.
    *
    * @param unit the compilation unit with built Dart element models
    */
   void build(CompilationUnit unit) {
+    // process classes
     for (CompilationUnitMember unitMember in unit.declarations) {
       if (unitMember is ClassDeclaration) {
         this._classDeclaration = unitMember;
         this._classElement = _classDeclaration.element as ClassElementImpl;
         this._classToolkitObjects.clear();
         parseModuleClass();
+        // process annotations
         NodeList<Annotation> annotations = _classDeclaration.metadata;
         for (Annotation annotation in annotations) {
           this._annotation = annotation;
+          // @NgFilter
           if (isAngularAnnotation2(_NG_FILTER)) {
             parseNgFilter();
             continue;
           }
+          // @NgComponent
           if (isAngularAnnotation2(_NG_COMPONENT)) {
             parseNgComponent();
             continue;
           }
+          // @NgController
           if (isAngularAnnotation2(_NG_CONTROLLER)) {
             parseNgController();
             continue;
           }
+          // @NgDirective
           if (isAngularAnnotation2(_NG_DIRECTIVE)) {
             parseNgDirective();
             continue;
           }
         }
+        // set toolkit objects
         if (!_classToolkitObjects.isEmpty) {
           List<ToolkitObjectElement> objects = _classToolkitObjects;
           _classElement.toolkitObjects = new List.from(objects);
         }
       }
     }
+    // process modules in variables
     parseModuleVariables(unit);
   }
 
   /**
    * Creates [AngularModuleElementImpl] for given information.
    */
   AngularModuleElementImpl createModuleElement(List<AngularModuleElement> childModules, List<ClassElement> keyTypes) {
     AngularModuleElementImpl module = new AngularModuleElementImpl();
     module.childModules = new List.from(childModules);
     module.keyTypes = new List.from(keyTypes);
@@ skipping 73 matching lines @@
   }
 
   /**
    * Analyzes [classDeclaration] and if it is a module, creates [AngularModuleElement]
    * model for it.
    */
   void parseModuleClass() {
     if (!isModule4) {
       return;
     }
+    // check install(), type() and value() invocations
     List<AngularModuleElement> childModules = [];
     List<ClassElement> keyTypes = [];
     _classDeclaration.accept(new RecursiveASTVisitor_AngularCompilationUnitBuilder_parseModuleClass(this, childModules, keyTypes));
+    // set module element
     AngularModuleElementImpl module = createModuleElement(childModules, keyTypes);
     _classToolkitObjects.add(module);
   }
 
   /**
    * Checks if given [MethodInvocation] is an interesting <code>Module</code> method
    * invocation and remembers corresponding elements into lists.
    */
   void parseModuleInvocation(MethodInvocation node, List<AngularModuleElement> childModules, List<ClassElement> keyTypes) {
     String methodName = node.methodName.name;
     NodeList<Expression> arguments = node.argumentList.arguments;
+    // install()
     if (arguments.length == 1 && methodName == "install") {
       Type2 argType = arguments[0].bestType;
       if (argType is InterfaceType) {
         ClassElement argElement = argType.element;
         List<ToolkitObjectElement> toolkitObjects = argElement.toolkitObjects;
         for (ToolkitObjectElement toolkitObject in toolkitObjects) {
           if (toolkitObject is AngularModuleElement) {
             childModules.add(toolkitObject);
           }
         }
       }
       return;
     }
+    // type() and value()
     if (arguments.length >= 1 && (methodName == "type" || methodName == "value")) {
       Expression arg = arguments[0];
       if (arg is Identifier) {
         Element argElement = arg.staticElement;
         if (argElement is ClassElement) {
           keyTypes.add(argElement);
         }
       }
       return;
     }
   }
 
   /**
    * Checks every local variable in the given unit to see if it is a <code>Module</code> and creates
    * [AngularModuleElement] for it.
    */
   void parseModuleVariables(CompilationUnit unit) {
     unit.accept(new RecursiveASTVisitor_AngularCompilationUnitBuilder_parseModuleVariables(this));
   }
 
   void parseNgComponent() {
     bool isValid = true;
+    // publishAs
     if (!hasStringArgument(_PUBLISH_AS)) {
       reportErrorForAnnotation(AngularCode.MISSING_PUBLISH_AS, []);
       isValid = false;
     }
+    // selector
     AngularSelectorElement selector = null;
     if (!hasStringArgument(_SELECTOR)) {
       reportErrorForAnnotation(AngularCode.MISSING_SELECTOR, []);
       isValid = false;
     } else {
       SimpleStringLiteral selectorLiteral = getStringLiteral(_SELECTOR);
       selector = parseSelector2(selectorLiteral);
       if (selector == null) {
         reportErrorForArgument(_SELECTOR, AngularCode.CANNOT_PARSE_SELECTOR, [selectorLiteral]);
         isValid = false;
       }
     }
+    // templateUrl
     if (!hasStringArgument(_TEMPLATE_URL)) {
       reportErrorForAnnotation(AngularCode.MISSING_TEMPLATE_URL, []);
       isValid = false;
     }
+    // cssUrl
     if (!hasStringArgument(_CSS_URL)) {
       reportErrorForAnnotation(AngularCode.MISSING_CSS_URL, []);
       isValid = false;
     }
+    // create
     if (isValid) {
       String name = getStringArgument(_PUBLISH_AS);
       int nameOffset = getStringArgumentOffset(_PUBLISH_AS);
       String templateUri = getStringArgument(_TEMPLATE_URL);
       int templateUriOffset = getStringArgumentOffset(_TEMPLATE_URL);
       String styleUri = getStringArgument(_CSS_URL);
       int styleUriOffset = getStringArgumentOffset(_CSS_URL);
       AngularComponentElementImpl element = new AngularComponentElementImpl(name, nameOffset);
       element.selector = selector;
       element.templateUri = templateUri;
@@ skipping 19 matching lines @@
 
   /**
    * Parses [AngularPropertyElement]s from [annotation].
    */
   void parseNgComponentProperties_fromFields(List<AngularPropertyElement> properties) {
     NodeList<ClassMember> members = _classDeclaration.members;
     for (ClassMember member in members) {
       if (member is FieldDeclaration) {
         FieldDeclaration fieldDeclaration = member;
         for (Annotation annotation in fieldDeclaration.metadata) {
+          // prepare property kind (if property annotation at all)
           AngularPropertyKind kind = null;
           if (isAngularAnnotation(annotation, _NG_ATTR)) {
             kind = AngularPropertyKind.ATTR;
           } else if (isAngularAnnotation(annotation, _NG_CALLBACK)) {
             kind = AngularPropertyKind.CALLBACK;
           } else if (isAngularAnnotation(annotation, _NG_ONE_WAY)) {
             kind = AngularPropertyKind.ONE_WAY;
           } else if (isAngularAnnotation(annotation, _NG_ONE_WAY_ONE_TIME)) {
             kind = AngularPropertyKind.ONE_WAY_ONE_TIME;
           } else if (isAngularAnnotation(annotation, _NG_TWO_WAY)) {
             kind = AngularPropertyKind.TWO_WAY;
           }
+          // add property
           if (kind != null) {
             SimpleStringLiteral nameLiteral = getOnlySimpleStringLiteralArgument(annotation);
             FieldElement field = getOnlyFieldElement(fieldDeclaration);
             if (nameLiteral != null && field != null) {
               AngularPropertyElementImpl property = new AngularPropertyElementImpl(nameLiteral.value, nameLiteral.valueOffset);
               property.field = field;
               property.propertyKind = kind;
               properties.add(property);
             }
           }
         }
       }
     }
   }
 
   /**
    * Parses [AngularPropertyElement]s from [annotation].
    */
   void parseNgComponentProperties_fromMap(List<AngularPropertyElement> properties) {
     Expression mapExpression = getArgument("map");
+    // may be not properties
     if (mapExpression == null) {
       return;
     }
+    // prepare map literal
     if (mapExpression is! MapLiteral) {
       reportError(mapExpression, AngularCode.INVALID_PROPERTY_MAP, []);
       return;
     }
     MapLiteral mapLiteral = mapExpression as MapLiteral;
+    // analyze map entries
     for (MapLiteralEntry entry in mapLiteral.entries) {
+      // prepare property name
       Expression nameExpression = entry.key;
       if (nameExpression is! SimpleStringLiteral) {
         reportError(nameExpression, AngularCode.INVALID_PROPERTY_NAME, []);
         continue;
       }
       SimpleStringLiteral nameLiteral = nameExpression as SimpleStringLiteral;
       String name = nameLiteral.value;
       int nameOffset = nameLiteral.valueOffset;
+      // prepare field specification
       Expression specExpression = entry.value;
       if (specExpression is! SimpleStringLiteral) {
         reportError(specExpression, AngularCode.INVALID_PROPERTY_SPEC, []);
         continue;
       }
       SimpleStringLiteral specLiteral = specExpression as SimpleStringLiteral;
       String spec = specLiteral.value;
+      // parse binding kind and field name
       AngularPropertyKind kind;
       int fieldNameOffset;
       if (spec.startsWith(_PREFIX_ATTR)) {
         kind = AngularPropertyKind.ATTR;
         fieldNameOffset = 1;
       } else if (spec.startsWith(_PREFIX_CALLBACK)) {
         kind = AngularPropertyKind.CALLBACK;
         fieldNameOffset = 1;
       } else if (spec.startsWith(_PREFIX_ONE_WAY_ONE_TIME)) {
         kind = AngularPropertyKind.ONE_WAY_ONE_TIME;
         fieldNameOffset = 3;
       } else if (spec.startsWith(_PREFIX_ONE_WAY)) {
         kind = AngularPropertyKind.ONE_WAY;
         fieldNameOffset = 2;
       } else if (spec.startsWith(_PREFIX_TWO_WAY)) {
         kind = AngularPropertyKind.TWO_WAY;
         fieldNameOffset = 3;
       } else {
         reportError(specLiteral, AngularCode.INVALID_PROPERTY_KIND, [spec]);
         continue;
       }
       String fieldName = spec.substring(fieldNameOffset);
       fieldNameOffset += specLiteral.valueOffset;
+      // prepare field
       FieldElement field = _classElement.getField(fieldName);
       if (field == null) {
         reportError2(fieldNameOffset, fieldName.length, AngularCode.INVALID_PROPERTY_FIELD, [fieldName]);
         continue;
       }
+      // add property
       AngularPropertyElementImpl property = new AngularPropertyElementImpl(name, nameOffset);
       property.field = field;
       property.propertyKind = kind;
       property.fieldNameOffset = fieldNameOffset;
       properties.add(property);
     }
   }
 
   void parseNgController() {
     bool isValid = true;
+    // publishAs
     if (!hasStringArgument(_PUBLISH_AS)) {
       reportErrorForAnnotation(AngularCode.MISSING_PUBLISH_AS, []);
       isValid = false;
     }
+    // selector
     AngularSelectorElement selector = null;
     if (!hasStringArgument(_SELECTOR)) {
       reportErrorForAnnotation(AngularCode.MISSING_SELECTOR, []);
       isValid = false;
     } else {
       SimpleStringLiteral selectorLiteral = getStringLiteral(_SELECTOR);
       selector = parseSelector2(selectorLiteral);
       if (selector == null) {
         reportErrorForArgument(_SELECTOR, AngularCode.CANNOT_PARSE_SELECTOR, [selectorLiteral]);
         isValid = false;
       }
     }
+    // create
     if (isValid) {
       String name = getStringArgument(_PUBLISH_AS);
       int nameOffset = getStringArgumentOffset(_PUBLISH_AS);
       AngularControllerElementImpl element = new AngularControllerElementImpl(name, nameOffset);
       element.selector = selector;
       _classToolkitObjects.add(element);
     }
   }
 
   void parseNgDirective() {
     bool isValid = true;
+    // selector
     AngularSelectorElement selector = null;
     if (!hasStringArgument(_SELECTOR)) {
       reportErrorForAnnotation(AngularCode.MISSING_SELECTOR, []);
       isValid = false;
     } else {
       SimpleStringLiteral selectorLiteral = getStringLiteral(_SELECTOR);
       selector = parseSelector2(selectorLiteral);
       if (selector == null) {
         reportErrorForArgument(_SELECTOR, AngularCode.CANNOT_PARSE_SELECTOR, [selectorLiteral]);
         isValid = false;
       }
     }
+    // create
     if (isValid) {
       int offset = _annotation.offset;
       AngularDirectiveElementImpl element = new AngularDirectiveElementImpl(offset);
       element.selector = selector;
       element.properties = parseNgComponentProperties(false);
       _classToolkitObjects.add(element);
     }
   }
 
   void parseNgFilter() {
     bool isValid = true;
+    // name
     if (!hasStringArgument(_NAME)) {
       reportErrorForAnnotation(AngularCode.MISSING_NAME, []);
       isValid = false;
     }
+    // create
     if (isValid) {
       String name = getStringArgument(_NAME);
       int nameOffset = getStringArgumentOffset(_NAME);
       _classToolkitObjects.add(new AngularFilterElementImpl(name, nameOffset));
     }
   }
 
   void reportError(ASTNode node, ErrorCode errorCode, List<Object> arguments) {
     int offset = node.offset;
     int length = node.length;
@@ skipping 37 matching lines @@
   RecursiveASTVisitor_AngularCompilationUnitBuilder_parseModuleVariables(this.AngularCompilationUnitBuilder_this) : super();
 
   LocalVariableElementImpl _variable = null;
 
   Expression _variableInit = null;
 
   List<AngularModuleElement> _childModules = [];
 
   List<ClassElement> _keyTypes = [];
 
+  Object visitClassDeclaration(ClassDeclaration node) => null;
+
   Object visitFunctionDeclaration(FunctionDeclaration node) {
     _childModules.clear();
     _keyTypes.clear();
     super.visitFunctionDeclaration(node);
     if (_variable != null) {
       AngularModuleElementImpl module = AngularCompilationUnitBuilder_this.createModuleElement(_childModules, _keyTypes);
       _variable.toolkitObjects = <ToolkitObjectElement> [module];
     }
     return null;
   }
@@ skipping 11 matching lines @@
     VariableElement element = node.element;
     if (element is LocalVariableElementImpl && AngularCompilationUnitBuilder.isModule2(node)) {
       _variable = element;
       _variableInit = node.initializer;
     }
     return super.visitVariableDeclaration(node);
   }
 
   bool isVariableInvocation(MethodInvocation node) {
     Expression target = node.realTarget;
+    // var module = new Module()..type(t1)..type(t2);
     if (_variableInit is CascadeExpression && target != null && identical(target.parent, _variableInit)) {
       return true;
     }
+    // var module = new Module();
+    // module.type(t);
     if (target is Identifier) {
       Element targetElement = target.staticElement;
       return identical(targetElement, _variable);
     }
+    // no
     return false;
   }
 }
 
 /**
  * Instances of the class `CompilationUnitBuilder` build an element model for a single
  * compilation unit.
  *
  * @coverage dart.engine.resolver
  */
@@ skipping 107 matching lines @@
     visitChildren(holder, node);
     SimpleIdentifier className = node.name;
     ClassElementImpl element = new ClassElementImpl(className);
     List<TypeParameterElement> typeParameters = holder.typeParameters;
     List<Type2> typeArguments = createTypeParameterTypes(typeParameters);
     InterfaceTypeImpl interfaceType = new InterfaceTypeImpl.con1(element);
     interfaceType.typeArguments = typeArguments;
     element.type = interfaceType;
     List<ConstructorElement> constructors = holder.constructors;
     if (constructors.length == 0) {
+      //
+      // Create the default constructor.
+      //
       constructors = createDefaultConstructors(interfaceType);
     }
     element.abstract = node.abstractKeyword != null;
     element.accessors = holder.accessors;
     element.constructors = constructors;
     element.fields = holder.fields;
     element.methods = holder.methods;
     element.typeParameters = typeParameters;
     element.validMixin = _isValidMixin;
     int functionTypeCount = _functionTypesToFix.length;
@@ skipping 14 matching lines @@
     SimpleIdentifier className = node.name;
     ClassElementImpl element = new ClassElementImpl(className);
     element.abstract = node.abstractKeyword != null;
     element.typedef = true;
     List<TypeParameterElement> typeParameters = holder.typeParameters;
     element.typeParameters = typeParameters;
     List<Type2> typeArguments = createTypeParameterTypes(typeParameters);
     InterfaceTypeImpl interfaceType = new InterfaceTypeImpl.con1(element);
     interfaceType.typeArguments = typeArguments;
     element.type = interfaceType;
+    // set default constructor
     element.constructors = createDefaultConstructors(interfaceType);
     for (FunctionTypeImpl functionType in _functionTypesToFix) {
       functionType.typeArguments = typeArguments;
     }
     _functionTypesToFix = null;
     _currentHolder.addType(element);
     className.staticElement = element;
     holder.validate();
     return null;
   }
@@ skipping 52 matching lines @@
     SimpleIdentifier parameterName = node.parameter.identifier;
     ParameterElementImpl parameter;
     if (node.parameter is FieldFormalParameter) {
       parameter = new DefaultFieldFormalParameterElementImpl(parameterName);
     } else {
       parameter = new DefaultParameterElementImpl(parameterName);
     }
     parameter.const3 = node.isConst;
     parameter.final2 = node.isFinal;
     parameter.parameterKind = node.kind;
+    // set initializer, default value range
     Expression defaultValue = node.defaultValue;
     if (defaultValue != null) {
       visit(holder, defaultValue);
       FunctionElementImpl initializer = new FunctionElementImpl.con2(defaultValue.beginToken.offset);
       initializer.functions = holder.functions;
       initializer.labels = holder.labels;
       initializer.localVariables = holder.localVariables;
       initializer.parameters = holder.parameters;
       initializer.synthetic = true;
       parameter.initializer = initializer;
       parameter.setDefaultValueRange(defaultValue.offset, defaultValue.length);
     }
+    // visible range
     setParameterVisibleRange(node, parameter);
     _currentHolder.addParameter(parameter);
     parameterName.staticElement = parameter;
     node.parameter.accept(this);
     holder.validate();
     return null;
   }
 
   Object visitFieldDeclaration(FieldDeclaration node) {
     bool wasInField = _inFieldContext;
     _inFieldContext = true;
     try {
       node.visitChildren(this);
     } finally {
       _inFieldContext = wasInField;
     }
     return null;
   }
 
   Object visitFieldFormalParameter(FieldFormalParameter node) {
     if (node.parent is! DefaultFormalParameter) {
       SimpleIdentifier parameterName = node.identifier;
       FieldFormalParameterElementImpl parameter = new FieldFormalParameterElementImpl(parameterName);
       parameter.const3 = node.isConst;
       parameter.final2 = node.isFinal;
       parameter.parameterKind = node.kind;
       _currentHolder.addParameter(parameter);
       parameterName.staticElement = parameter;
     }
+    //
+    // The children of this parameter include any parameters defined on the type of this parameter.
+    //
     ElementHolder holder = new ElementHolder();
     visitChildren(holder, node);
     (node.element as ParameterElementImpl).parameters = holder.parameters;
     holder.validate();
     return null;
   }
 
   Object visitFunctionDeclaration(FunctionDeclaration node) {
     FunctionExpression expression = node.functionExpression;
     if (expression != null) {
@@ skipping 20 matching lines @@
             int blockEnd = enclosingBlock.offset + enclosingBlock.length;
             element.setVisibleRange(functionEnd, blockEnd - functionEnd - 1);
           }
         }
         _currentHolder.addFunction(element);
         expression.element = element;
         functionName.staticElement = element;
       } else {
         SimpleIdentifier propertyNameNode = node.name;
         if (propertyNameNode == null) {
+          // TODO(brianwilkerson) Report this internal error.
           return null;
         }
         String propertyName = propertyNameNode.name;
         TopLevelVariableElementImpl variable = _currentHolder.getTopLevelVariable(propertyName) as TopLevelVariableElementImpl;
         if (variable == null) {
           variable = new TopLevelVariableElementImpl.con2(node.name.name);
           variable.final2 = true;
           variable.synthetic = true;
           _currentHolder.addTopLevelVariable(variable);
         }
@@ skipping 83 matching lines @@
 
   Object visitFunctionTypedFormalParameter(FunctionTypedFormalParameter node) {
     if (node.parent is! DefaultFormalParameter) {
       SimpleIdentifier parameterName = node.identifier;
       ParameterElementImpl parameter = new ParameterElementImpl.con1(parameterName);
       parameter.parameterKind = node.kind;
       setParameterVisibleRange(node, parameter);
       _currentHolder.addParameter(parameter);
       parameterName.staticElement = parameter;
     }
+    //
+    // The children of this parameter include any parameters defined on the type of this parameter.
+    //
     ElementHolder holder = new ElementHolder();
     visitChildren(holder, node);
     (node.element as ParameterElementImpl).parameters = holder.parameters;
     holder.validate();
     return null;
   }
 
   Object visitLabeledStatement(LabeledStatement node) {
     bool onSwitchStatement = node.statement is SwitchStatement;
     for (Label label in node.labels) {
@@ skipping 145 matching lines @@
       LocalVariableElementImpl variable;
       if (isConst && hasInitializer) {
         variable = new ConstLocalVariableElementImpl(variableName);
       } else {
         variable = new LocalVariableElementImpl(variableName);
       }
       element = variable;
       Block enclosingBlock = node.getAncestor(Block);
       int functionEnd = node.offset + node.length;
       int blockEnd = enclosingBlock.offset + enclosingBlock.length;
+      // TODO(brianwilkerson) This isn't right for variables declared in a for loop.
       variable.setVisibleRange(functionEnd, blockEnd - functionEnd - 1);
       _currentHolder.addLocalVariable(variable);
       variableName.staticElement = element;
     } else {
       SimpleIdentifier variableName = node.name;
       TopLevelVariableElementImpl variable;
       if (isConst && hasInitializer) {
         variable = new ConstTopLevelVariableElementImpl(variableName);
       } else {
         variable = new TopLevelVariableElementImpl.con1(variableName);
@@ skipping 607 matching lines @@
       String scriptSourcePath = scriptAttribute == null ? null : scriptAttribute.text;
       if (identical(node.attributeEnd.type, ht.TokenType.GT) && scriptSourcePath == null) {
         EmbeddedHtmlScriptElementImpl script = new EmbeddedHtmlScriptElementImpl(node);
         try {
           LibraryResolver resolver = new LibraryResolver(_context);
           LibraryElementImpl library = resolver.resolveEmbeddedLibrary(htmlSource, _modificationStamp, node.script, true) as LibraryElementImpl;
           script.scriptLibrary = library;
           _resolvedLibraries.addAll(resolver.resolvedLibraries);
           _errorListener.addAll(resolver.errorListener);
         } on AnalysisException catch (exception) {
+          //TODO (danrubel): Handle or forward the exception
           AnalysisEngine.instance.logger.logError3(exception);
         }
         node.scriptElement = script;
         _scripts.add(script);
       } else {
         ExternalHtmlScriptElementImpl script = new ExternalHtmlScriptElementImpl(node);
         if (scriptSourcePath != null) {
           try {
             scriptSourcePath = Uri.encodeFull(scriptSourcePath);
+            // Force an exception to be thrown if the URI is invalid so that we can report the
+            // problem.
             parseUriWithException(scriptSourcePath);
             Source scriptSource = _context.sourceFactory.resolveUri(htmlSource, scriptSourcePath);
             script.scriptSource = scriptSource;
             if (scriptSource == null || !scriptSource.exists()) {
               reportValueError(HtmlWarningCode.URI_DOES_NOT_EXIST, scriptAttribute, [scriptSourcePath]);
             }
           } on URISyntaxException catch (exception) {
             reportValueError(HtmlWarningCode.INVALID_URI, scriptAttribute, [scriptSourcePath]);
           }
         }
@@ skipping 51 matching lines @@
   ht.XmlAttributeNode getScriptSourcePath(ht.XmlTagNode node) {
     for (ht.XmlAttributeNode attribute in node.attributes) {
       if (attribute.name == _SRC) {
         return attribute;
       }
     }
     return null;
   }
 
   Object reportCircularity(ht.XmlTagNode node) {
+    //
+    // This should not be possible, but we have an error report that suggests that it happened at
+    // least once. This code will guard against infinite recursion and might help us identify the
+    // cause of the issue.
+    //
     JavaStringBuilder builder = new JavaStringBuilder();
     builder.append("Found circularity in XML nodes: ");
     bool first = true;
     for (ht.XmlTagNode pathNode in _parentNodes) {
       if (first) {
         first = false;
       } else {
         builder.append(", ");
       }
       String tagName = pathNode.tag;
@@ skipping 114 matching lines @@
   Object visitBinaryExpression(BinaryExpression node) {
     checkForDivisionOptimizationHint(node);
     checkForDeprecatedMemberUse(node.bestElement, node);
     return super.visitBinaryExpression(node);
   }
 
   Object visitClassDeclaration(ClassDeclaration node) {
     ClassElement outerClass = _enclosingClass;
     try {
       _enclosingClass = node.element;
+      // Commented out until we decide that we want this hint in the analyzer
+      //    checkForOverrideEqualsButNotHashCode(node);
       return super.visitClassDeclaration(node);
     } finally {
       _enclosingClass = outerClass;
     }
   }
 
   Object visitExportDirective(ExportDirective node) {
     checkForDeprecatedMemberUse(node.uriElement, node);
     return super.visitExportDirective(node);
   }
@@ skipping 17 matching lines @@
     checkForDeprecatedMemberUse(node.staticElement, node);
     return super.visitInstanceCreationExpression(node);
   }
 
   Object visitIsExpression(IsExpression node) {
     checkAllTypeChecks(node);
     return super.visitIsExpression(node);
   }
 
   Object visitMethodDeclaration(MethodDeclaration node) {
-    checkForOverridingPrivateMember(node);
+    // This was determined to not be a good hint, see: dartbug.com/16029
+    //checkForOverridingPrivateMember(node);
     checkForMissingReturn(node.returnType, node.body);
     return super.visitMethodDeclaration(node);
   }
 
   Object visitPostfixExpression(PostfixExpression node) {
     checkForDeprecatedMemberUse(node.bestElement, node);
     return super.visitPostfixExpression(node);
   }
 
   Object visitPrefixExpression(PrefixExpression node) {
@@ skipping 29 matching lines @@
    */
   bool checkAllTypeChecks(IsExpression node) {
     Expression expression = node.expression;
     TypeName typeName = node.type;
     Type2 lhsType = expression.staticType;
     Type2 rhsType = typeName.type;
     if (lhsType == null || rhsType == null) {
       return false;
     }
     String rhsNameStr = typeName.name.name;
+    // if x is dynamic
     if (rhsType.isDynamic && rhsNameStr == sc.Keyword.DYNAMIC.syntax) {
       if (node.notOperator == null) {
+        // the is case
         _errorReporter.reportError3(HintCode.UNNECESSARY_TYPE_CHECK_TRUE, node, []);
       } else {
+        // the is not case
         _errorReporter.reportError3(HintCode.UNNECESSARY_TYPE_CHECK_FALSE, node, []);
       }
       return true;
     }
     Element rhsElement = rhsType.element;
     LibraryElement libraryElement = rhsElement != null ? rhsElement.library : null;
     if (libraryElement != null && libraryElement.isDartCore) {
+      // if x is Object or null is Null
       if (rhsType.isObject || (expression is NullLiteral && rhsNameStr == _NULL_TYPE_NAME)) {
         if (node.notOperator == null) {
+          // the is case
           _errorReporter.reportError3(HintCode.UNNECESSARY_TYPE_CHECK_TRUE, node, []);
         } else {
+          // the is not case
           _errorReporter.reportError3(HintCode.UNNECESSARY_TYPE_CHECK_FALSE, node, []);
         }
         return true;
       } else if (rhsNameStr == _NULL_TYPE_NAME) {
         if (node.notOperator == null) {
+          // the is case
           _errorReporter.reportError3(HintCode.TYPE_CHECK_IS_NULL, node, []);
         } else {
+          // the is not case
           _errorReporter.reportError3(HintCode.TYPE_CHECK_IS_NOT_NULL, node, []);
         }
         return true;
       }
     }
     return false;
   }
 
   /**
    * Given some [Element], look at the associated metadata and report the use of the member if
    * it is declared as deprecated.
    *
    * @param element some element to check for deprecated use of
    * @param node the node use for the location of the error
    * @return `true` if and only if a hint code is generated on the passed node
    * @see HintCode#DEPRECATED_MEMBER_USE
    */
   bool checkForDeprecatedMemberUse(Element element, ASTNode node) {
     if (element != null && element.isDeprecated) {
       String displayName = element.displayName;
       if (element is ConstructorElement) {
+        // TODO(jwren) We should modify ConstructorElement.getDisplayName(), or have the logic
+        // centralized elsewhere, instead of doing this logic here.
         ConstructorElement constructorElement = element;
         displayName = constructorElement.enclosingElement.displayName;
         if (!constructorElement.displayName.isEmpty) {
           displayName = "${displayName}.${constructorElement.displayName}";
         }
       }
       _errorReporter.reportError3(HintCode.DEPRECATED_MEMBER_USE, node, [displayName]);
       return true;
     }
     return false;
@@ skipping 25 matching lines @@
   }
 
   /**
    * Check for the passed binary expression for the [HintCode#DIVISION_OPTIMIZATION].
    *
    * @param node the binary expression to check
    * @return `true` if and only if a hint code is generated on the passed node
    * @see HintCode#DIVISION_OPTIMIZATION
    */
   bool checkForDivisionOptimizationHint(BinaryExpression node) {
+    // Return if the operator is not '/'
     if (node.operator.type != sc.TokenType.SLASH) {
       return false;
     }
+    // Return if the '/' operator is not defined in core, or if we don't know its static or propagated type
     MethodElement methodElement = node.bestElement;
     if (methodElement == null) {
       return false;
     }
     LibraryElement libraryElement = methodElement.library;
     if (libraryElement != null && !libraryElement.isDartCore) {
       return false;
     }
+    // Report error if the (x/y) has toInt() invoked on it
     if (node.parent is ParenthesizedExpression) {
       ParenthesizedExpression parenthesizedExpression = wrapParenthesizedExpression(node.parent as ParenthesizedExpression);
       if (parenthesizedExpression.parent is MethodInvocation) {
         MethodInvocation methodInvocation = parenthesizedExpression.parent as MethodInvocation;
         if (_TO_INT_METHOD_NAME == methodInvocation.methodName.name && methodInvocation.argumentList.arguments.isEmpty) {
           _errorReporter.reportError3(HintCode.DIVISION_OPTIMIZATION, methodInvocation, []);
           return true;
         }
       }
     }
@@ skipping 38 matching lines @@
 
   /**
    * Checks that if the passed method declaration is private, it does not override a private member
    * in a superclass.
    *
    * @param node the method declaration to check
    * @return `true` if and only if a hint code is generated on the passed node
    * @see HintCode#OVERRIDDING_PRIVATE_MEMBER
    */
   bool checkForOverridingPrivateMember(MethodDeclaration node) {
+    // If not in an enclosing class, return false
     if (_enclosingClass == null) {
       return false;
     }
+    // If the member is not private, return false
     if (!Identifier.isPrivateName(node.name.name)) {
       return false;
     }
+    // Get the element of the member, if null, return false
     ExecutableElement executableElement = node.element;
     if (executableElement == null) {
       return false;
     }
+    // Loop through all of the superclasses looking for a matching method or accessor
+    // TODO(jwren) If the HintGenerator needs or has easy access to the InheritanceManager in the
+    // future then this could be refactored down to be more readable, however, since we are only
+    // looking through super classes (and not the entire interface graph) there is no pressing need
     String elementName = executableElement.name;
     bool isGetterOrSetter = executableElement is PropertyAccessorElement;
     InterfaceType superType = _enclosingClass.supertype;
     if (superType == null) {
       return false;
     }
     ClassElement classElement = superType.element;
     while (classElement != null) {
       if (_enclosingClass.library != classElement.library) {
         if (isGetterOrSetter) {
@@ skipping 35 matching lines @@
    *
    * @param node the as expression to check
    * @return `true` if and only if a hint code is generated on the passed node
    * @see HintCode#UNNECESSARY_CAST
    */
   bool checkForUnnecessaryCast(AsExpression node) {
     Expression expression = node.expression;
     TypeName typeName = node.type;
     Type2 lhsType = expression.staticType;
     Type2 rhsType = typeName.type;
+    // TODO(jwren) After dartbug.com/13732, revisit this, we should be able to remove the
+    // !(x instanceof TypeParameterType) checks.
     if (lhsType != null && rhsType != null && !lhsType.isDynamic && !rhsType.isDynamic && lhsType is! TypeParameterType && rhsType is! TypeParameterType && lhsType.isSubtypeOf(rhsType)) {
       _errorReporter.reportError3(HintCode.UNNECESSARY_CAST, node, []);
       return true;
     }
     return false;
   }
 }
 
 /**
  * Instances of the class `Dart2JSVerifier` traverse an AST structure looking for hints for
@@ skipping 37 matching lines @@
    * @see HintCode#IS_NOT_DOUBLE
    * @see HintCode#IS_NOT_INT
    */
   bool checkForIsDoubleHints(IsExpression node) {
     TypeName typeName = node.type;
     Type2 type = typeName.type;
     if (type != null && type.element != null) {
       Element element = type.element;
       String typeNameStr = element.name;
       LibraryElement libraryElement = element.library;
+      //      if (typeNameStr.equals(INT_TYPE_NAME) && libraryElement != null
+      //          && libraryElement.isDartCore()) {
+      //        if (node.getNotOperator() == null) {
+      //          errorReporter.reportError(HintCode.IS_INT, node);
+      //        } else {
+      //          errorReporter.reportError(HintCode.IS_NOT_INT, node);
+      //        }
+      //        return true;
+      //      } else
       if (typeNameStr == _DOUBLE_TYPE_NAME && libraryElement != null && libraryElement.isDartCore) {
         if (node.notOperator == null) {
           _errorReporter.reportError3(HintCode.IS_DOUBLE, node, []);
         } else {
           _errorReporter.reportError3(HintCode.IS_NOT_DOUBLE, node, []);
         }
         return true;
       }
     }
     return false;
@@ skipping 24 matching lines @@
   Object visitBinaryExpression(BinaryExpression node) {
     sc.Token operator = node.operator;
     bool isAmpAmp = identical(operator.type, sc.TokenType.AMPERSAND_AMPERSAND);
     bool isBarBar = identical(operator.type, sc.TokenType.BAR_BAR);
     if (isAmpAmp || isBarBar) {
       Expression lhsCondition = node.leftOperand;
       if (!isDebugConstant(lhsCondition)) {
         ValidResult lhsResult = getConstantBooleanValue(lhsCondition);
         if (lhsResult != null) {
           if (lhsResult.isTrue && isBarBar) {
+            // report error on else block: true || !e!
             _errorReporter.reportError3(HintCode.DEAD_CODE, node.rightOperand, []);
+            // only visit the LHS:
             safelyVisit(lhsCondition);
             return null;
           } else if (lhsResult.isFalse && isAmpAmp) {
+            // report error on if block: false && !e!
             _errorReporter.reportError3(HintCode.DEAD_CODE, node.rightOperand, []);
+            // only visit the LHS:
             safelyVisit(lhsCondition);
             return null;
           }
         }
       }
     }
     return super.visitBinaryExpression(node);
   }
 
   /**
@@ skipping 20 matching lines @@
     return null;
   }
 
   Object visitConditionalExpression(ConditionalExpression node) {
     Expression conditionExpression = node.condition;
     safelyVisit(conditionExpression);
     if (!isDebugConstant(conditionExpression)) {
       ValidResult result = getConstantBooleanValue(conditionExpression);
       if (result != null) {
         if (result.isTrue) {
+          // report error on else block: true ? 1 : !2!
           _errorReporter.reportError3(HintCode.DEAD_CODE, node.elseExpression, []);
           safelyVisit(node.thenExpression);
           return null;
         } else {
+          // report error on if block: false ? !1! : 2
           _errorReporter.reportError3(HintCode.DEAD_CODE, node.thenExpression, []);
           safelyVisit(node.elseExpression);
           return null;
         }
       }
     }
     return super.visitConditionalExpression(node);
   }
 
   Object visitIfStatement(IfStatement node) {
     Expression conditionExpression = node.condition;
     safelyVisit(conditionExpression);
     if (!isDebugConstant(conditionExpression)) {
       ValidResult result = getConstantBooleanValue(conditionExpression);
       if (result != null) {
         if (result.isTrue) {
+          // report error on else block: if(true) {} else {!}
           Statement elseStatement = node.elseStatement;
           if (elseStatement != null) {
             _errorReporter.reportError3(HintCode.DEAD_CODE, elseStatement, []);
             safelyVisit(node.thenStatement);
             return null;
           }
         } else {
+          // report error on if block: if (false) {!} else {}
           _errorReporter.reportError3(HintCode.DEAD_CODE, node.thenStatement, []);
           safelyVisit(node.elseStatement);
           return null;
         }
       }
     }
     return super.visitIfStatement(node);
   }
 
   Object visitTryStatement(TryStatement node) {
     safelyVisit(node.body);
     safelyVisit(node.finallyBlock);
     NodeList<CatchClause> catchClauses = node.catchClauses;
     int numOfCatchClauses = catchClauses.length;
     List<Type2> visitedTypes = new List<Type2>();
     for (int i = 0; i < numOfCatchClauses; i++) {
       CatchClause catchClause = catchClauses[i];
       if (catchClause.onKeyword != null) {
+        // on-catch clause found, verify that the exception type is not a subtype of a previous
+        // on-catch exception type
         TypeName typeName = catchClause.exceptionType;
         if (typeName != null && typeName.type != null) {
           Type2 currentType = typeName.type;
           if (currentType.isObject) {
+            // Found catch clause clause that has Object as an exception type, this is equivalent to
+            // having a catch clause that doesn't have an exception type, visit the block, but
+            // generate an error on any following catch clauses (and don't visit them).
             safelyVisit(catchClause);
             if (i + 1 != numOfCatchClauses) {
+              // this catch clause is not the last in the try statement
               CatchClause nextCatchClause = catchClauses[i + 1];
               CatchClause lastCatchClause = catchClauses[numOfCatchClauses - 1];
               int offset = nextCatchClause.offset;
               int length = lastCatchClause.end - offset;
               _errorReporter.reportError5(HintCode.DEAD_CODE_CATCH_FOLLOWING_CATCH, offset, length, []);
               return null;
             }
           }
           for (Type2 type in visitedTypes) {
             if (currentType.isSubtypeOf(type)) {
               CatchClause lastCatchClause = catchClauses[numOfCatchClauses - 1];
               int offset = catchClause.offset;
               int length = lastCatchClause.end - offset;
               _errorReporter.reportError5(HintCode.DEAD_CODE_ON_CATCH_SUBTYPE, offset, length, [currentType.displayName, type.displayName]);
               return null;
             }
           }
           visitedTypes.add(currentType);
         }
         safelyVisit(catchClause);
       } else {
+        // Found catch clause clause that doesn't have an exception type, visit the block, but
+        // generate an error on any following catch clauses (and don't visit them).
         safelyVisit(catchClause);
         if (i + 1 != numOfCatchClauses) {
+          // this catch clause is not the last in the try statement
           CatchClause nextCatchClause = catchClauses[i + 1];
           CatchClause lastCatchClause = catchClauses[numOfCatchClauses - 1];
           int offset = nextCatchClause.offset;
           int length = lastCatchClause.end - offset;
           _errorReporter.reportError5(HintCode.DEAD_CODE_CATCH_FOLLOWING_CATCH, offset, length, []);
           return null;
         }
       }
     }
     return null;
   }
 
   Object visitWhileStatement(WhileStatement node) {
     Expression conditionExpression = node.condition;
     safelyVisit(conditionExpression);
     if (!isDebugConstant(conditionExpression)) {
       ValidResult result = getConstantBooleanValue(conditionExpression);
       if (result != null) {
         if (result.isFalse) {
+          // report error on if block: while (false) {!}
           _errorReporter.reportError3(HintCode.DEAD_CODE, node.body, []);
           return null;
         }
       }
     }
     safelyVisit(node.body);
     return null;
   }
 
   /**
    * Given some [Expression], this method returns [ValidResult#RESULT_TRUE] if it is
    * `true`, [ValidResult#RESULT_FALSE] if it is `false`, or `null` if the
    * expression is not a constant boolean value.
    *
    * @param expression the expression to evaluate
    * @return [ValidResult#RESULT_TRUE] if it is `true`, [ValidResult#RESULT_FALSE]
    *         if it is `false`, or `null` if the expression is not a constant boolean
    *         value
    */
   ValidResult getConstantBooleanValue(Expression expression) {
     if (expression is BooleanLiteral) {
       if (expression.value) {
         return new ValidResult(new DartObjectImpl(null, BoolState.from(true)));
       } else {
         return new ValidResult(new DartObjectImpl(null, BoolState.from(false)));
       }
     }
+    // Don't consider situations where we could evaluate to a constant boolean expression with the
+    // ConstantVisitor
+    //    else {
+    //      EvaluationResultImpl result = expression.accept(new ConstantVisitor());
+    //      if (result == ValidResult.RESULT_TRUE) {
+    //        return ValidResult.RESULT_TRUE;
+    //      } else if (result == ValidResult.RESULT_FALSE) {
+    //        return ValidResult.RESULT_FALSE;
+    //      }
+    //      return null;
+    //    }
     return null;
   }
 
   /**
    * Return `true` if and only if the passed expression is resolved to a constant variable.
    *
    * @param expression some conditional expression
    * @return `true` if and only if the passed expression is resolved to a constant variable
    */
   bool isDebugConstant(Expression expression) {
@@ skipping 71 matching lines @@
       _importsVerifier.generateDuplicateImportHints(definingCompilationUnitErrorReporter);
       _importsVerifier.generateUnusedImportHints(definingCompilationUnitErrorReporter);
     } finally {
       timeCounter.stop();
     }
   }
 
   void generateForCompilationUnit(CompilationUnit unit, Source source) {
     ErrorReporter errorReporter = new ErrorReporter(_errorListener, source);
     _importsVerifier.visitCompilationUnit(unit);
+    // dead code analysis
     new DeadCodeVerifier(errorReporter).visitCompilationUnit(unit);
+    // dart2js analysis
     if (_enableDart2JSHints) {
       new Dart2JSVerifier(errorReporter).visitCompilationUnit(unit);
     }
+    // Dart best practices
     new BestPracticesVerifier(errorReporter).visitCompilationUnit(unit);
+    // Find to-do comments
     new ToDoFinder(errorReporter).findIn(unit);
   }
 }
 
 /**
  * Instances of the class `ImportsVerifier` visit all of the referenced libraries in the
  * source code verifying that all of the imports are used, otherwise a
  * [HintCode#UNUSED_IMPORT] is generated with
  * [generateUnusedImportHints].
  *
@@ skipping 91 matching lines @@
   /**
    * After all of the compilation units have been visited by this visitor, this method can be called
    * to report an [HintCode#UNUSED_IMPORT] hint for each of the import directives in the
    * [unusedImports] list.
    *
    * @param errorReporter the error reporter to report the set of [HintCode#UNUSED_IMPORT]
    *          hints to
    */
   void generateUnusedImportHints(ErrorReporter errorReporter) {
     for (ImportDirective unusedImport in _unusedImports) {
+      // Check that the import isn't dart:core
       ImportElement importElement = unusedImport.element;
       if (importElement != null) {
         LibraryElement libraryElement = importElement.importedLibrary;
         if (libraryElement != null && libraryElement.isDartCore) {
           continue;
         }
       }
       errorReporter.reportError3(HintCode.UNUSED_IMPORT, unusedImport.uri, []);
     }
   }
 
   Object visitCompilationUnit(CompilationUnit node) {
     if (_inDefiningCompilationUnit) {
       NodeList<Directive> directives = node.directives;
       for (Directive directive in directives) {
         if (directive is ImportDirective) {
           ImportDirective importDirective = directive;
           LibraryElement libraryElement = importDirective.uriElement;
           if (libraryElement != null) {
             _unusedImports.add(importDirective);
+            //
+            // Initialize prefixElementMap
+            //
             if (importDirective.asToken != null) {
               SimpleIdentifier prefixIdentifier = importDirective.prefix;
               if (prefixIdentifier != null) {
                 Element element = prefixIdentifier.staticElement;
                 if (element is PrefixElement) {
                   PrefixElement prefixElementKey = element;
                   _prefixElementMap[prefixElementKey] = importDirective;
                 }
               }
             }
+            //
+            // Initialize libraryMap: libraryElement -> importDirective
+            //
             putIntoLibraryMap(libraryElement, importDirective);
+            //
+            // For this new addition to the libraryMap, also recursively add any exports from the
+            // libraryElement
+            //
             addAdditionalLibrariesForExports(libraryElement, importDirective, new List<LibraryElement>());
           }
         }
       }
     }
+    // If there are no imports in this library, don't visit the identifiers in the library- there
+    // can be no unused imports.
     if (_unusedImports.isEmpty) {
       return null;
     }
     if (_unusedImports.length > 1) {
+      // order the list of unusedImports to find duplicates in faster than O(n^2) time
       List<ImportDirective> importDirectiveArray = new List.from(_unusedImports);
       importDirectiveArray.sort(ImportDirective.COMPARATOR);
       ImportDirective currentDirective = importDirectiveArray[0];
       for (int i = 1; i < importDirectiveArray.length; i++) {
         ImportDirective nextDirective = importDirectiveArray[i];
         if (ImportDirective.COMPARATOR(currentDirective, nextDirective) == 0) {
+          // Add either the currentDirective or nextDirective depending on which comes second, this
+          // guarantees that the first of the duplicates won't be highlighted.
           if (currentDirective.offset < nextDirective.offset) {
             _duplicateImports.add(nextDirective);
           } else {
             _duplicateImports.add(currentDirective);
           }
         }
         currentDirective = nextDirective;
       }
     }
     return super.visitCompilationUnit(node);
   }
 
   Object visitExportDirective(ExportDirective node) {
     visitMetadata(node.metadata);
     return null;
   }
 
   Object visitImportDirective(ImportDirective node) {
     visitMetadata(node.metadata);
     return null;
   }
 
   Object visitLibraryDirective(LibraryDirective node) {
     visitMetadata(node.metadata);
     return null;
   }
 
   Object visitPrefixedIdentifier(PrefixedIdentifier node) {
+    // If the prefixed identifier references some A.B, where A is a library prefix, then we can
+    // lookup the associated ImportDirective in prefixElementMap and remove it from the
+    // unusedImports list.
     SimpleIdentifier prefixIdentifier = node.prefix;
     Element element = prefixIdentifier.staticElement;
     if (element is PrefixElement) {
       _unusedImports.remove(_prefixElementMap[element]);
       return null;
     }
+    // Otherwise, pass the prefixed identifier element and name onto visitIdentifier.
     return visitIdentifier(element, prefixIdentifier.name);
   }
 
   Object visitSimpleIdentifier(SimpleIdentifier node) => visitIdentifier(node.staticElement, node.name);
 
   void set inDefiningCompilationUnit(bool inDefiningCompilationUnit) {
     this._inDefiningCompilationUnit = inDefiningCompilationUnit;
   }
 
   /**
@@ skipping 14 matching lines @@
    * Lookup and return the [Namespace] from the [namespaceMap], if the map does not
    * have the computed namespace, compute it and cache it in the map. If the import directive is not
    * resolved or is not resolvable, `null` is returned.
    *
    * @param importDirective the import directive used to compute the returned namespace
    * @return the computed or looked up [Namespace]
    */
   Namespace computeNamespace(ImportDirective importDirective) {
     Namespace namespace = _namespaceMap[importDirective];
     if (namespace == null) {
+      // If the namespace isn't in the namespaceMap, then compute and put it in the map
       ImportElement importElement = importDirective.element;
       if (importElement != null) {
         NamespaceBuilder builder = new NamespaceBuilder();
         namespace = builder.createImportNamespace(importElement);
         _namespaceMap[importDirective] = namespace;
       }
     }
     return namespace;
   }
 
   /**
    * The [libraryMap] is a mapping between a library elements and a list of import
    * directives, but when adding these mappings into the [libraryMap], this method can be
    * used to simply add the mapping between the library element an an import directive without
    * needing to check to see if a list needs to be created.
    */
   void putIntoLibraryMap(LibraryElement libraryElement, ImportDirective importDirective) {
     List<ImportDirective> importList = _libraryMap[libraryElement];
     if (importList == null) {
       importList = new List<ImportDirective>();
       _libraryMap[libraryElement] = importList;
     }
     importList.add(importDirective);
   }
 
   Object visitIdentifier(Element element, String name) {
     if (element == null) {
       return null;
     }
+    // If the element is multiply defined then call this method recursively for each of the conflicting elements.
     if (element is MultiplyDefinedElement) {
       MultiplyDefinedElement multiplyDefinedElement = element;
       for (Element elt in multiplyDefinedElement.conflictingElements) {
         visitIdentifier(elt, name);
       }
       return null;
     } else if (element is PrefixElement) {
       _unusedImports.remove(_prefixElementMap[element]);
       return null;
     }
     LibraryElement containingLibrary = element.library;
     if (containingLibrary == null) {
       return null;
     }
+    // If the element is declared in the current library, return.
     if (_currentLibrary == containingLibrary) {
       return null;
     }
     List<ImportDirective> importsFromSameLibrary = _libraryMap[containingLibrary];
     if (importsFromSameLibrary == null) {
       return null;
     }
     if (importsFromSameLibrary.length == 1) {
+      // If there is only one import directive for this library, then it must be the directive that
+      // this element is imported with, remove it from the unusedImports list.
       ImportDirective usedImportDirective = importsFromSameLibrary[0];
       _unusedImports.remove(usedImportDirective);
     } else {
+      // Otherwise, for each of the imported directives, use the namespaceMap to
       for (ImportDirective importDirective in importsFromSameLibrary) {
+        // Get the namespace for this import
         Namespace namespace = computeNamespace(importDirective);
         if (namespace != null && namespace.get(name) != null) {
           _unusedImports.remove(importDirective);
         }
       }
     }
     return null;
   }
 
   /**
@@ skipping 51 matching lines @@
     Source source = getSource(uriLiteral);
     String fullName = getSourceFullName(source);
     if (fullName != null) {
       int pathIndex = 0;
       int fullNameIndex = fullName.length;
       while (pathIndex < path.length && JavaString.startsWithBefore(path, "../", pathIndex)) {
         fullNameIndex = JavaString.lastIndexOf(fullName, '/', fullNameIndex);
         if (fullNameIndex < 4) {
           return false;
         }
+        // Check for "/lib" at a specified place in the fullName
         if (JavaString.startsWithBefore(fullName, "/lib", fullNameIndex - 4)) {
           String relativePubspecPath = path.substring(0, pathIndex + 3) + _PUBSPEC_YAML;
           Source pubspecSource = _context.sourceFactory.resolveUri(source, relativePubspecPath);
           if (pubspecSource != null && pubspecSource.exists()) {
+            // Files inside the lib directory hierarchy should not reference files outside
             _errorReporter.reportError3(PubSuggestionCode.FILE_IMPORT_INSIDE_LIB_REFERENCES_FILE_OUTSIDE, uriLiteral, []);
           }
           return true;
         }
         pathIndex += 3;
       }
     }
     return false;
   }
 
@@ skipping 26 matching lines @@
   bool checkForFileImportOutsideLibReferencesFileInside2(StringLiteral uriLiteral, String path, int pathIndex) {
     Source source = getSource(uriLiteral);
     String relativePubspecPath = path.substring(0, pathIndex) + _PUBSPEC_YAML;
     Source pubspecSource = _context.sourceFactory.resolveUri(source, relativePubspecPath);
     if (pubspecSource == null || !pubspecSource.exists()) {
       return false;
     }
     String fullName = getSourceFullName(source);
     if (fullName != null) {
       if (!fullName.contains("/lib/")) {
+        // Files outside the lib directory hierarchy should not reference files inside
+        // ... use package: url instead
         _errorReporter.reportError3(PubSuggestionCode.FILE_IMPORT_OUTSIDE_LIB_REFERENCES_FILE_INSIDE, uriLiteral, []);
         return true;
       }
     }
     return false;
   }
 
   /**
    * This verifies that the passed package import directive does not contain ".."
    *
    * @param uriLiteral the import URL (not `null`)
    * @param path the path to be validated (not `null`)
    * @return `true` if and only if an error code is generated on the passed node
    * @see PubSuggestionCode.PACKAGE_IMPORT_CONTAINS_DOT_DOT
    */
   bool checkForPackageImportContainsDotDot(StringLiteral uriLiteral, String path) {
     if (path.startsWith("../") || path.contains("/../")) {
+      // Package import should not to contain ".."
       _errorReporter.reportError3(PubSuggestionCode.PACKAGE_IMPORT_CONTAINS_DOT_DOT, uriLiteral, []);
       return true;
     }
     return false;
   }
 
   /**
    * Answer the source associated with the compilation unit containing the given AST node.
    *
    * @param node the node (not `null`)
@@ skipping 1461 matching lines @@
       if (leftHandSide != null) {
         String methodName = operatorType.lexeme;
         Type2 staticType = getStaticType(leftHandSide);
         MethodElement staticMethod = lookUpMethod(leftHandSide, staticType, methodName);
         node.staticElement = staticMethod;
         Type2 propagatedType = getPropagatedType(leftHandSide);
         MethodElement propagatedMethod = lookUpMethod(leftHandSide, propagatedType, methodName);
         node.propagatedElement = propagatedMethod;
         bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticMethod);
         bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedMethod) : false;
+        //
+        // If we are about to generate the hint (propagated version of this warning), then check
+        // that the member is not in a subtype of the propagated type.
+        //
         if (shouldReportMissingMember_propagated) {
           if (memberFoundInSubclass(propagatedType.element, methodName, true, false)) {
             shouldReportMissingMember_propagated = false;
           }
         }
         if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
           ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_METHOD : HintCode.UNDEFINED_METHOD) as ErrorCode;
           _resolver.reportErrorProxyConditionalAnalysisError3(shouldReportMissingMember_static ? staticType.element : propagatedType.element, errorCode, operator, [
               methodName,
               shouldReportMissingMember_static ? staticType.displayName : propagatedType.displayName]);
@@ skipping 10 matching lines @@
       if (leftOperand != null) {
         String methodName = operator.lexeme;
         Type2 staticType = getStaticType(leftOperand);
         MethodElement staticMethod = lookUpMethod(leftOperand, staticType, methodName);
         node.staticElement = staticMethod;
         Type2 propagatedType = getPropagatedType(leftOperand);
         MethodElement propagatedMethod = lookUpMethod(leftOperand, propagatedType, methodName);
         node.propagatedElement = propagatedMethod;
         bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticMethod);
         bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedMethod) : false;
+        //
+        // If we are about to generate the hint (propagated version of this warning), then check
+        // that the member is not in a subtype of the propagated type.
+        //
         if (shouldReportMissingMember_propagated) {
           if (memberFoundInSubclass(propagatedType.element, methodName, true, false)) {
             shouldReportMissingMember_propagated = false;
           }
         }
         if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
           ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_OPERATOR : HintCode.UNDEFINED_OPERATOR) as ErrorCode;
           _resolver.reportErrorProxyConditionalAnalysisError3(shouldReportMissingMember_static ? staticType.element : propagatedType.element, errorCode, operator, [
               methodName,
               shouldReportMissingMember_static ? staticType.displayName : propagatedType.displayName]);
@@ skipping 21 matching lines @@
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitCommentReference(CommentReference node) {
     Identifier identifier = node.identifier;
     if (identifier is SimpleIdentifier) {
       SimpleIdentifier simpleIdentifier = identifier;
       Element element = resolveSimpleIdentifier(simpleIdentifier);
       if (element == null) {
+        //
+        // This might be a reference to an imported name that is missing the prefix.
+        //
         element = findImportWithoutPrefix(simpleIdentifier);
         if (element is MultiplyDefinedElement) {
+          // TODO(brianwilkerson) Report this error?
           element = null;
         }
       }
       if (element == null) {
       } else {
         if (element.library == null || element.library != _definingLibrary) {
         }
         simpleIdentifier.staticElement = element;
         if (node.newKeyword != null) {
           if (element is ClassElement) {
             ConstructorElement constructor = (element as ClassElement).unnamedConstructor;
             if (constructor == null) {
             } else {
               simpleIdentifier.staticElement = constructor;
             }
           } else {
           }
         }
       }
     } else if (identifier is PrefixedIdentifier) {
       PrefixedIdentifier prefixedIdentifier = identifier;
       SimpleIdentifier prefix = prefixedIdentifier.prefix;
       SimpleIdentifier name = prefixedIdentifier.identifier;
       Element element = resolveSimpleIdentifier(prefix);
       if (element == null) {
       } else {
         if (element is PrefixElement) {
           prefix.staticElement = element;
+          // TODO(brianwilkerson) Report this error?
           element = _resolver.nameScope.lookup(identifier, _definingLibrary);
           name.staticElement = element;
           return null;
         }
         LibraryElement library = element.library;
         if (library == null) {
+          // TODO(brianwilkerson) We need to understand how the library could ever be null.
           AnalysisEngine.instance.logger.logError("Found element with null library: ${element.name}");
         } else if (library != _definingLibrary) {
         }
         name.staticElement = element;
         if (node.newKeyword == null) {
           if (element is ClassElement) {
             Element memberElement = lookupGetterOrMethod((element as ClassElement).type, name.name);
             if (memberElement == null) {
               memberElement = (element as ClassElement).getNamedConstructor(name.name);
               if (memberElement == null) {
@@ skipping 19 matching lines @@
       }
     }
     return null;
   }
 
   Object visitConstructorDeclaration(ConstructorDeclaration node) {
     super.visitConstructorDeclaration(node);
     ConstructorElement element = node.element;
     if (element is ConstructorElementImpl) {
       ConstructorElementImpl constructorElement = element;
+      // set redirected factory constructor
       ConstructorName redirectedNode = node.redirectedConstructor;
       if (redirectedNode != null) {
         ConstructorElement redirectedElement = redirectedNode.staticElement;
         constructorElement.redirectedConstructor = redirectedElement;
       }
+      // set redirected generate constructor
       for (ConstructorInitializer initializer in node.initializers) {
         if (initializer is RedirectingConstructorInvocation) {
           ConstructorElement redirectedElement = initializer.staticElement;
           constructorElement.redirectedConstructor = redirectedElement;
         }
       }
       setMetadata(constructorElement, node);
     }
     return null;
   }
 
   Object visitConstructorFieldInitializer(ConstructorFieldInitializer node) {
     SimpleIdentifier fieldName = node.fieldName;
     ClassElement enclosingClass = _resolver.enclosingClass;
     FieldElement fieldElement = enclosingClass.getField(fieldName.name);
     fieldName.staticElement = fieldElement;
     if (fieldElement == null || fieldElement.isSynthetic) {
       _resolver.reportError7(CompileTimeErrorCode.INITIALIZER_FOR_NON_EXISTANT_FIELD, node, [fieldName]);
     } else if (fieldElement.isStatic) {
       _resolver.reportError7(CompileTimeErrorCode.INITIALIZER_FOR_STATIC_FIELD, node, [fieldName]);
     }
     return null;
   }
 
   Object visitConstructorName(ConstructorName node) {
     Type2 type = node.type.type;
     if (type != null && type.isDynamic) {
       return null;
     } else if (type is! InterfaceType) {
+      // TODO(brianwilkerson) Report these errors.
       ASTNode parent = node.parent;
       if (parent is InstanceCreationExpression) {
         if (parent.isConst) {
         } else {
         }
       } else {
       }
       return null;
     }
+    // look up ConstructorElement
     ConstructorElement constructor;
     SimpleIdentifier name = node.name;
     InterfaceType interfaceType = type as InterfaceType;
     if (name == null) {
       constructor = interfaceType.lookUpConstructor(null, _definingLibrary);
     } else {
       constructor = interfaceType.lookUpConstructor(name.name, _definingLibrary);
       name.staticElement = constructor;
     }
     node.staticElement = constructor;
@@ skipping 10 matching lines @@
   }
 
   Object visitDeclaredIdentifier(DeclaredIdentifier node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitExportDirective(ExportDirective node) {
     Element element = node.element;
     if (element is ExportElement) {
+      // The element is null when the URI is invalid
+      // TODO(brianwilkerson) Figure out whether the element can ever be something other than an
+      // ExportElement
       resolveCombinators(element.exportedLibrary, node.combinators);
       setMetadata(element, node);
     }
     return null;
   }
 
   Object visitFieldFormalParameter(FieldFormalParameter node) {
     String fieldName = node.identifier.name;
     ClassElement classElement = _resolver.enclosingClass;
     if (classElement != null) {
       FieldElement fieldElement = classElement.getField(fieldName);
       if (fieldElement == null) {
         _resolver.reportError7(CompileTimeErrorCode.INITIALIZING_FORMAL_FOR_NON_EXISTANT_FIELD, node, [fieldName]);
       } else {
         ParameterElement parameterElement = node.element;
         if (parameterElement is FieldFormalParameterElementImpl) {
           FieldFormalParameterElementImpl fieldFormal = parameterElement;
           fieldFormal.field = fieldElement;
           Type2 declaredType = fieldFormal.type;
           Type2 fieldType = fieldElement.type;
           if (node.type == null) {
             fieldFormal.type = fieldType;
           }
           if (fieldElement.isSynthetic) {
             _resolver.reportError7(CompileTimeErrorCode.INITIALIZING_FORMAL_FOR_NON_EXISTANT_FIELD, node, [fieldName]);
           } else if (fieldElement.isStatic) {
             _resolver.reportError7(CompileTimeErrorCode.INITIALIZING_FORMAL_FOR_STATIC_FIELD, node, [fieldName]);
           } else if (declaredType != null && fieldType != null && !declaredType.isAssignableTo(fieldType)) {
+            // TODO(brianwilkerson) We should implement a displayName() method for types that will
+            // work nicely with function types and then use that below.
             _resolver.reportError7(StaticWarningCode.FIELD_INITIALIZING_FORMAL_NOT_ASSIGNABLE, node, [declaredType.displayName, fieldType.displayName]);
           }
         } else {
           if (fieldElement.isSynthetic) {
             _resolver.reportError7(CompileTimeErrorCode.INITIALIZING_FORMAL_FOR_NON_EXISTANT_FIELD, node, [fieldName]);
           } else if (fieldElement.isStatic) {
             _resolver.reportError7(CompileTimeErrorCode.INITIALIZING_FORMAL_FOR_STATIC_FIELD, node, [fieldName]);
           }
         }
       }
     }
+    //    else {
+    //    // TODO(jwren) Report error, constructor initializer variable is a top level element
+    //    // (Either here or in ErrorVerifier#checkForAllFinalInitializedErrorCodes)
+    //    }
     return super.visitFieldFormalParameter(node);
   }
 
   Object visitFunctionDeclaration(FunctionDeclaration node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitFunctionExpressionInvocation(FunctionExpressionInvocation node) {
+    // TODO(brianwilkerson) Can we ever resolve the function being invoked?
     Expression expression = node.function;
     if (expression is FunctionExpression) {
       FunctionExpression functionExpression = expression;
       ExecutableElement functionElement = functionExpression.element;
       ArgumentList argumentList = node.argumentList;
       List<ParameterElement> parameters = resolveArgumentsToParameters(false, argumentList, functionElement);
       if (parameters != null) {
         argumentList.correspondingStaticParameters = parameters;
       }
     }
@@ skipping 11 matching lines @@
       String prefixName = prefixNode.name;
       for (PrefixElement prefixElement in _definingLibrary.prefixes) {
         if (prefixElement.displayName == prefixName) {
           prefixNode.staticElement = prefixElement;
           break;
         }
       }
     }
     ImportElement importElement = node.element;
     if (importElement != null) {
+      // The element is null when the URI is invalid
       LibraryElement library = importElement.importedLibrary;
       if (library != null) {
         resolveCombinators(library, node.combinators);
       }
       setMetadata(importElement, node);
     }
     return null;
   }
 
   Object visitIndexExpression(IndexExpression node) {
     Expression target = node.realTarget;
     Type2 staticType = getStaticType(target);
     Type2 propagatedType = getPropagatedType(target);
     String getterMethodName = sc.TokenType.INDEX.lexeme;
     String setterMethodName = sc.TokenType.INDEX_EQ.lexeme;
     bool isInGetterContext = node.inGetterContext();
     bool isInSetterContext = node.inSetterContext();
     if (isInGetterContext && isInSetterContext) {
+      // lookup setter
       MethodElement setterStaticMethod = lookUpMethod(target, staticType, setterMethodName);
       MethodElement setterPropagatedMethod = lookUpMethod(target, propagatedType, setterMethodName);
+      // set setter element
       node.staticElement = setterStaticMethod;
       node.propagatedElement = setterPropagatedMethod;
+      // generate undefined method warning
       checkForUndefinedIndexOperator(node, target, getterMethodName, setterStaticMethod, setterPropagatedMethod, staticType, propagatedType);
+      // lookup getter method
       MethodElement getterStaticMethod = lookUpMethod(target, staticType, getterMethodName);
       MethodElement getterPropagatedMethod = lookUpMethod(target, propagatedType, getterMethodName);
+      // set getter element
       AuxiliaryElements auxiliaryElements = new AuxiliaryElements(getterStaticMethod, getterPropagatedMethod);
       node.auxiliaryElements = auxiliaryElements;
+      // generate undefined method warning
       checkForUndefinedIndexOperator(node, target, getterMethodName, getterStaticMethod, getterPropagatedMethod, staticType, propagatedType);
     } else if (isInGetterContext) {
+      // lookup getter method
       MethodElement staticMethod = lookUpMethod(target, staticType, getterMethodName);
       MethodElement propagatedMethod = lookUpMethod(target, propagatedType, getterMethodName);
+      // set getter element
       node.staticElement = staticMethod;
       node.propagatedElement = propagatedMethod;
+      // generate undefined method warning
       checkForUndefinedIndexOperator(node, target, getterMethodName, staticMethod, propagatedMethod, staticType, propagatedType);
     } else if (isInSetterContext) {
+      // lookup setter method
       MethodElement staticMethod = lookUpMethod(target, staticType, setterMethodName);
       MethodElement propagatedMethod = lookUpMethod(target, propagatedType, setterMethodName);
+      // set setter element
       node.staticElement = staticMethod;
       node.propagatedElement = propagatedMethod;
+      // generate undefined method warning
       checkForUndefinedIndexOperator(node, target, setterMethodName, staticMethod, propagatedMethod, staticType, propagatedType);
     }
     return null;
   }
 
   Object visitInstanceCreationExpression(InstanceCreationExpression node) {
     ConstructorElement invokedConstructor = node.constructorName.staticElement;
     node.staticElement = invokedConstructor;
     ArgumentList argumentList = node.argumentList;
     List<ParameterElement> parameters = resolveArgumentsToParameters(node.isConst, argumentList, invokedConstructor);
     if (parameters != null) {
       argumentList.correspondingStaticParameters = parameters;
     }
     return null;
   }
 
   Object visitLibraryDirective(LibraryDirective node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitMethodDeclaration(MethodDeclaration node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitMethodInvocation(MethodInvocation node) {
     SimpleIdentifier methodName = node.methodName;
+    //
+    // Synthetic identifiers have been already reported during parsing.
+    //
     if (methodName.isSynthetic) {
       return null;
     }
+    //
+    // We have a method invocation of one of two forms: 'e.m(a1, ..., an)' or 'm(a1, ..., an)'. The
+    // first step is to figure out which executable is being invoked, using both the static and the
+    // propagated type information.
+    //
     Expression target = node.realTarget;
     if (target is SuperExpression && !isSuperInValidContext(target)) {
       return null;
     }
     Element staticElement;
     Element propagatedElement;
     if (target == null) {
       staticElement = resolveInvokedElement2(methodName);
       propagatedElement = null;
     } else {
       Type2 staticType = getStaticType(target);
+      //
+      // If this method invocation is of the form 'C.m' where 'C' is a class, then we don't call
+      // resolveInvokedElement(..) which walks up the class hierarchy, instead we just look for the
+      // member in the type only.
+      //
       ClassElementImpl typeReference = getTypeReference(target);
       if (typeReference != null) {
         staticElement = propagatedElement = resolveElement(typeReference, methodName);
       } else {
         staticElement = resolveInvokedElement(target, staticType, methodName);
         propagatedElement = resolveInvokedElement(target, getPropagatedType(target), methodName);
       }
     }
     staticElement = convertSetterToGetter(staticElement);
     propagatedElement = convertSetterToGetter(propagatedElement);
+    //
+    // Record the results.
+    //
     methodName.staticElement = staticElement;
     methodName.propagatedElement = propagatedElement;
     ArgumentList argumentList = node.argumentList;
     if (staticElement != null) {
       List<ParameterElement> parameters = computeCorrespondingParameters(argumentList, staticElement);
       if (parameters != null) {
         argumentList.correspondingStaticParameters = parameters;
       }
     }
     if (propagatedElement != null) {
       List<ParameterElement> parameters = computeCorrespondingParameters(argumentList, propagatedElement);
       if (parameters != null) {
         argumentList.correspondingPropagatedParameters = parameters;
       }
     }
+    //
+    // Then check for error conditions.
+    //
     ErrorCode errorCode = checkForInvocationError(target, true, staticElement);
     bool generatedWithTypePropagation = false;
     if (_enableHints && errorCode == null && staticElement == null) {
       errorCode = checkForInvocationError(target, false, propagatedElement);
       if (identical(errorCode, StaticTypeWarningCode.UNDEFINED_METHOD)) {
         ClassElement classElementContext = null;
         if (target == null) {
           classElementContext = _resolver.enclosingClass;
         } else {
           Type2 type = target.bestType;
@@ skipping 23 matching lines @@
     } else if (identical(errorCode, CompileTimeErrorCode.UNDEFINED_FUNCTION)) {
       _resolver.reportError7(CompileTimeErrorCode.UNDEFINED_FUNCTION, methodName, [methodName.name]);
     } else if (identical(errorCode, StaticTypeWarningCode.UNDEFINED_METHOD)) {
       String targetTypeName;
       if (target == null) {
         ClassElement enclosingClass = _resolver.enclosingClass;
         targetTypeName = enclosingClass.displayName;
         ErrorCode proxyErrorCode = (generatedWithTypePropagation ? HintCode.UNDEFINED_METHOD : StaticTypeWarningCode.UNDEFINED_METHOD) as ErrorCode;
         _resolver.reportErrorProxyConditionalAnalysisError(_resolver.enclosingClass, proxyErrorCode, methodName, [methodName.name, targetTypeName]);
       } else {
+        // ignore Function "call"
+        // (if we are about to create a hint using type propagation, then we can use type
+        // propagation here as well)
         Type2 targetType = null;
         if (!generatedWithTypePropagation) {
           targetType = getStaticType(target);
         } else {
+          // choose the best type
           targetType = getPropagatedType(target);
           if (targetType == null) {
             targetType = getStaticType(target);
           }
         }
         if (targetType != null && targetType.isDartCoreFunction && methodName.name == CALL_METHOD_NAME) {
+          // TODO(brianwilkerson) Can we ever resolve the function being invoked?
+          //resolveArgumentsToParameters(node.getArgumentList(), invokedFunction);
           return null;
         }
         targetTypeName = targetType == null ? null : targetType.displayName;
         ErrorCode proxyErrorCode = (generatedWithTypePropagation ? HintCode.UNDEFINED_METHOD : StaticTypeWarningCode.UNDEFINED_METHOD) as ErrorCode;
         _resolver.reportErrorProxyConditionalAnalysisError(targetType.element, proxyErrorCode, methodName, [methodName.name, targetTypeName]);
       }
     } else if (identical(errorCode, StaticTypeWarningCode.UNDEFINED_SUPER_METHOD)) {
+      // Generate the type name.
+      // The error code will never be generated via type propagation
       Type2 targetType = getStaticType(target);
       String targetTypeName = targetType == null ? null : targetType.name;
       _resolver.reportError7(StaticTypeWarningCode.UNDEFINED_SUPER_METHOD, methodName, [methodName.name, targetTypeName]);
     }
     return null;
   }
 
   Object visitPartDirective(PartDirective node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitPartOfDirective(PartOfDirective node) {
     setMetadata(node.element, node);
     return null;
   }
 
   Object visitPostfixExpression(PostfixExpression node) {
     Expression operand = node.operand;
     String methodName = getPostfixOperator(node);
     Type2 staticType = getStaticType(operand);
     MethodElement staticMethod = lookUpMethod(operand, staticType, methodName);
     node.staticElement = staticMethod;
     Type2 propagatedType = getPropagatedType(operand);
     MethodElement propagatedMethod = lookUpMethod(operand, propagatedType, methodName);
     node.propagatedElement = propagatedMethod;
     bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticMethod);
     bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedMethod) : false;
+    //
+    // If we are about to generate the hint (propagated version of this warning), then check
+    // that the member is not in a subtype of the propagated type.
+    //
     if (shouldReportMissingMember_propagated) {
       if (memberFoundInSubclass(propagatedType.element, methodName, true, false)) {
         shouldReportMissingMember_propagated = false;
       }
     }
     if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
       ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_OPERATOR : HintCode.UNDEFINED_OPERATOR) as ErrorCode;
       _resolver.reportErrorProxyConditionalAnalysisError3(shouldReportMissingMember_static ? staticType.element : propagatedType.element, errorCode, node.operator, [
           methodName,
           shouldReportMissingMember_static ? staticType.displayName : propagatedType.displayName]);
     }
     return null;
   }
 
   Object visitPrefixedIdentifier(PrefixedIdentifier node) {
     SimpleIdentifier prefix = node.prefix;
     SimpleIdentifier identifier = node.identifier;
+    //
+    // First, check to see whether the prefix is really a prefix.
+    //
     Element prefixElement = prefix.staticElement;
     if (prefixElement is PrefixElement) {
       Element element = _resolver.nameScope.lookup(node, _definingLibrary);
       if (element == null && identifier.inSetterContext()) {
         element = _resolver.nameScope.lookup(new ElementResolver_SyntheticIdentifier("${node.name}="), _definingLibrary);
       }
       if (element == null) {
         if (identifier.inSetterContext()) {
           _resolver.reportError7(StaticWarningCode.UNDEFINED_SETTER, identifier, [identifier.name, prefixElement.name]);
         } else if (node.parent is Annotation) {
           Annotation annotation = node.parent as Annotation;
           _resolver.reportError7(CompileTimeErrorCode.INVALID_ANNOTATION, annotation, []);
           return null;
         } else {
           _resolver.reportError7(StaticWarningCode.UNDEFINED_GETTER, identifier, [identifier.name, prefixElement.name]);
         }
         return null;
       }
       if (element is PropertyAccessorElement && identifier.inSetterContext()) {
         PropertyInducingElement variable = (element as PropertyAccessorElement).variable;
         if (variable != null) {
           PropertyAccessorElement setter = variable.setter;
           if (setter != null) {
             element = setter;
           }
         }
       }
+      // TODO(brianwilkerson) The prefix needs to be resolved to the element for the import that
+      // defines the prefix, not the prefix's element.
       identifier.staticElement = element;
+      // Validate annotation element.
       if (node.parent is Annotation) {
         Annotation annotation = node.parent as Annotation;
         resolveAnnotationElement(annotation);
         return null;
       }
       return null;
     }
+    // May be annotation, resolve invocation of "const" constructor.
     if (node.parent is Annotation) {
       Annotation annotation = node.parent as Annotation;
       resolveAnnotationElement(annotation);
     }
+    //
+    // Otherwise, the prefix is really an expression that happens to be a simple identifier and this
+    // is really equivalent to a property access node.
+    //
     resolvePropertyAccess(prefix, identifier);
     return null;
   }
 
   Object visitPrefixExpression(PrefixExpression node) {
     sc.Token operator = node.operator;
     sc.TokenType operatorType = operator.type;
     if (operatorType.isUserDefinableOperator || identical(operatorType, sc.TokenType.PLUS_PLUS) || identical(operatorType, sc.TokenType.MINUS_MINUS)) {
       Expression operand = node.operand;
       String methodName = getPrefixOperator(node);
       Type2 staticType = getStaticType(operand);
       MethodElement staticMethod = lookUpMethod(operand, staticType, methodName);
       node.staticElement = staticMethod;
       Type2 propagatedType = getPropagatedType(operand);
       MethodElement propagatedMethod = lookUpMethod(operand, propagatedType, methodName);
       node.propagatedElement = propagatedMethod;
       bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticMethod);
       bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedMethod) : false;
+      //
+      // If we are about to generate the hint (propagated version of this warning), then check
+      // that the member is not in a subtype of the propagated type.
+      //
       if (shouldReportMissingMember_propagated) {
         if (memberFoundInSubclass(propagatedType.element, methodName, true, false)) {
           shouldReportMissingMember_propagated = false;
         }
       }
       if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
         ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_OPERATOR : HintCode.UNDEFINED_OPERATOR) as ErrorCode;
         _resolver.reportErrorProxyConditionalAnalysisError3(shouldReportMissingMember_static ? staticType.element : propagatedType.element, errorCode, operator, [
             methodName,
             shouldReportMissingMember_static ? staticType.displayName : propagatedType.displayName]);
       }
     }
     return null;
   }
 
   Object visitPropertyAccess(PropertyAccess node) {
     Expression target = node.realTarget;
     if (target is SuperExpression && !isSuperInValidContext(target)) {
       return null;
     }
     SimpleIdentifier propertyName = node.propertyName;
     resolvePropertyAccess(target, propertyName);
     return null;
   }
 
   Object visitRedirectingConstructorInvocation(RedirectingConstructorInvocation node) {
     ClassElement enclosingClass = _resolver.enclosingClass;
     if (enclosingClass == null) {
+      // TODO(brianwilkerson) Report this error.
       return null;
     }
     SimpleIdentifier name = node.constructorName;
     ConstructorElement element;
     if (name == null) {
       element = enclosingClass.unnamedConstructor;
     } else {
       element = enclosingClass.getNamedConstructor(name.name);
     }
     if (element == null) {
+      // TODO(brianwilkerson) Report this error and decide what element to associate with the node.
       return null;
     }
     if (name != null) {
       name.staticElement = element;
     }
     node.staticElement = element;
     ArgumentList argumentList = node.argumentList;
     List<ParameterElement> parameters = resolveArgumentsToParameters(false, argumentList, element);
     if (parameters != null) {
       argumentList.correspondingStaticParameters = parameters;
     }
     return null;
   }
 
   Object visitSimpleIdentifier(SimpleIdentifier node) {
+    //
+    // Synthetic identifiers have been already reported during parsing.
+    //
     if (node.isSynthetic) {
       return null;
     }
+    //
+    // We ignore identifiers that have already been resolved, such as identifiers representing the
+    // name in a declaration.
+    //
     if (node.staticElement != null) {
       return null;
     }
+    //
+    // The name dynamic denotes a Type object even though dynamic is not a class.
+    //
     if (node.name == _dynamicType.name) {
       node.staticElement = _dynamicType.element;
       node.staticType = _typeType;
       return null;
     }
+    //
+    // Otherwise, the node should be resolved.
+    //
     Element element = resolveSimpleIdentifier(node);
     ClassElement enclosingClass = _resolver.enclosingClass;
     if (isFactoryConstructorReturnType(node) && element != enclosingClass) {
       _resolver.reportError7(CompileTimeErrorCode.INVALID_FACTORY_NAME_NOT_A_CLASS, node, []);
     } else if (isConstructorReturnType(node) && element != enclosingClass) {
       _resolver.reportError7(CompileTimeErrorCode.INVALID_CONSTRUCTOR_NAME, node, []);
       element = null;
     } else if (element == null || (element is PrefixElement && !isValidAsPrefix(node))) {
+      // TODO(brianwilkerson) Recover from this error.
       if (isConstructorReturnType(node)) {
         _resolver.reportError7(CompileTimeErrorCode.INVALID_CONSTRUCTOR_NAME, node, []);
       } else if (node.parent is Annotation) {
         Annotation annotation = node.parent as Annotation;
         _resolver.reportError7(CompileTimeErrorCode.INVALID_ANNOTATION, annotation, []);
       } else {
         _resolver.reportErrorProxyConditionalAnalysisError(_resolver.enclosingClass, StaticWarningCode.UNDEFINED_IDENTIFIER, node, [node.name]);
       }
     }
     node.staticElement = element;
     if (node.inSetterContext() && node.inGetterContext() && enclosingClass != null) {
       InterfaceType enclosingType = enclosingClass.type;
       AuxiliaryElements auxiliaryElements = new AuxiliaryElements(lookUpGetter(null, enclosingType, node.name), null);
       node.auxiliaryElements = auxiliaryElements;
     }
+    //
+    // Validate annotation element.
+    //
     if (node.parent is Annotation) {
       Annotation annotation = node.parent as Annotation;
       resolveAnnotationElement(annotation);
     }
     return null;
   }
 
   Object visitSuperConstructorInvocation(SuperConstructorInvocation node) {
     ClassElement enclosingClass = _resolver.enclosingClass;
     if (enclosingClass == null) {
+      // TODO(brianwilkerson) Report this error.
       return null;
     }
     InterfaceType superType = enclosingClass.supertype;
     if (superType == null) {
+      // TODO(brianwilkerson) Report this error.
       return null;
     }
     SimpleIdentifier name = node.constructorName;
     String superName = name != null ? name.name : null;
     ConstructorElement element = superType.lookUpConstructor(superName, _definingLibrary);
     if (element == null) {
       if (name != null) {
         _resolver.reportError7(CompileTimeErrorCode.UNDEFINED_CONSTRUCTOR_IN_INITIALIZER, node, [superType.displayName, name]);
       } else {
         _resolver.reportError7(CompileTimeErrorCode.UNDEFINED_CONSTRUCTOR_IN_INITIALIZER_DEFAULT, node, [superType.displayName]);
@@ skipping 60 matching lines @@
   /**
    * Given that we have found code to invoke the given element, return the error code that should be
    * reported, or `null` if no error should be reported.
    *
    * @param target the target of the invocation, or `null` if there was no target
    * @param useStaticContext
    * @param element the element to be invoked
    * @return the error code that should be reported
    */
   ErrorCode checkForInvocationError(Expression target, bool useStaticContext, Element element) {
+    // Prefix is not declared, instead "prefix.id" are declared.
     if (element is PrefixElement) {
       element = null;
     }
     if (element is PropertyAccessorElement) {
+      //
+      // This is really a function expression invocation.
+      //
+      // TODO(brianwilkerson) Consider the possibility of re-writing the AST.
       FunctionType getterType = element.type;
       if (getterType != null) {
         Type2 returnType = getterType.returnType;
         if (!isExecutableType(returnType)) {
           return StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION;
         }
       }
     } else if (element is ExecutableElement) {
       return null;
     } else if (element == null && target is SuperExpression) {
+      // TODO(jwren) We should split the UNDEFINED_METHOD into two error codes, this one, and
+      // a code that describes the situation where the method was found, but it was not
+      // accessible from the current library.
       return StaticTypeWarningCode.UNDEFINED_SUPER_METHOD;
     } else {
+      //
+      // This is really a function expression invocation.
+      //
+      // TODO(brianwilkerson) Consider the possibility of re-writing the AST.
       if (element is PropertyInducingElement) {
         PropertyAccessorElement getter = element.getter;
         FunctionType getterType = getter.type;
         if (getterType != null) {
           Type2 returnType = getterType.returnType;
           if (!isExecutableType(returnType)) {
             return StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION;
           }
         }
       } else if (element is VariableElement) {
         Type2 variableType = element.type;
         if (!isExecutableType(variableType)) {
           return StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION;
         }
       } else {
         if (target == null) {
           ClassElement enclosingClass = _resolver.enclosingClass;
           if (enclosingClass == null) {
             return CompileTimeErrorCode.UNDEFINED_FUNCTION;
           } else if (element == null) {
+            // Proxy-conditional warning, based on state of resolver.getEnclosingClass()
             return StaticTypeWarningCode.UNDEFINED_METHOD;
           } else {
             return StaticTypeWarningCode.INVOCATION_OF_NON_FUNCTION;
           }
         } else {
           Type2 targetType;
           if (useStaticContext) {
             targetType = getStaticType(target);
           } else {
+            // Compute and use the propagated type, if it is null, then it may be the case that
+            // static type is some type, in which the static type should be used.
             targetType = target.bestType;
           }
           if (targetType == null) {
             return CompileTimeErrorCode.UNDEFINED_FUNCTION;
           } else if (!targetType.isDynamic && !targetType.isBottom) {
+            // Proxy-conditional warning, based on state of targetType.getElement()
             return StaticTypeWarningCode.UNDEFINED_METHOD;
           }
         }
       }
     }
     return null;
   }
 
   /**
    * Check that the for some index expression that the method element was resolved, otherwise a
    * [StaticWarningCode#UNDEFINED_OPERATOR] is generated.
    *
    * @param node the index expression to resolve
    * @param target the target of the expression
    * @param methodName the name of the operator associated with the context of using of the given
    *          index expression
    * @return `true` if and only if an error code is generated on the passed node
    */
   bool checkForUndefinedIndexOperator(IndexExpression node, Expression target, String methodName, MethodElement staticMethod, MethodElement propagatedMethod, Type2 staticType, Type2 propagatedType) {
     bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticMethod);
     bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedMethod) : false;
+    //
+    // If we are about to generate the hint (propagated version of this warning), then check
+    // that the member is not in a subtype of the propagated type.
+    //
     if (shouldReportMissingMember_propagated) {
       if (memberFoundInSubclass(propagatedType.element, methodName, true, false)) {
         shouldReportMissingMember_propagated = false;
       }
     }
     if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
       sc.Token leftBracket = node.leftBracket;
       sc.Token rightBracket = node.rightBracket;
       ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_OPERATOR : HintCode.UNDEFINED_OPERATOR) as ErrorCode;
       if (leftBracket == null || rightBracket == null) {
@@ skipping 16 matching lines @@
    * Given a list of arguments and the element that will be invoked using those argument, compute
    * the list of parameters that correspond to the list of arguments. Return the parameters that
    * correspond to the arguments, or `null` if no correspondence could be computed.
    *
    * @param argumentList the list of arguments being passed to the element
    * @param executableElement the element that will be invoked with the arguments
    * @return the parameters that correspond to the arguments
    */
   List<ParameterElement> computeCorrespondingParameters(ArgumentList argumentList, Element element) {
     if (element is PropertyAccessorElement) {
+      //
+      // This is an invocation of the call method defined on the value returned by the getter.
+      //
       FunctionType getterType = element.type;
       if (getterType != null) {
         Type2 getterReturnType = getterType.returnType;
         if (getterReturnType is InterfaceType) {
           MethodElement callMethod = getterReturnType.lookUpMethod(CALL_METHOD_NAME, _definingLibrary);
           if (callMethod != null) {
             return resolveArgumentsToParameters(false, argumentList, callMethod);
           }
         } else if (getterReturnType is FunctionType) {
           Element functionElement = getterReturnType.element;
           if (functionElement is ExecutableElement) {
             return resolveArgumentsToParameters(false, argumentList, functionElement);
           }
         }
       }
     } else if (element is ExecutableElement) {
       return resolveArgumentsToParameters(false, argumentList, element);
     } else if (element is VariableElement) {
       VariableElement variable = element;
       Type2 type = _promoteManager.getStaticType(variable);
       if (type is FunctionType) {
         FunctionType functionType = type;
         List<ParameterElement> parameters = functionType.parameters;
         return resolveArgumentsToParameters2(false, argumentList, parameters);
       } else if (type is InterfaceType) {
+        // "call" invocation
         MethodElement callMethod = type.lookUpMethod(CALL_METHOD_NAME, _definingLibrary);
         if (callMethod != null) {
           List<ParameterElement> parameters = callMethod.parameters;
           return resolveArgumentsToParameters2(false, argumentList, parameters);
         }
       }
     }
     return null;
   }
 
   /**
    * If the given element is a setter, return the getter associated with it. Otherwise, return the
    * element unchanged.
    *
    * @param element the element to be normalized
    * @return a non-setter element derived from the given element
    */
   Element convertSetterToGetter(Element element) {
+    // TODO(brianwilkerson) Determine whether and why the element could ever be a setter.
     if (element is PropertyAccessorElement) {
       return element.variable.getter;
     }
     return element;
   }
 
   /**
    * Look for any declarations of the given identifier that are imported using a prefix. Return the
    * element that was found, or `null` if the name is not imported using a prefix.
    *
@@ skipping 50 matching lines @@
 
   /**
    * Return the propagated type of the given expression that is to be used for type analysis.
    *
    * @param expression the expression whose type is to be returned
    * @return the type of the given expression
    */
   Type2 getPropagatedType(Expression expression) {
     Type2 propagatedType = resolveTypeParameter(expression.propagatedType);
     if (propagatedType is FunctionType) {
+      //
+      // All function types are subtypes of 'Function', which is itself a subclass of 'Object'.
+      //
       propagatedType = _resolver.typeProvider.functionType;
     }
     return propagatedType;
   }
 
   /**
    * Return the static type of the given expression that is to be used for type analysis.
    *
    * @param expression the expression whose type is to be returned
    * @return the type of the given expression
    */
   Type2 getStaticType(Expression expression) {
     if (expression is NullLiteral) {
       return _resolver.typeProvider.bottomType;
     }
     Type2 staticType = resolveTypeParameter(expression.staticType);
     if (staticType is FunctionType) {
+      //
+      // All function types are subtypes of 'Function', which is itself a subclass of 'Object'.
+      //
       staticType = _resolver.typeProvider.functionType;
     }
     return staticType;
   }
 
   /**
    * Return `true` if the given type represents an object that could be invoked using the call
    * operator '()'.
    *
    * @param type the type being tested
@@ skipping 91 matching lines @@
    * `null` if there is no getter with the given name.
    *
    * @param targetType the type in which the getter might be defined
    * @param includeTargetType `true` if the search should include the target type
    * @param getterName the name of the getter being looked up
    * @param visitedInterfaces a set containing all of the interfaces that have been examined, used
    *          to prevent infinite recursion and to optimize the search
    * @return the element representing the getter that was found
    */
   PropertyAccessorElement lookUpGetterInInterfaces(InterfaceType targetType, bool includeTargetType, String getterName, Set<ClassElement> visitedInterfaces) {
+    // TODO(brianwilkerson) This isn't correct. Section 8.1.1 of the specification (titled
+    // "Inheritance and Overriding" under "Interfaces") describes a much more complex scheme for
+    // finding the inherited member. We need to follow that scheme. The code below should cover the
+    // 80% case.
     ClassElement targetClass = targetType.element;
     if (visitedInterfaces.contains(targetClass)) {
       return null;
     }
     visitedInterfaces.add(targetClass);
     if (includeTargetType) {
       PropertyAccessorElement getter = targetType.getGetter(getterName);
       if (getter != null && getter.isAccessibleIn(_definingLibrary)) {
         return getter;
       }
@@ skipping 49 matching lines @@
    * was found, or `null` if there is no method or getter with the given name.
    *
    * @param targetType the type in which the method or getter might be defined
    * @param includeTargetType `true` if the search should include the target type
    * @param memberName the name of the method or getter being looked up
    * @param visitedInterfaces a set containing all of the interfaces that have been examined, used
    *          to prevent infinite recursion and to optimize the search
    * @return the element representing the method or getter that was found
    */
   ExecutableElement lookUpGetterOrMethodInInterfaces(InterfaceType targetType, bool includeTargetType, String memberName, Set<ClassElement> visitedInterfaces) {
+    // TODO(brianwilkerson) This isn't correct. Section 8.1.1 of the specification (titled
+    // "Inheritance and Overriding" under "Interfaces") describes a much more complex scheme for
+    // finding the inherited member. We need to follow that scheme. The code below should cover the
+    // 80% case.
     ClassElement targetClass = targetType.element;
     if (visitedInterfaces.contains(targetClass)) {
       return null;
     }
     visitedInterfaces.add(targetClass);
     if (includeTargetType) {
       ExecutableElement member = targetType.getMethod(memberName);
       if (member != null) {
         return member;
       }
@@ skipping 30 matching lines @@
    */
   LabelElementImpl lookupLabel(ASTNode parentNode, SimpleIdentifier labelNode) {
     LabelScope labelScope = _resolver.labelScope;
     LabelElementImpl labelElement = null;
     if (labelNode == null) {
       if (labelScope == null) {
       } else {
         labelElement = labelScope.lookup2(LabelScope.EMPTY_LABEL) as LabelElementImpl;
         if (labelElement == null) {
         }
+        //
+        // The label element that was returned was a marker for look-up and isn't stored in the
+        // element model.
+        //
         labelElement = null;
       }
     } else {
       if (labelScope == null) {
         _resolver.reportError7(CompileTimeErrorCode.LABEL_UNDEFINED, labelNode, [labelNode.name]);
       } else {
         labelElement = labelScope.lookup(labelNode) as LabelElementImpl;
         if (labelElement == null) {
           _resolver.reportError7(CompileTimeErrorCode.LABEL_UNDEFINED, labelNode, [labelNode.name]);
         } else {
@@ skipping 44 matching lines @@
    * `null` if there is no method with the given name.
    *
    * @param targetType the type in which the member might be defined
    * @param includeTargetType `true` if the search should include the target type
    * @param methodName the name of the method being looked up
    * @param visitedInterfaces a set containing all of the interfaces that have been examined, used
    *          to prevent infinite recursion and to optimize the search
    * @return the element representing the method that was found
    */
   MethodElement lookUpMethodInInterfaces(InterfaceType targetType, bool includeTargetType, String methodName, Set<ClassElement> visitedInterfaces) {
+    // TODO(brianwilkerson) This isn't correct. Section 8.1.1 of the specification (titled
+    // "Inheritance and Overriding" under "Interfaces") describes a much more complex scheme for
+    // finding the inherited member. We need to follow that scheme. The code below should cover the
+    // 80% case.
     ClassElement targetClass = targetType.element;
     if (visitedInterfaces.contains(targetClass)) {
       return null;
     }
     visitedInterfaces.add(targetClass);
     if (includeTargetType) {
       MethodElement method = targetType.getMethod(methodName);
       if (method != null && method.isAccessibleIn(_definingLibrary)) {
         return method;
       }
@@ skipping 50 matching lines @@
    * `null` if there is no setter with the given name.
    *
    * @param targetType the type in which the setter might be defined
    * @param includeTargetType `true` if the search should include the target type
    * @param setterName the name of the setter being looked up
    * @param visitedInterfaces a set containing all of the interfaces that have been examined, used
    *          to prevent infinite recursion and to optimize the search
    * @return the element representing the setter that was found
    */
   PropertyAccessorElement lookUpSetterInInterfaces(InterfaceType targetType, bool includeTargetType, String setterName, Set<ClassElement> visitedInterfaces) {
+    // TODO(brianwilkerson) This isn't correct. Section 8.1.1 of the specification (titled
+    // "Inheritance and Overriding" under "Interfaces") describes a much more complex scheme for
+    // finding the inherited member. We need to follow that scheme. The code below should cover the
+    // 80% case.
     ClassElement targetClass = targetType.element;
     if (visitedInterfaces.contains(targetClass)) {
       return null;
     }
     visitedInterfaces.add(targetClass);
     if (includeTargetType) {
       PropertyAccessorElement setter = targetType.getSetter(setterName);
       if (setter != null && setter.isAccessibleIn(_definingLibrary)) {
         return setter;
       }
@@ skipping 71 matching lines @@
         return sc.TokenType.PLUS;
       } else if (operator == sc.TokenType.SLASH_EQ) {
         return sc.TokenType.SLASH;
       } else if (operator == sc.TokenType.STAR_EQ) {
         return sc.TokenType.STAR;
       } else if (operator == sc.TokenType.TILDE_SLASH_EQ) {
         return sc.TokenType.TILDE_SLASH;
       }
       break;
     }
+    // Internal error: Unmapped assignment operator.
     AnalysisEngine.instance.logger.logError("Failed to map ${operator.lexeme} to it's corresponding operator");
     return operator;
   }
 
   void resolveAnnotationConstructorInvocationArguments(Annotation annotation, ConstructorElement constructor) {
     ArgumentList argumentList = annotation.arguments;
+    // error will be reported in ConstantVerifier
     if (argumentList == null) {
       return;
     }
+    // resolve arguments to parameters
     List<ParameterElement> parameters = resolveArgumentsToParameters(true, argumentList, constructor);
     if (parameters != null) {
       argumentList.correspondingStaticParameters = parameters;
     }
   }
 
   /**
    * Continues resolution of the given [Annotation].
    *
    * @param annotation the [Annotation] to resolve
    */
   void resolveAnnotationElement(Annotation annotation) {
     SimpleIdentifier nameNode1;
     SimpleIdentifier nameNode2;
     {
       Identifier annName = annotation.name;
       if (annName is PrefixedIdentifier) {
         PrefixedIdentifier prefixed = annName;
         nameNode1 = prefixed.prefix;
         nameNode2 = prefixed.identifier;
       } else {
         nameNode1 = annName as SimpleIdentifier;
         nameNode2 = null;
       }
     }
     SimpleIdentifier nameNode3 = annotation.constructorName;
     ConstructorElement constructor = null;
+    //
+    // CONST or Class(args)
+    //
     if (nameNode1 != null && nameNode2 == null && nameNode3 == null) {
       Element element1 = nameNode1.staticElement;
+      // CONST
       if (element1 is PropertyAccessorElement) {
         resolveAnnotationElementGetter(annotation, element1);
         return;
       }
+      // Class(args)
       if (element1 is ClassElement) {
         ClassElement classElement = element1;
         constructor = new InterfaceTypeImpl.con1(classElement).lookUpConstructor(null, _definingLibrary);
       }
     }
+    //
+    // prefix.CONST or prefix.Class() or Class.CONST or Class.constructor(args)
+    //
     if (nameNode1 != null && nameNode2 != null && nameNode3 == null) {
       Element element1 = nameNode1.staticElement;
       Element element2 = nameNode2.staticElement;
+      // Class.CONST - not resolved yet
       if (element1 is ClassElement) {
         ClassElement classElement = element1;
         element2 = classElement.lookUpGetter(nameNode2.name, _definingLibrary);
       }
+      // prefix.CONST or Class.CONST
       if (element2 is PropertyAccessorElement) {
         nameNode2.staticElement = element2;
         annotation.element = element2;
         resolveAnnotationElementGetter(annotation, element2 as PropertyAccessorElement);
         return;
       }
+      // prefix.Class()
       if (element2 is ClassElement) {
         ClassElement classElement = element2 as ClassElement;
         constructor = classElement.unnamedConstructor;
       }
+      // Class.constructor(args)
       if (element1 is ClassElement) {
         ClassElement classElement = element1;
         constructor = new InterfaceTypeImpl.con1(classElement).lookUpConstructor(nameNode2.name, _definingLibrary);
         nameNode2.staticElement = constructor;
       }
     }
+    //
+    // prefix.Class.CONST or prefix.Class.constructor(args)
+    //
     if (nameNode1 != null && nameNode2 != null && nameNode3 != null) {
       Element element2 = nameNode2.staticElement;
+      // element2 should be ClassElement
       if (element2 is ClassElement) {
         ClassElement classElement = element2;
         String name3 = nameNode3.name;
+        // prefix.Class.CONST
         PropertyAccessorElement getter = classElement.lookUpGetter(name3, _definingLibrary);
         if (getter != null) {
           nameNode3.staticElement = getter;
           annotation.element = element2;
           resolveAnnotationElementGetter(annotation, getter);
           return;
         }
+        // prefix.Class.constructor(args)
         constructor = new InterfaceTypeImpl.con1(classElement).lookUpConstructor(name3, _definingLibrary);
         nameNode3.staticElement = constructor;
       }
     }
+    // we need constructor
     if (constructor == null) {
       _resolver.reportError7(CompileTimeErrorCode.INVALID_ANNOTATION, annotation, []);
       return;
     }
+    // record element
     annotation.element = constructor;
+    // resolve arguments
     resolveAnnotationConstructorInvocationArguments(annotation, constructor);
   }
 
   void resolveAnnotationElementGetter(Annotation annotation, PropertyAccessorElement accessorElement) {
+    // accessor should be synthetic
     if (!accessorElement.isSynthetic) {
       _resolver.reportError7(CompileTimeErrorCode.INVALID_ANNOTATION, annotation, []);
       return;
     }
+    // variable should be constant
     VariableElement variableElement = accessorElement.variable;
     if (!variableElement.isConst) {
       _resolver.reportError7(CompileTimeErrorCode.INVALID_ANNOTATION, annotation, []);
     }
+    // OK
     return;
   }
 
   /**
    * Given a list of arguments and the element that will be invoked using those argument, compute
    * the list of parameters that correspond to the list of arguments. Return the parameters that
    * correspond to the arguments, or `null` if no correspondence could be computed.
    *
    * @param reportError if `true` then compile-time error should be reported; if `false`
    *          then compile-time warning
@@ skipping 77 matching lines @@
   }
 
   /**
    * Resolve the names in the given combinators in the scope of the given library.
    *
    * @param library the library that defines the names
    * @param combinators the combinators containing the names to be resolved
    */
   void resolveCombinators(LibraryElement library, NodeList<Combinator> combinators) {
     if (library == null) {
+      //
+      // The library will be null if the directive containing the combinators has a URI that is not
+      // valid.
+      //
       return;
     }
     Namespace namespace = new NamespaceBuilder().createExportNamespace2(library);
     for (Combinator combinator in combinators) {
       NodeList<SimpleIdentifier> names;
       if (combinator is HideCombinator) {
         names = combinator.hiddenNames;
       } else {
         names = (combinator as ShowCombinator).shownNames;
       }
@@ skipping 38 matching lines @@
    * @param target the target of the invocation ('e')
    * @param targetType the type of the target
    * @param methodName the name of the method being invoked ('m')
    * @return the element being invoked
    */
   Element resolveInvokedElement(Expression target, Type2 targetType, SimpleIdentifier methodName) {
     if (targetType is InterfaceType) {
       InterfaceType classType = targetType;
       Element element = lookUpMethod(target, classType, methodName.name);
       if (element == null) {
+        //
+        // If there's no method, then it's possible that 'm' is a getter that returns a function.
+        //
         element = lookUpGetter(target, classType, methodName.name);
       }
       return element;
     } else if (target is SimpleIdentifier) {
       Element targetElement = target.staticElement;
       if (targetElement is PrefixElement) {
+        //
+        // Look to see whether the name of the method is really part of a prefixed identifier for an
+        // imported top-level function or top-level getter that returns a function.
+        //
         String name = "${target.name}.${methodName}";
         Identifier functionName = new ElementResolver_SyntheticIdentifier(name);
         Element element = _resolver.nameScope.lookup(functionName, _definingLibrary);
         if (element != null) {
+          // TODO(brianwilkerson) This isn't a method invocation, it's a function invocation where
+          // the function name is a prefixed identifier. Consider re-writing the AST.
           return element;
         }
       }
     }
+    // TODO(brianwilkerson) Report this error.
     return null;
   }
 
   /**
    * Given an invocation of the form 'm(a1, ..., an)', resolve 'm' to the element being invoked. If
    * the returned element is a method, then the method will be invoked. If the returned element is a
    * getter, the getter will be invoked without arguments and the result of that invocation will
    * then be invoked with the arguments.
    *
    * @param methodName the name of the method being invoked ('m')
    * @return the element being invoked
    */
   Element resolveInvokedElement2(SimpleIdentifier methodName) {
+    //
+    // Look first in the lexical scope.
+    //
     Element element = _resolver.nameScope.lookup(methodName, _definingLibrary);
     if (element == null) {
+      //
+      // If it isn't defined in the lexical scope, and the invocation is within a class, then look
+      // in the inheritance scope.
+      //
       ClassElement enclosingClass = _resolver.enclosingClass;
       if (enclosingClass != null) {
         InterfaceType enclosingType = enclosingClass.type;
         element = lookUpMethod(null, enclosingType, methodName.name);
         if (element == null) {
+          //
+          // If there's no method, then it's possible that 'm' is a getter that returns a function.
+          //
           element = lookUpGetter(null, enclosingType, methodName.name);
         }
       }
     }
+    // TODO(brianwilkerson) Report this error.
     return element;
   }
 
   /**
    * Given that we are accessing a property of the given type with the given name, return the
    * element that represents the property.
    *
    * @param target the target of the invocation ('e')
    * @param targetType the type in which the search for the property should begin
    * @param propertyName the name of the property being accessed
@@ skipping 11 matching lines @@
       memberElement = lookUpMethod(target, targetType, propertyName.name);
     }
     return memberElement;
   }
 
   void resolvePropertyAccess(Expression target, SimpleIdentifier propertyName) {
     Type2 staticType = getStaticType(target);
     Type2 propagatedType = getPropagatedType(target);
     Element staticElement = null;
     Element propagatedElement = null;
+    //
+    // If this property access is of the form 'C.m' where 'C' is a class, then we don't call
+    // resolveProperty(..) which walks up the class hierarchy, instead we just look for the
+    // member in the type only.
+    //
     ClassElementImpl typeReference = getTypeReference(target);
     if (typeReference != null) {
       staticElement = propagatedElement = resolveElement(typeReference, propertyName);
     } else {
       staticElement = resolveProperty(target, staticType, propertyName);
       propagatedElement = resolveProperty(target, propagatedType, propertyName);
     }
+    // May be part of annotation, record property element only if exists.
+    // Error was already reported in validateAnnotationElement().
     if (target.parent.parent is Annotation) {
       if (staticElement != null) {
         propertyName.staticElement = staticElement;
       }
       return;
     }
     propertyName.staticElement = staticElement;
     propertyName.propagatedElement = propagatedElement;
     bool shouldReportMissingMember_static = shouldReportMissingMember(staticType, staticElement);
     bool shouldReportMissingMember_propagated = !shouldReportMissingMember_static && _enableHints ? shouldReportMissingMember(propagatedType, propagatedElement) : false;
+    // If we are about to generate the hint (propagated version of this warning), then check
+    // that the member is not in a subtype of the propagated type.
     if (shouldReportMissingMember_propagated) {
       if (memberFoundInSubclass(propagatedType.element, propertyName.name, false, true)) {
         shouldReportMissingMember_propagated = false;
       }
     }
     if (shouldReportMissingMember_static || shouldReportMissingMember_propagated) {
       Element staticOrPropagatedEnclosingElt = shouldReportMissingMember_static ? staticType.element : propagatedType.element;
-      bool isStaticProperty = isStatic(staticOrPropagatedEnclosingElt);
-      if (propertyName.inSetterContext()) {
-        if (isStaticProperty) {
-          ErrorCode errorCode = (shouldReportMissingMember_static ? StaticWarningCode.UNDEFINED_SETTER : HintCode.UNDEFINED_SETTER) as ErrorCode;
-          _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
-              propertyName.name,
-              staticOrPropagatedEnclosingElt.displayName]);
+      if (staticOrPropagatedEnclosingElt != null) {
+        bool isStaticProperty = isStatic(staticOrPropagatedEnclosingElt);
+        if (propertyName.inSetterContext()) {
+          if (isStaticProperty) {
+            ErrorCode errorCode = (shouldReportMissingMember_static ? StaticWarningCode.UNDEFINED_SETTER : HintCode.UNDEFINED_SETTER) as ErrorCode;
+            _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
+                propertyName.name,
+                staticOrPropagatedEnclosingElt.displayName]);
+          } else {
+            ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_SETTER : HintCode.UNDEFINED_SETTER) as ErrorCode;
+            _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
+                propertyName.name,
+                staticOrPropagatedEnclosingElt.displayName]);
+          }
+        } else if (propertyName.inGetterContext()) {
+          if (isStaticProperty) {
+            ErrorCode errorCode = (shouldReportMissingMember_static ? StaticWarningCode.UNDEFINED_GETTER : HintCode.UNDEFINED_GETTER) as ErrorCode;
+            _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
+                propertyName.name,
+                staticOrPropagatedEnclosingElt.displayName]);
+          } else {
+            ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_GETTER : HintCode.UNDEFINED_GETTER) as ErrorCode;
+            _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
+                propertyName.name,
+                staticOrPropagatedEnclosingElt.displayName]);
+          }
         } else {
-          ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_SETTER : HintCode.UNDEFINED_SETTER) as ErrorCode;
-          _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
-              propertyName.name,
-              staticOrPropagatedEnclosingElt.displayName]);
+          _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, StaticWarningCode.UNDEFINED_IDENTIFIER, propertyName, [propertyName.name]);
         }
-      } else if (propertyName.inGetterContext()) {
-        if (isStaticProperty) {
-          ErrorCode errorCode = (shouldReportMissingMember_static ? StaticWarningCode.UNDEFINED_GETTER : HintCode.UNDEFINED_GETTER) as ErrorCode;
-          _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
-              propertyName.name,
-              staticOrPropagatedEnclosingElt.displayName]);
-        } else {
-          ErrorCode errorCode = (shouldReportMissingMember_static ? StaticTypeWarningCode.UNDEFINED_GETTER : HintCode.UNDEFINED_GETTER) as ErrorCode;
-          _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, errorCode, propertyName, [
-              propertyName.name,
-              staticOrPropagatedEnclosingElt.displayName]);
-        }
-      } else {
-        _resolver.reportErrorProxyConditionalAnalysisError(staticOrPropagatedEnclosingElt, StaticWarningCode.UNDEFINED_IDENTIFIER, propertyName, [propertyName.name]);
       }
     }
   }
 
   /**
    * Resolve the given simple identifier if possible. Return the element to which it could be
    * resolved, or `null` if it could not be resolved. This does not record the results of the
    * resolution.
    *
    * @param node the identifier to be resolved
    * @return the element to which the identifier could be resolved
    */
   Element resolveSimpleIdentifier(SimpleIdentifier node) {
     Element element = _resolver.nameScope.lookup(node, _definingLibrary);
     if (element is PropertyAccessorElement && node.inSetterContext()) {
       PropertyInducingElement variable = (element as PropertyAccessorElement).variable;
       if (variable != null) {
         PropertyAccessorElement setter = variable.setter;
         if (setter == null) {
+          //
+          // Check to see whether there might be a locally defined getter and an inherited setter.
+          //
           ClassElement enclosingClass = _resolver.enclosingClass;
           if (enclosingClass != null) {
             setter = lookUpSetter(null, enclosingClass.type, node.name);
           }
         }
         if (setter != null) {
           element = setter;
         }
       }
     } else if (element == null && node.inSetterContext()) {
@@ skipping 407 matching lines @@
    * @param baseFunctionType the function type that is being overridden
    * @param memberName the name of the member, this is used to lookup the inheritance path of the
    *          override
    * @param definingType the type that is overriding the member
    * @return the passed function type with any parameterized types substituted
    */
   FunctionType substituteTypeArgumentsInMemberFromInheritance(FunctionType baseFunctionType, String memberName, InterfaceType definingType) {
     if (baseFunctionType == null) {
       return baseFunctionType;
     }
+    // First, generate the path from the defining type to the overridden member
     Queue<InterfaceType> inheritancePath = new Queue<InterfaceType>();
     computeInheritancePath(inheritancePath, definingType, memberName);
     if (inheritancePath == null || inheritancePath.isEmpty) {
+      // TODO(jwren) log analysis engine error
       return baseFunctionType;
     }
     FunctionType functionTypeToReturn = baseFunctionType;
+    // loop backward through the list substituting as we go:
     while (!inheritancePath.isEmpty) {
       InterfaceType lastType = inheritancePath.removeLast();
       List<Type2> parameterTypes = lastType.element.type.typeArguments;
       List<Type2> argumentTypes = lastType.typeArguments;
       functionTypeToReturn = functionTypeToReturn.substitute2(argumentTypes, parameterTypes);
     }
     return functionTypeToReturn;
   }
 
   /**
@@ skipping 12 matching lines @@
     if (resultMap != null) {
       return resultMap;
     } else {
       resultMap = new MemberMap();
     }
     ClassElement superclassElt = null;
     InterfaceType supertype = classElt.supertype;
     if (supertype != null) {
       superclassElt = supertype.element;
     } else {
+      // classElt is Object
       _classLookup[classElt] = resultMap;
       return resultMap;
     }
     if (superclassElt != null) {
       if (!visitedClasses.contains(superclassElt)) {
         visitedClasses.add(classElt);
         resultMap = new MemberMap.con2(computeClassChainLookupMap(superclassElt, visitedClasses));
       } else {
+        // This case happens only when the superclass was previously visited and not in the lookup,
+        // meaning this is meant to shorten the compute for recursive cases.
         _classLookup[superclassElt] = resultMap;
         return resultMap;
       }
+      //
+      // Substitute the supertypes down the hierarchy
+      //
       substituteTypeParametersDownHierarchy(supertype, resultMap);
+      //
+      // Include the members from the superclass in the resultMap
+      //
       recordMapWithClassMembers(resultMap, supertype);
     }
+    //
+    // Include the members from the mixins in the resultMap
+    //
     List<InterfaceType> mixins = classElt.mixins;
     for (int i = mixins.length - 1; i >= 0; i--) {
       recordMapWithClassMembers(resultMap, mixins[i]);
     }
     _classLookup[classElt] = resultMap;
     return resultMap;
   }
 
   /**
    * Compute and return the inheritance path given the context of a type and a member that is
    * overridden in the inheritance path (for which the type is in the path).
    *
    * @param chain the inheritance path that is built up as this method calls itself recursively,
    *          when this method is called an empty [LinkedList] should be provided
    * @param currentType the current type in the inheritance path
    * @param memberName the name of the member that is being looked up the inheritance path
    */
   void computeInheritancePath(Queue<InterfaceType> chain, InterfaceType currentType, String memberName) {
+    // TODO (jwren) create a public version of this method which doesn't require the initial chain
+    // to be provided, then provided tests for this functionality in InheritanceManagerTest
     chain.add(currentType);
     ClassElement classElt = currentType.element;
     InterfaceType supertype = classElt.supertype;
+    // Base case- reached Object
     if (supertype == null) {
+      // Looked up the chain all the way to Object, return null.
+      // This should never happen.
       return;
     }
+    // If we are done, return the chain
+    // We are not done if this is the first recursive call on this method.
     if (chain.length != 1) {
+      // We are done however if the member is in this classElt
       if (lookupMemberInClass(classElt, memberName) != null) {
         return;
       }
     }
+    // Mixins- note that mixins call lookupMemberInClass, not lookupMember
     List<InterfaceType> mixins = classElt.mixins;
     for (int i = mixins.length - 1; i >= 0; i--) {
       ClassElement mixinElement = mixins[i].element;
       if (mixinElement != null) {
         ExecutableElement elt = lookupMemberInClass(mixinElement, memberName);
         if (elt != null) {
+          // this is equivalent (but faster than) calling this method recursively
+          // (return computeInheritancePath(chain, mixins[i], memberName);)
           chain.add(mixins[i]);
           return;
         }
       }
     }
+    // Superclass
     ClassElement superclassElt = supertype.element;
     if (lookupMember(superclassElt, memberName) != null) {
       computeInheritancePath(chain, supertype, memberName);
       return;
     }
+    // Interfaces
     List<InterfaceType> interfaces = classElt.interfaces;
     for (InterfaceType interfaceType in interfaces) {
       ClassElement interfaceElement = interfaceType.element;
       if (interfaceElement != null && lookupMember(interfaceElement, memberName) != null) {
         computeInheritancePath(chain, interfaceType, memberName);
         return;
       }
     }
   }
 
@@ skipping 12 matching lines @@
     MemberMap resultMap = _interfaceLookup[classElt];
     if (resultMap != null) {
       return resultMap;
     } else {
       resultMap = new MemberMap();
     }
     InterfaceType supertype = classElt.supertype;
     ClassElement superclassElement = supertype != null ? supertype.element : null;
     List<InterfaceType> mixins = classElt.mixins;
     List<InterfaceType> interfaces = classElt.interfaces;
+    // Recursively collect the list of mappings from all of the interface types
     List<MemberMap> lookupMaps = new List<MemberMap>();
+    // Superclass element
     if (superclassElement != null) {
       if (!visitedInterfaces.contains(superclassElement)) {
         try {
           visitedInterfaces.add(superclassElement);
+          //
+          // Recursively compute the map for the supertype.
+          //
           MemberMap map = computeInterfaceLookupMap(superclassElement, visitedInterfaces);
           map = new MemberMap.con2(map);
+          //
+          // Substitute the supertypes down the hierarchy
+          //
           substituteTypeParametersDownHierarchy(supertype, map);
+          //
+          // Add any members from the supertype into the map as well.
+          //
           recordMapWithClassMembers(map, supertype);
           lookupMaps.add(map);
         } finally {
           visitedInterfaces.remove(superclassElement);
         }
       } else {
         MemberMap map = _interfaceLookup[classElt];
         if (map != null) {
           lookupMaps.add(map);
         } else {
           _interfaceLookup[superclassElement] = resultMap;
           return resultMap;
         }
       }
     }
+    // Mixin elements
     for (InterfaceType mixinType in mixins) {
       MemberMap mapWithMixinMembers = new MemberMap();
       recordMapWithClassMembers(mapWithMixinMembers, mixinType);
       lookupMaps.add(mapWithMixinMembers);
     }
+    // Interface elements
     for (InterfaceType interfaceType in interfaces) {
       ClassElement interfaceElement = interfaceType.element;
       if (interfaceElement != null) {
         if (!visitedInterfaces.contains(interfaceElement)) {
           try {
             visitedInterfaces.add(interfaceElement);
+            //
+            // Recursively compute the map for the interfaces.
+            //
             MemberMap map = computeInterfaceLookupMap(interfaceElement, visitedInterfaces);
             map = new MemberMap.con2(map);
+            //
+            // Substitute the supertypes down the hierarchy
+            //
             substituteTypeParametersDownHierarchy(interfaceType, map);
+            //
+            // And add any members from the interface into the map as well.
+            //
             recordMapWithClassMembers(map, interfaceType);
             lookupMaps.add(map);
           } finally {
             visitedInterfaces.remove(interfaceElement);
           }
         } else {
           MemberMap map = _interfaceLookup[classElt];
           if (map != null) {
             lookupMaps.add(map);
           } else {
             _interfaceLookup[interfaceElement] = resultMap;
             return resultMap;
           }
         }
       }
     }
     if (lookupMaps.length == 0) {
       _interfaceLookup[classElt] = resultMap;
       return resultMap;
     }
+    //
+    // Union all of the maps together, grouping the ExecutableElements into sets.
+    //
     Map<String, Set<ExecutableElement>> unionMap = new Map<String, Set<ExecutableElement>>();
     for (MemberMap lookupMap in lookupMaps) {
       for (int i = 0; i < lookupMap.size; i++) {
         String key = lookupMap.getKey(i);
         if (key == null) {
           break;
         }
         Set<ExecutableElement> set = unionMap[key];
         if (set == null) {
           set = new Set<ExecutableElement>();
           unionMap[key] = set;
         }
         set.add(lookupMap.getValue(i));
       }
     }
+    //
+    // Loop through the entries in the union map, adding them to the resultMap appropriately.
+    //
     for (MapEntry<String, Set<ExecutableElement>> entry in getMapEntrySet(unionMap)) {
       String key = entry.getKey();
       Set<ExecutableElement> set = entry.getValue();
       int numOfEltsWithMatchingNames = set.length;
       if (numOfEltsWithMatchingNames == 1) {
         resultMap.put(key, new JavaIterator(set).next());
       } else {
         bool allMethods = true;
         bool allSetters = true;
         bool allGetters = true;
         for (ExecutableElement executableElement in set) {
           if (executableElement is PropertyAccessorElement) {
             allMethods = false;
             if (executableElement.isSetter) {
               allGetters = false;
             } else {
               allSetters = false;
             }
           } else {
             allGetters = false;
             allSetters = false;
           }
         }
         if (allMethods || allGetters || allSetters) {
+          // Compute the element whose type is the subtype of all of the other types.
           List<ExecutableElement> elements = new List.from(set);
           List<FunctionType> executableElementTypes = new List<FunctionType>(numOfEltsWithMatchingNames);
           for (int i = 0; i < numOfEltsWithMatchingNames; i++) {
             executableElementTypes[i] = elements[i].type;
           }
           bool foundSubtypeOfAllTypes = false;
           for (int i = 0; i < numOfEltsWithMatchingNames; i++) {
             FunctionType subtype = executableElementTypes[i];
             if (subtype == null) {
               continue;
@@ skipping 479 matching lines @@
     Source librarySource = library.librarySource;
     CompilationUnit definingCompilationUnit = library.definingCompilationUnit;
     CompilationUnitElementImpl definingCompilationUnitElement = builder.buildCompilationUnit(librarySource, definingCompilationUnit);
     NodeList<Directive> directives = definingCompilationUnit.directives;
     LibraryIdentifier libraryNameNode = null;
     bool hasPartDirective = false;
     FunctionElement entryPoint = findEntryPoint(definingCompilationUnitElement);
     List<Directive> directivesToResolve = new List<Directive>();
     List<CompilationUnitElementImpl> sourcedCompilationUnits = new List<CompilationUnitElementImpl>();
     for (Directive directive in directives) {
+      //
+      // We do not build the elements representing the import and export directives at this point.
+      // That is not done until we get to LibraryResolver.buildDirectiveModels() because we need the
+      // LibraryElements for the referenced libraries, which might not exist at this point (due to
+      // the possibility of circular references).
+      //
       if (directive is LibraryDirective) {
         if (libraryNameNode == null) {
           libraryNameNode = directive.name;
           directivesToResolve.add(directive);
         }
       } else if (directive is PartDirective) {
         PartDirective partDirective = directive;
         StringLiteral partUri = partDirective.uri;
         Source partSource = library.getSource(partDirective);
         if (partSource != null && partSource.exists()) {
           hasPartDirective = true;
           CompilationUnitElementImpl part = builder.buildCompilationUnit(partSource, library.getAST(partSource));
           part.uri = library.getUri(partDirective);
+          //
+          // Validate that the part contains a part-of directive with the same name as the library.
+          //
           String partLibraryName = getPartLibraryName(library, partSource, directivesToResolve);
           if (partLibraryName == null) {
             _errorListener.onError(new AnalysisError.con2(librarySource, partUri.offset, partUri.length, CompileTimeErrorCode.PART_OF_NON_PART, [partUri.toSource()]));
           } else if (libraryNameNode == null) {
           } else if (libraryNameNode.name != partLibraryName) {
             _errorListener.onError(new AnalysisError.con2(librarySource, partUri.offset, partUri.length, StaticWarningCode.PART_OF_DIFFERENT_LIBRARY, [libraryNameNode.name, partLibraryName]));
           }
           if (entryPoint == null) {
             entryPoint = findEntryPoint(part);
           }
           directive.element = part;
           sourcedCompilationUnits.add(part);
         }
       }
     }
     if (hasPartDirective && libraryNameNode == null) {
       _errorListener.onError(new AnalysisError.con1(librarySource, ResolverErrorCode.MISSING_LIBRARY_DIRECTIVE_WITH_PART, []));
     }
+    //
+    // Create and populate the library element.
+    //
     LibraryElementImpl libraryElement = new LibraryElementImpl(_analysisContext, libraryNameNode);
     libraryElement.definingCompilationUnit = definingCompilationUnitElement;
     if (entryPoint != null) {
       libraryElement.entryPoint = entryPoint;
     }
     int sourcedUnitCount = sourcedCompilationUnits.length;
     libraryElement.parts = new List.from(sourcedCompilationUnits);
     for (Directive directive in directivesToResolve) {
       directive.element = libraryElement;
     }
@@ skipping 173 matching lines @@
    * @param unit the compilation unit representing the embedded library
    * @param fullAnalysis `true` if a full analysis should be performed
    * @return the element representing the resolved library
    * @throws AnalysisException if the library could not be resolved for some reason
    */
   LibraryElement resolveEmbeddedLibrary(Source librarySource, int modificationStamp, CompilationUnit unit, bool fullAnalysis) {
     InstrumentationBuilder instrumentation = Instrumentation.builder2("dart.engine.LibraryResolver.resolveEmbeddedLibrary");
     try {
       instrumentation.metric("fullAnalysis", fullAnalysis);
       instrumentation.data3("fullName", librarySource.fullName);
+      //
+      // Create the objects representing the library being resolved and the core library.
+      //
       Library targetLibrary = createLibrary2(librarySource, modificationStamp, unit);
       _coreLibrary = _libraryMap[_coreLibrarySource];
       if (_coreLibrary == null) {
+        // This will be true unless the library being analyzed is the core library.
         _coreLibrary = createLibrary(_coreLibrarySource);
       }
       instrumentation.metric3("createLibrary", "complete");
+      //
+      // Compute the set of libraries that need to be resolved together.
+      //
       computeLibraryDependencies2(targetLibrary, unit);
       _librariesInCycles = computeLibrariesInCycles(targetLibrary);
+      //
+      // Build the element models representing the libraries being resolved. This is done in three
+      // steps:
+      //
+      // 1. Build the basic element models without making any connections between elements other than
+      //    the basic parent/child relationships. This includes building the elements representing the
+      //    libraries.
+      // 2. Build the elements for the import and export directives. This requires that we have the
+      //    elements built for the referenced libraries, but because of the possibility of circular
+      //    references needs to happen after all of the library elements have been created.
+      // 3. Build the rest of the type model by connecting superclasses, mixins, and interfaces. This
+      //    requires that we be able to compute the names visible in the libraries being resolved,
+      //    which in turn requires that we have resolved the import directives.
+      //
       buildElementModels();
       instrumentation.metric3("buildElementModels", "complete");
       LibraryElement coreElement = _coreLibrary.libraryElement;
       if (coreElement == null) {
         throw new AnalysisException.con1("Could not resolve dart:core");
       }
       buildDirectiveModels();
       instrumentation.metric3("buildDirectiveModels", "complete");
       _typeProvider = new TypeProviderImpl(coreElement);
       buildTypeHierarchies();
       instrumentation.metric3("buildTypeHierarchies", "complete");
+      //
+      // Perform resolution and type analysis.
+      //
+      // TODO(brianwilkerson) Decide whether we want to resolve all of the libraries or whether we
+      // want to only resolve the target library. The advantage to resolving everything is that we
+      // have already done part of the work so we'll avoid duplicated effort. The disadvantage of
+      // resolving everything is that we might do extra work that we don't really care about. Another
+      // possibility is to add a parameter to this method and punt the decision to the clients.
+      //
+      //if (analyzeAll) {
       resolveReferencesAndTypes();
       instrumentation.metric3("resolveReferencesAndTypes", "complete");
+      //} else {
+      //  resolveReferencesAndTypes(targetLibrary);
+      //}
       performConstantEvaluation();
       instrumentation.metric3("performConstantEvaluation", "complete");
       return targetLibrary.libraryElement;
     } finally {
       instrumentation.log();
     }
   }
 
   /**
    * Resolve the library specified by the given source in the given context.
    *
    * Note that because Dart allows circular imports between libraries, it is possible that more than
    * one library will need to be resolved. In such cases the error listener can receive errors from
    * multiple libraries.
    *
    * @param librarySource the source specifying the defining compilation unit of the library to be
    *          resolved
    * @param fullAnalysis `true` if a full analysis should be performed
    * @return the element representing the resolved library
    * @throws AnalysisException if the library could not be resolved for some reason
    */
   LibraryElement resolveLibrary(Source librarySource, bool fullAnalysis) {
     InstrumentationBuilder instrumentation = Instrumentation.builder2("dart.engine.LibraryResolver.resolveLibrary");
     try {
       instrumentation.metric("fullAnalysis", fullAnalysis);
       instrumentation.data3("fullName", librarySource.fullName);
+      //
+      // Create the objects representing the library being resolved and the core library.
+      //
       Library targetLibrary = createLibrary(librarySource);
       _coreLibrary = _libraryMap[_coreLibrarySource];
       if (_coreLibrary == null) {
+        // This will be true unless the library being analyzed is the core library.
         _coreLibrary = createLibraryOrNull(_coreLibrarySource);
         if (_coreLibrary == null) {
           throw new AnalysisException.con1("Core library does not exist");
         }
       }
       instrumentation.metric3("createLibrary", "complete");
+      //
+      // Compute the set of libraries that need to be resolved together.
+      //
       computeLibraryDependencies(targetLibrary);
       _librariesInCycles = computeLibrariesInCycles(targetLibrary);
+      //
+      // Build the element models representing the libraries being resolved. This is done in three
+      // steps:
+      //
+      // 1. Build the basic element models without making any connections between elements other than
+      //    the basic parent/child relationships. This includes building the elements representing the
+      //    libraries.
+      // 2. Build the elements for the import and export directives. This requires that we have the
+      //    elements built for the referenced libraries, but because of the possibility of circular
+      //    references needs to happen after all of the library elements have been created.
+      // 3. Build the rest of the type model by connecting superclasses, mixins, and interfaces. This
+      //    requires that we be able to compute the names visible in the libraries being resolved,
+      //    which in turn requires that we have resolved the import directives.
+      //
       buildElementModels();
       instrumentation.metric3("buildElementModels", "complete");
       LibraryElement coreElement = _coreLibrary.libraryElement;
       if (coreElement == null) {
         throw new AnalysisException.con1("Could not resolve dart:core");
       }
       buildDirectiveModels();
       instrumentation.metric3("buildDirectiveModels", "complete");
       _typeProvider = new TypeProviderImpl(coreElement);
       buildTypeHierarchies();
       instrumentation.metric3("buildTypeHierarchies", "complete");
+      //
+      // Perform resolution and type analysis.
+      //
+      // TODO(brianwilkerson) Decide whether we want to resolve all of the libraries or whether we
+      // want to only resolve the target library. The advantage to resolving everything is that we
+      // have already done part of the work so we'll avoid duplicated effort. The disadvantage of
+      // resolving everything is that we might do extra work that we don't really care about. Another
+      // possibility is to add a parameter to this method and punt the decision to the clients.
+      //
+      //if (analyzeAll) {
       resolveReferencesAndTypes();
       instrumentation.metric3("resolveReferencesAndTypes", "complete");
+      //} else {
+      //  resolveReferencesAndTypes(targetLibrary);
+      //}
       performConstantEvaluation();
       instrumentation.metric3("performConstantEvaluation", "complete");
       instrumentation.metric2("librariesInCycles", _librariesInCycles.length);
       for (Library lib in _librariesInCycles) {
         instrumentation.metric2("librariesInCycles-CompilationUnitSources-Size", lib.compilationUnitSources.length);
       }
       return targetLibrary.libraryElement;
     } finally {
       instrumentation.log();
     }
@@ skipping 91 matching lines @@
   void buildDirectiveModels() {
     for (Library library in _librariesInCycles) {
       Map<String, PrefixElementImpl> nameToPrefixMap = new Map<String, PrefixElementImpl>();
       List<ImportElement> imports = new List<ImportElement>();
       List<ExportElement> exports = new List<ExportElement>();
       for (Directive directive in library.definingCompilationUnit.directives) {
         if (directive is ImportDirective) {
           ImportDirective importDirective = directive;
           Source importedSource = library.getSource(importDirective);
           if (importedSource != null) {
+            // The imported source will be null if the URI in the import directive was invalid.
             Library importedLibrary = _libraryMap[importedSource];
             if (importedLibrary != null) {
               ImportElementImpl importElement = new ImportElementImpl(directive.offset);
               StringLiteral uriLiteral = importDirective.uri;
               if (uriLiteral != null) {
                 importElement.uriEnd = uriLiteral.end;
               }
               importElement.uri = library.getUri(importDirective);
               importElement.combinators = buildCombinators(importDirective);
               LibraryElement importedLibraryElement = importedLibrary.libraryElement;
@@ skipping 16 matching lines @@
               imports.add(importElement);
               if (analysisContext.computeKindOf(importedSource) != SourceKind.LIBRARY) {
                 _errorListener.onError(new AnalysisError.con2(library.librarySource, uriLiteral.offset, uriLiteral.length, CompileTimeErrorCode.IMPORT_OF_NON_LIBRARY, [uriLiteral.toSource()]));
               }
             }
           }
         } else if (directive is ExportDirective) {
           ExportDirective exportDirective = directive;
           Source exportedSource = library.getSource(exportDirective);
           if (exportedSource != null) {
+            // The exported source will be null if the URI in the export directive was invalid.
             Library exportedLibrary = _libraryMap[exportedSource];
             if (exportedLibrary != null) {
               ExportElementImpl exportElement = new ExportElementImpl();
               exportElement.uri = library.getUri(exportDirective);
               exportElement.combinators = buildCombinators(exportDirective);
               LibraryElement exportedLibraryElement = exportedLibrary.libraryElement;
               if (exportedLibraryElement != null) {
                 exportElement.exportedLibrary = exportedLibraryElement;
               }
               directive.element = exportElement;
@@ skipping 296 matching lines @@
         ast.accept(visitor);
         for (ProxyConditionalAnalysisError conditionalCode in visitor.proxyConditionalAnalysisErrors) {
           if (conditionalCode.shouldIncludeErrorCode()) {
             visitor.reportError(conditionalCode.analysisError);
           }
         }
       }
     } finally {
       timeCounter.stop();
     }
+    // Angular
     timeCounter = PerformanceStatistics.angular.start();
     try {
       for (Source source in library.compilationUnitSources) {
         CompilationUnit ast = library.getAST(source);
         new AngularCompilationUnitBuilder(_errorListener, source).build(ast);
       }
     } finally {
       timeCounter.stop();
     }
   }
@@ skipping 113 matching lines @@
   ExecutableElement getValue(int i) => _values[i];
 
   /**
    * Given some key/value pair, store the pair in the map. If the key exists already, then the new
    * value overrides the old value.
    *
    * @param key the key to store in the map
    * @param value the ExecutableElement value to store in the map
    */
   void put(String key, ExecutableElement value) {
+    // If we already have a value with this key, override the value
     for (int i = 0; i < _size; i++) {
       if (_keys[i] != null && _keys[i] == key) {
         _values[i] = value;
         return;
       }
     }
+    // If needed, double the size of our arrays and copy values over in both arrays
     if (_size == _keys.length) {
       int newArrayLength = _size * 2;
       List<String> keys_new_array = new List<String>(newArrayLength);
       List<ExecutableElement> values_new_array = new List<ExecutableElement>(newArrayLength);
       for (int i = 0; i < _size; i++) {
         keys_new_array[i] = _keys[i];
       }
       for (int i = 0; i < _size; i++) {
         values_new_array[i] = _values[i];
       }
       _keys = keys_new_array;
       _values = values_new_array;
     }
+    // Put new value at end of array
     _keys[_size] = key;
     _values[_size] = value;
     _size++;
   }
 
   /**
    * Given some String key, this method replaces the associated key and value pair with `null`
    * . The size is not decremented with this call, instead it is expected that the users check for
    * `null`.
    *
@@ skipping 208 matching lines @@
     sc.TokenType operatorType = node.operator.type;
     Expression leftOperand = node.leftOperand;
     Expression rightOperand = node.rightOperand;
     if (identical(operatorType, sc.TokenType.AMPERSAND_AMPERSAND)) {
       safelyVisit(leftOperand);
       if (rightOperand != null) {
         try {
           _overrideManager.enterScope();
           _promoteManager.enterScope();
           propagateTrueState(leftOperand);
+          // Type promotion.
           promoteTypes(leftOperand);
           clearTypePromotionsIfPotentiallyMutatedIn(leftOperand);
           clearTypePromotionsIfPotentiallyMutatedIn(rightOperand);
           clearTypePromotionsIfAccessedInClosureAndProtentiallyMutated(rightOperand);
+          // Visit right operand.
           rightOperand.accept(this);
         } finally {
           _overrideManager.exitScope();
           _promoteManager.exitScope();
         }
       }
     } else if (identical(operatorType, sc.TokenType.BAR_BAR)) {
       safelyVisit(leftOperand);
       if (rightOperand != null) {
         try {
@@ skipping 18 matching lines @@
     try {
       _overrideManager.enterScope();
       super.visitBlockFunctionBody(node);
     } finally {
       _overrideManager.exitScope();
     }
     return null;
   }
 
   Object visitBreakStatement(BreakStatement node) {
+    //
+    // We do not visit the label because it needs to be visited in the context of the statement.
+    //
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitClassDeclaration(ClassDeclaration node) {
     ClassElement outerType = _enclosingClass;
     try {
       _enclosingClass = node.element;
       _typeAnalyzer.thisType = _enclosingClass == null ? null : _enclosingClass.type;
@@ skipping 11 matching lines @@
         _commentBeforeFunction = node;
         return null;
       }
     }
     super.visitComment(node);
     _commentBeforeFunction = null;
     return null;
   }
 
   Object visitCommentReference(CommentReference node) {
+    //
+    // We do not visit the identifier because it needs to be visited in the context of the reference.
+    //
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitCompilationUnit(CompilationUnit node) {
+    //
+    // TODO(brianwilkerson) The goal of the code below is to visit the declarations in such an
+    // order that we can infer type information for top-level variables before we visit references
+    // to them. This is better than making no effort, but still doesn't completely satisfy that
+    // goal (consider for example "final var a = b; final var b = 0;"; we'll infer a type of 'int'
+    // for 'b', but not for 'a' because of the order of the visits). Ideally we would create a
+    // dependency graph, but that would require references to be resolved, which they are not.
+    //
     try {
       _overrideManager.enterScope();
       NodeList<Directive> directives = node.directives;
       int directiveCount = directives.length;
       for (int i = 0; i < directiveCount; i++) {
         directives[i].accept(this);
       }
       NodeList<CompilationUnitMember> declarations = node.declarations;
       int declarationCount = declarations.length;
       for (int i = 0; i < declarationCount; i++) {
@@ skipping 18 matching lines @@
 
   Object visitConditionalExpression(ConditionalExpression node) {
     Expression condition = node.condition;
     safelyVisit(condition);
     Expression thenExpression = node.thenExpression;
     if (thenExpression != null) {
       try {
         _overrideManager.enterScope();
         _promoteManager.enterScope();
         propagateTrueState(condition);
+        // Type promotion.
         promoteTypes(condition);
         clearTypePromotionsIfPotentiallyMutatedIn(thenExpression);
         clearTypePromotionsIfAccessedInClosureAndProtentiallyMutated(thenExpression);
+        // Visit "then" expression.
         thenExpression.accept(this);
       } finally {
         _overrideManager.exitScope();
         _promoteManager.exitScope();
       }
     }
     Expression elseExpression = node.elseExpression;
     if (elseExpression != null) {
       try {
         _overrideManager.enterScope();
@@ skipping 22 matching lines @@
     try {
       _enclosingFunction = node.element;
       super.visitConstructorDeclaration(node);
     } finally {
       _enclosingFunction = outerFunction;
     }
     return null;
   }
 
   Object visitConstructorFieldInitializer(ConstructorFieldInitializer node) {
+    //
+    // We visit the expression, but do not visit the field name because it needs to be visited in
+    // the context of the constructor field initializer node.
+    //
     safelyVisit(node.expression);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitConstructorName(ConstructorName node) {
+    //
+    // We do not visit either the type name, because it won't be visited anyway, or the name,
+    // because it needs to be visited in the context of the constructor name.
+    //
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitContinueStatement(ContinueStatement node) {
+    //
+    // We do not visit the label because it needs to be visited in the context of the statement.
+    //
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitDoStatement(DoStatement node) {
     try {
       _overrideManager.enterScope();
       super.visitDoStatement(node);
     } finally {
       _overrideManager.exitScope();
     }
+    // TODO(brianwilkerson) If the loop can only be exited because the condition is false, then
+    // propagateFalseState(node.getCondition());
     return null;
   }
 
   Object visitEmptyFunctionBody(EmptyFunctionBody node) {
     safelyVisit(_commentBeforeFunction);
     return super.visitEmptyFunctionBody(node);
   }
 
   Object visitExpressionFunctionBody(ExpressionFunctionBody node) {
     safelyVisit(_commentBeforeFunction);
@@ skipping 77 matching lines @@
   Object visitIfStatement(IfStatement node) {
     Expression condition = node.condition;
     safelyVisit(condition);
     Map<Element, Type2> thenOverrides = null;
     Statement thenStatement = node.thenStatement;
     if (thenStatement != null) {
       try {
         _overrideManager.enterScope();
         _promoteManager.enterScope();
         propagateTrueState(condition);
+        // Type promotion.
         promoteTypes(condition);
         clearTypePromotionsIfPotentiallyMutatedIn(thenStatement);
         clearTypePromotionsIfAccessedInClosureAndProtentiallyMutated(thenStatement);
+        // Visit "then".
         visitStatementInScope(thenStatement);
       } finally {
         thenOverrides = _overrideManager.captureLocalOverrides();
         _overrideManager.exitScope();
         _promoteManager.exitScope();
       }
     }
     Map<Element, Type2> elseOverrides = null;
     Statement elseStatement = node.elseStatement;
     if (elseStatement != null) {
@@ skipping 33 matching lines @@
     try {
       _enclosingFunction = node.element;
       super.visitMethodDeclaration(node);
     } finally {
       _enclosingFunction = outerFunction;
     }
     return null;
   }
 
   Object visitMethodInvocation(MethodInvocation node) {
+    //
+    // We visit the target and argument list, but do not visit the method name because it needs to
+    // be visited in the context of the invocation.
+    //
     safelyVisit(node.target);
     node.accept(_elementResolver);
     inferFunctionExpressionsParametersTypes(node.argumentList);
     safelyVisit(node.argumentList);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitNode(ASTNode node) {
     node.visitChildren(this);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitPrefixedIdentifier(PrefixedIdentifier node) {
+    //
+    // We visit the prefix, but do not visit the identifier because it needs to be visited in the
+    // context of the prefix.
+    //
     safelyVisit(node.prefix);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitPropertyAccess(PropertyAccess node) {
+    //
+    // We visit the target, but do not visit the property name because it needs to be visited in the
+    // context of the property access node.
+    //
     safelyVisit(node.target);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitRedirectingConstructorInvocation(RedirectingConstructorInvocation node) {
+    //
+    // We visit the argument list, but do not visit the optional identifier because it needs to be
+    // visited in the context of the constructor invocation.
+    //
     safelyVisit(node.argumentList);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitShowCombinator(ShowCombinator node) => null;
 
   Object visitSuperConstructorInvocation(SuperConstructorInvocation node) {
+    //
+    // We visit the argument list, but do not visit the optional identifier because it needs to be
+    // visited in the context of the constructor invocation.
+    //
     safelyVisit(node.argumentList);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   Object visitSwitchCase(SwitchCase node) {
     try {
       _overrideManager.enterScope();
       super.visitSwitchCase(node);
@@ skipping 33 matching lines @@
     Statement body = node.body;
     if (body != null) {
       try {
         _overrideManager.enterScope();
         propagateTrueState(condition);
         visitStatementInScope(body);
       } finally {
         _overrideManager.exitScope();
       }
     }
+    // TODO(brianwilkerson) If the loop can only be exited because the condition is false, then
+    // propagateFalseState(condition);
     node.accept(_elementResolver);
     node.accept(_typeAnalyzer);
     return null;
   }
 
   /**
    * Return the class element representing the class containing the current node, or `null` if
    * the current node is not contained in a class.
    *
    * @return the class element representing the class containing the current node
@@ skipping 156 matching lines @@
    * @param enclosingElement the enclosing element
    * @param errorCode the error code of the error to be reported
    * @param token the token specifying the location of the error
    * @param arguments the arguments to the error, used to compose the error message
    */
   void reportErrorProxyConditionalAnalysisError3(Element enclosingElement, ErrorCode errorCode, sc.Token token, List<Object> arguments) {
     _proxyConditionalAnalysisErrors.add(new ProxyConditionalAnalysisError(enclosingElement, new AnalysisError.con2(source, token.offset, token.length, errorCode, arguments)));
   }
 
   void visitForEachStatementInScope(ForEachStatement node) {
+    //
+    // We visit the iterator before the loop variable because the loop variable cannot be in scope
+    // while visiting the iterator.
+    //
     Expression iterator = node.iterator;
     safelyVisit(iterator);
     DeclaredIdentifier loopVariable = node.loopVariable;
     SimpleIdentifier identifier = node.identifier;
     safelyVisit(loopVariable);
     safelyVisit(identifier);
     Statement body = node.body;
     if (body != null) {
       try {
         _overrideManager.enterScope();
@@ skipping 92 matching lines @@
    *
    * @param iterator the iterator for a for-each statement
    * @return the type of objects that will be assigned to the loop variable
    */
   Type2 getIteratorElementType(Expression iteratorExpression) {
     Type2 expressionType = iteratorExpression.staticType;
     if (expressionType is InterfaceType) {
       InterfaceType interfaceType = expressionType;
       FunctionType iteratorFunction = _inheritanceManager.lookupMemberType(interfaceType, "iterator");
       if (iteratorFunction == null) {
+        // TODO(brianwilkerson) Should we report this error?
         return null;
       }
       Type2 iteratorType = iteratorFunction.returnType;
       if (iteratorType is InterfaceType) {
         InterfaceType iteratorInterfaceType = iteratorType;
         FunctionType currentFunction = _inheritanceManager.lookupMemberType(iteratorInterfaceType, "current");
         if (currentFunction == null) {
+          // TODO(brianwilkerson) Should we report this error?
           return null;
         }
         return currentFunction.returnType;
       }
     }
     return null;
   }
 
   /**
    * If given "mayBeClosure" is [FunctionExpression] without explicit parameters types and its
    * required type is [FunctionType], then infer parameters types from [FunctionType].
    */
   void inferFunctionExpressionParametersTypes(Expression mayBeClosure, Type2 mayByFunctionType) {
+    // prepare closure
     if (mayBeClosure is! FunctionExpression) {
       return;
     }
     FunctionExpression closure = mayBeClosure as FunctionExpression;
+    // prepare expected closure type
     if (mayByFunctionType is! FunctionType) {
       return;
     }
     FunctionType expectedClosureType = mayByFunctionType as FunctionType;
+    // set propagated type for the closure
     closure.propagatedType = expectedClosureType;
+    // set inferred types for parameters
     NodeList<FormalParameter> parameters = closure.parameters.parameters;
     List<ParameterElement> expectedParameters = expectedClosureType.parameters;
     for (int i = 0; i < parameters.length && i < expectedParameters.length; i++) {
       FormalParameter parameter = parameters[i];
       ParameterElement element = parameter.element;
       Type2 currentType = getBestType(element);
+      // may be override the type
       Type2 expectedType = expectedParameters[i].type;
       if (currentType == null || expectedType.isMoreSpecificThan(currentType)) {
         _overrideManager.setType(element, expectedType);
       }
     }
   }
 
   /**
    * Try to infer types of parameters of the [FunctionExpression] arguments.
    */
@@ skipping 10 matching lines @@
   }
 
   /**
    * Return `true` if the given expression terminates abruptly (that is, if any expression
    * following the given expression will not be reached).
    *
    * @param expression the expression being tested
    * @return `true` if the given expression terminates abruptly
    */
   bool isAbruptTermination(Expression expression) {
+    // TODO(brianwilkerson) This needs to be significantly improved. Ideally we would eventually
+    // turn this into a method on Expression that returns a termination indication (normal, abrupt
+    // with no exception, abrupt with an exception).
     while (expression is ParenthesizedExpression) {
       expression = (expression as ParenthesizedExpression).expression;
     }
     return expression is ThrowExpression || expression is RethrowExpression;
   }
 
   /**
    * Return `true` if the given statement terminates abruptly (that is, if any statement
    * following the given statement will not be reached).
    *
    * @param statement the statement being tested
    * @return `true` if the given statement terminates abruptly
    */
   bool isAbruptTermination2(Statement statement) {
+    // TODO(brianwilkerson) This needs to be significantly improved. Ideally we would eventually
+    // turn this into a method on Statement that returns a termination indication (normal, abrupt
+    // with no exception, abrupt with an exception).
     if (statement is ReturnStatement || statement is BreakStatement || statement is ContinueStatement) {
       return true;
     } else if (statement is ExpressionStatement) {
       return isAbruptTermination(statement.expression);
     } else if (statement is Block) {
       NodeList<Statement> statements = statement.statements;
       int size = statements.length;
       if (size == 0) {
         return false;
       }
@@ skipping 36 matching lines @@
    * the given expression with the given type. Generally speaking, it is appropriate if the given
    * type is more specific than the current type.
    *
    * @param expression the expression used to access the static element whose types might be
    *          promoted
    * @param potentialType the potential type of the elements
    */
   void promote(Expression expression, Type2 potentialType) {
     VariableElement element = getPromotionStaticElement(expression);
     if (element != null) {
+      // may be mutated somewhere in closure
       if ((element as VariableElementImpl).isPotentiallyMutatedInClosure) {
         return;
       }
+      // prepare current variable type
       Type2 type = _promoteManager.getType(element);
       if (type == null) {
         type = expression.staticType;
       }
+      // Declared type should not be "dynamic".
       if (type == null || type.isDynamic) {
         return;
       }
+      // Promoted type should not be "dynamic".
       if (potentialType == null || potentialType.isDynamic) {
         return;
       }
+      // Promoted type should be more specific than declared.
       if (!potentialType.isMoreSpecificThan(type)) {
         return;
       }
+      // Do promote type of variable.
       _promoteManager.setType(element, potentialType);
     }
   }
 
   /**
    * Promotes type information using given condition.
    */
   void promoteTypes(Expression condition) {
     if (condition is BinaryExpression) {
       BinaryExpression binary = condition;
@@ skipping 378 matching lines @@
       visitForEachStatementInScope(node);
     } finally {
       _labelScope = outerLabelScope;
       _nameScope = outerNameScope;
     }
     return null;
   }
 
   Object visitFormalParameterList(FormalParameterList node) {
     super.visitFormalParameterList(node);
+    // We finished resolving function signature, now include formal parameters scope.
     if (_nameScope is FunctionScope) {
       (_nameScope as FunctionScope).defineParameters();
     }
     if (_nameScope is FunctionTypeScope) {
       (_nameScope as FunctionTypeScope).defineParameters();
     }
     return null;
   }
 
   Object visitForStatement(ForStatement node) {
@@ skipping 20 matching lines @@
       _nameScope = outerScope;
     }
     if (function.enclosingElement is! CompilationUnitElement) {
       _nameScope.define(function);
     }
     return null;
   }
 
   Object visitFunctionExpression(FunctionExpression node) {
     if (node.parent is FunctionDeclaration) {
+      // We have already created a function scope and don't need to do so again.
       super.visitFunctionExpression(node);
     } else {
       Scope outerScope = _nameScope;
       try {
         ExecutableElement functionElement = node.element;
         if (functionElement == null) {
         } else {
           _nameScope = new FunctionScope(_nameScope, functionElement);
         }
         super.visitFunctionExpression(node);
@@ skipping 167 matching lines @@
   }
 
   /**
    * Visit the given statement after it's scope has been created. This replaces the normal call to
    * the inherited visit method so that ResolverVisitor can intervene when type propagation is
    * enabled.
    *
    * @param node the statement to be visited
    */
   void visitForEachStatementInScope(ForEachStatement node) {
+    //
+    // We visit the iterator before the loop variable because the loop variable cannot be in scope
+    // while visiting the iterator.
+    //
     safelyVisit(node.identifier);
     safelyVisit(node.iterator);
     safelyVisit(node.loopVariable);
     visitStatementInScope(node.body);
   }
 
   /**
    * Visit the given statement after it's scope has been created. This replaces the normal call to
    * the inherited visit method so that ResolverVisitor can intervene when type propagation is
    * enabled.
    *
    * @param node the statement to be visited
    */
   void visitForStatementInScope(ForStatement node) {
     safelyVisit(node.variables);
     safelyVisit(node.initialization);
     safelyVisit(node.condition);
     node.updaters.accept(this);
     visitStatementInScope(node.body);
   }
 
   /**
    * Visit the given statement after it's scope has been created. This is used by ResolverVisitor to
    * correctly visit the 'then' and 'else' statements of an 'if' statement.
    *
    * @param node the statement to be visited
    */
   void visitStatementInScope(Statement node) {
     if (node is Block) {
+      // Don't create a scope around a block because the block will create it's own scope.
       visitBlock(node);
     } else if (node != null) {
       Scope outerNameScope = _nameScope;
       try {
         _nameScope = new EnclosedScope(_nameScope);
         node.accept(this);
       } finally {
         _nameScope = outerNameScope;
       }
     }
@@ skipping 364 matching lines @@
    *
    * It is a static type warning if the type of e<sub>1</sub> may not be assigned to `bool`.
    *
    * The static type of <i>c</i> is the least upper bound of the static type of <i>e<sub>2</sub></i>
    * and the static type of <i>e<sub>3</sub></i>.</blockquote>
    */
   Object visitConditionalExpression(ConditionalExpression node) {
     Type2 staticThenType = getStaticType(node.thenExpression);
     Type2 staticElseType = getStaticType(node.elseExpression);
     if (staticThenType == null) {
+      // TODO(brianwilkerson) Determine whether this can still happen.
       staticThenType = _dynamicType;
     }
     if (staticElseType == null) {
+      // TODO(brianwilkerson) Determine whether this can still happen.
       staticElseType = _dynamicType;
     }
     Type2 staticType = staticThenType.getLeastUpperBound(staticElseType);
     if (staticType == null) {
       staticType = _dynamicType;
     }
     recordStaticType(node, staticType);
     Type2 propagatedThenType = node.thenExpression.propagatedType;
     Type2 propagatedElseType = node.elseExpression.propagatedType;
     if (propagatedThenType != null || propagatedElseType != null) {
@@ skipping 54 matching lines @@
    *
    * The static type of a function literal of the form <i>(T<sub>1</sub> a<sub>1</sub>, &hellip;,
    * T<sub>n</sub> a<sub>n</sub>, {T<sub>n+1</sub> x<sub>n+1</sub> : d1, &hellip;, T<sub>n+k</sub>
    * x<sub>n+k</sub> : dk}) {s}</i> is <i>(T<sub>1</sub>, &hellip;, T<sub>n</sub>, {T<sub>n+1</sub>
    * x<sub>n+1</sub>, &hellip;, T<sub>n+k</sub> x<sub>n+k</sub>}) &rarr; dynamic</i>. In any case
    * where <i>T<sub>i</sub>, 1 &lt;= i &lt;= n</i>, is not specified, it is considered to have been
    * specified as dynamic.</blockquote>
    */
   Object visitFunctionExpression(FunctionExpression node) {
     if (node.parent is FunctionDeclaration) {
+      // The function type will be resolved and set when we visit the parent node.
       return null;
     }
     ExecutableElementImpl functionElement = node.element as ExecutableElementImpl;
     functionElement.returnType = computeStaticReturnType3(node);
     recordPropagatedType(functionElement, node.body);
     recordStaticType(node, node.element.type);
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.14.4: <blockquote>A function expression invocation <i>i</i>
    * has the form <i>e<sub>f</sub>(a<sub>1</sub>, &hellip;, a<sub>n</sub>, x<sub>n+1</sub>:
    * a<sub>n+1</sub>, &hellip;, x<sub>n+k</sub>: a<sub>n+k</sub>)</i>, where <i>e<sub>f</sub></i> is
    * an expression.
    *
    * It is a static type warning if the static type <i>F</i> of <i>e<sub>f</sub></i> may not be
    * assigned to a function type.
    *
    * If <i>F</i> is not a function type, the static type of <i>i</i> is dynamic. Otherwise the
    * static type of <i>i</i> is the declared return type of <i>F</i>.</blockquote>
    */
   Object visitFunctionExpressionInvocation(FunctionExpressionInvocation node) {
     ExecutableElement staticMethodElement = node.staticElement;
+    // Record static return type of the static element.
     Type2 staticStaticType = computeStaticReturnType(staticMethodElement);
     recordStaticType(node, staticStaticType);
+    // Record propagated return type of the static element.
     Type2 staticPropagatedType = computePropagatedReturnType(staticMethodElement);
     if (staticPropagatedType != null && (staticStaticType == null || staticPropagatedType.isMoreSpecificThan(staticStaticType))) {
       recordPropagatedType2(node, staticPropagatedType);
     }
     ExecutableElement propagatedMethodElement = node.propagatedElement;
     if (propagatedMethodElement != staticMethodElement) {
+      // Record static return type of the propagated element.
       Type2 propagatedStaticType = computeStaticReturnType(propagatedMethodElement);
       if (propagatedStaticType != null && (staticStaticType == null || propagatedStaticType.isMoreSpecificThan(staticStaticType)) && (staticPropagatedType == null || propagatedStaticType.isMoreSpecificThan(staticPropagatedType))) {
         recordPropagatedType2(node, propagatedStaticType);
       }
+      // Record propagated return type of the propagated element.
       Type2 propagatedPropagatedType = computePropagatedReturnType(propagatedMethodElement);
       if (propagatedPropagatedType != null && (staticStaticType == null || propagatedPropagatedType.isMoreSpecificThan(staticStaticType)) && (staticPropagatedType == null || propagatedPropagatedType.isMoreSpecificThan(staticPropagatedType)) && (propagatedStaticType == null || propagatedPropagatedType.isMoreSpecificThan(propagatedStaticType))) {
         recordPropagatedType2(node, propagatedPropagatedType);
       }
     }
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.29: <blockquote>An assignable expression of the form
@@ skipping 229 matching lines @@
    * <i>S.m</i> exists, it is a static warning if the type <i>F</i> of <i>S.m</i> may not be
    * assigned to a function type.
    *
    * If <i>S.m</i> does not exist, or if <i>F</i> is not a function type, the static type of
    * <i>i</i> is dynamic. Otherwise the static type of <i>i</i> is the declared return type of
    * <i>F</i>.</blockquote>
    */
   Object visitMethodInvocation(MethodInvocation node) {
     SimpleIdentifier methodNameNode = node.methodName;
     Element staticMethodElement = methodNameNode.staticElement;
+    // Record types of the local variable invoked as a function.
     if (staticMethodElement is LocalVariableElement) {
       LocalVariableElement variable = staticMethodElement;
       Type2 staticType = variable.type;
       recordStaticType(methodNameNode, staticType);
       Type2 propagatedType = _overrideManager.getType(variable);
       if (propagatedType != null && propagatedType.isMoreSpecificThan(staticType)) {
         recordPropagatedType2(methodNameNode, propagatedType);
       }
     }
+    // Record static return type of the static element.
     Type2 staticStaticType = computeStaticReturnType(staticMethodElement);
     recordStaticType(node, staticStaticType);
+    // Record propagated return type of the static element.
     Type2 staticPropagatedType = computePropagatedReturnType(staticMethodElement);
     if (staticPropagatedType != null && (staticStaticType == null || staticPropagatedType.isMoreSpecificThan(staticStaticType))) {
       recordPropagatedType2(node, staticPropagatedType);
     }
     String methodName = methodNameNode.name;
+    // Future.then(closure) return type is:
+    // 1) the returned Future type, if the closure returns a Future;
+    // 2) Future<valueType>, if the closure returns a value.
     if (methodName == "then") {
       Expression target = node.realTarget;
       Type2 targetType = target == null ? null : target.bestType;
       if (isAsyncFutureType(targetType)) {
         NodeList<Expression> arguments = node.argumentList.arguments;
         if (arguments.length == 1) {
+          // TODO(brianwilkerson) Handle the case where both arguments are provided.
           Expression closureArg = arguments[0];
           if (closureArg is FunctionExpression) {
             FunctionExpression closureExpr = closureArg;
             Type2 returnType = computePropagatedReturnType(closureExpr.element);
             if (returnType != null) {
+              // prepare the type of the returned Future
               InterfaceTypeImpl newFutureType;
               if (isAsyncFutureType(returnType)) {
                 newFutureType = returnType as InterfaceTypeImpl;
               } else {
                 InterfaceType futureType = targetType as InterfaceType;
                 newFutureType = new InterfaceTypeImpl.con1(futureType.element);
                 newFutureType.typeArguments = <Type2> [returnType];
               }
+              // set the 'then' invocation type
               recordPropagatedType2(node, newFutureType);
               return null;
             }
           }
         }
       }
     }
     if (methodName == "\$dom_createEvent") {
       Expression target = node.realTarget;
       if (target != null) {
@@ skipping 46 matching lines @@
         }
       }
     } else if (methodName == "JS") {
       Type2 returnType = getFirstArgumentAsType(_typeProvider.objectType.element.library, node.argumentList);
       if (returnType != null) {
         recordPropagatedType2(node, returnType);
       }
     } else {
       Element propagatedElement = methodNameNode.propagatedElement;
       if (propagatedElement != staticMethodElement) {
+        // Record static return type of the propagated element.
         Type2 propagatedStaticType = computeStaticReturnType(propagatedElement);
         if (propagatedStaticType != null && (staticStaticType == null || propagatedStaticType.isMoreSpecificThan(staticStaticType)) && (staticPropagatedType == null || propagatedStaticType.isMoreSpecificThan(staticPropagatedType))) {
           recordPropagatedType2(node, propagatedStaticType);
         }
+        // Record propagated return type of the propagated element.
         Type2 propagatedPropagatedType = computePropagatedReturnType(propagatedElement);
         if (propagatedPropagatedType != null && (staticStaticType == null || propagatedPropagatedType.isMoreSpecificThan(staticStaticType)) && (staticPropagatedType == null || propagatedPropagatedType.isMoreSpecificThan(staticPropagatedType)) && (propagatedStaticType == null || propagatedPropagatedType.isMoreSpecificThan(propagatedStaticType))) {
           recordPropagatedType2(node, propagatedPropagatedType);
         }
       }
     }
     return null;
   }
 
   Object visitNamedExpression(NamedExpression node) {
@@ skipping 127 matching lines @@
   /**
    * The Dart Language Specification, 12.27: <blockquote>A unary expression <i>u</i> of the form
    * <i>op e</i> is equivalent to a method invocation <i>expression e.op()</i>. An expression of the
    * form <i>op super</i> is equivalent to the method invocation <i>super.op()<i>.</blockquote>
    */
   Object visitPrefixExpression(PrefixExpression node) {
     sc.TokenType operator = node.operator.type;
     if (identical(operator, sc.TokenType.BANG)) {
       recordStaticType(node, _typeProvider.boolType);
     } else {
+      // The other cases are equivalent to invoking a method.
       ExecutableElement staticMethodElement = node.staticElement;
       Type2 staticType = computeStaticReturnType(staticMethodElement);
       if (identical(operator, sc.TokenType.MINUS_MINUS) || identical(operator, sc.TokenType.PLUS_PLUS)) {
         Type2 intType = _typeProvider.intType;
         if (identical(getStaticType(node.operand), intType)) {
           staticType = intType;
         }
       }
       recordStaticType(node, staticType);
       MethodElement propagatedMethodElement = node.propagatedElement;
@@ skipping 55 matching lines @@
     Element element = propertyName.staticElement;
     Type2 staticType = _dynamicType;
     if (element is MethodElement) {
       staticType = element.type;
     } else if (element is PropertyAccessorElement) {
       staticType = getType(element, node.target != null ? getStaticType(node.target) : null);
     } else {
     }
     recordStaticType(propertyName, staticType);
     recordStaticType(node, staticType);
+    // TODO(brianwilkerson) I think we want to repeat the logic above using the propagated element
+    // to get another candidate for the propagated type.
     Type2 propagatedType = _overrideManager.getType(element);
     if (propagatedType != null && propagatedType.isMoreSpecificThan(staticType)) {
       recordPropagatedType2(node, propagatedType);
     }
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.9: <blockquote>The static type of a rethrow expression is
    * bottom.</blockquote>
@@ skipping 60 matching lines @@
       } else {
         staticType = _typeProvider.typeType;
       }
     } else if (element is MethodElement) {
       staticType = element.type;
     } else if (element is PropertyAccessorElement) {
       staticType = getType(element, null);
     } else if (element is ExecutableElement) {
       staticType = element.type;
     } else if (element is TypeParameterElement) {
+      //      if (isTypeName(node)) {
       staticType = element.type;
     } else if (element is VariableElement) {
       VariableElement variable = element;
       staticType = _promoteManager.getStaticType(variable);
     } else if (element is PrefixElement) {
       return null;
     } else {
       staticType = _dynamicType;
     }
     recordStaticType(node, staticType);
+    // TODO(brianwilkerson) I think we want to repeat the logic above using the propagated element
+    // to get another candidate for the propagated type.
     Type2 propagatedType = _overrideManager.getType(element);
     if (propagatedType != null && propagatedType.isMoreSpecificThan(staticType)) {
       recordPropagatedType2(node, propagatedType);
     }
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.5: <blockquote>The static type of a string literal is
    * `String`.</blockquote>
    */
   Object visitSimpleStringLiteral(SimpleStringLiteral node) {
     recordStaticType(node, _typeProvider.stringType);
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.5: <blockquote>The static type of a string literal is
    * `String`.</blockquote>
    */
   Object visitStringInterpolation(StringInterpolation node) {
     recordStaticType(node, _typeProvider.stringType);
     return null;
   }
 
   Object visitSuperExpression(SuperExpression node) {
     if (_thisType == null) {
+      // TODO(brianwilkerson) Report this error if it hasn't already been reported
       recordStaticType(node, _dynamicType);
     } else {
       recordStaticType(node, _thisType);
     }
     return null;
   }
 
   Object visitSymbolLiteral(SymbolLiteral node) {
     recordStaticType(node, _typeProvider.symbolType);
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.10: <blockquote>The static type of `this` is the
    * interface of the immediately enclosing class.</blockquote>
    */
   Object visitThisExpression(ThisExpression node) {
     if (_thisType == null) {
+      // TODO(brianwilkerson) Report this error if it hasn't already been reported
       recordStaticType(node, _dynamicType);
     } else {
       recordStaticType(node, _thisType);
     }
     return null;
   }
 
   /**
    * The Dart Language Specification, 12.8: <blockquote>The static type of a throw expression is
    * bottom.</blockquote>
@@ skipping 68 matching lines @@
   }
 
   /**
    * Compute the static return type of the method or function represented by the given element.
    *
    * @param element the element representing the method or function invoked by the given node
    * @return the static return type that was computed
    */
   Type2 computeStaticReturnType(Element element) {
     if (element is PropertyAccessorElement) {
+      //
+      // This is a function invocation expression disguised as something else. We are invoking a
+      // getter and then invoking the returned function.
+      //
       FunctionType propertyType = element.type;
       if (propertyType != null) {
         Type2 returnType = propertyType.returnType;
         if (returnType.isDartCoreFunction) {
           return _dynamicType;
         } else if (returnType is InterfaceType) {
           MethodElement callMethod = returnType.lookUpMethod(ElementResolver.CALL_METHOD_NAME, _resolver.definingLibrary);
           if (callMethod != null) {
             return callMethod.type.returnType;
           }
         } else if (returnType is FunctionType) {
           Type2 innerReturnType = returnType.returnType;
           if (innerReturnType != null) {
             return innerReturnType;
           }
         }
         if (returnType != null) {
           return returnType;
         }
       }
     } else if (element is ExecutableElement) {
       FunctionType type = element.type;
       if (type != null) {
+        // TODO(brianwilkerson) Figure out the conditions under which the type is null.
         return type.returnType;
       }
     } else if (element is VariableElement) {
       VariableElement variable = element;
       Type2 variableType = _promoteManager.getStaticType(variable);
       if (variableType is FunctionType) {
         return variableType.returnType;
       }
     }
     return _dynamicType;
@@ skipping 58 matching lines @@
    * string literal, then parse that argument as a query string and return the type specified by the
    * argument.
    *
    * @param library the library in which the specified type would be defined
    * @param argumentList the list of arguments from which a type is to be extracted
    * @return the type specified by the first argument in the argument list
    */
   Type2 getFirstArgumentAsQuery(LibraryElement library, ArgumentList argumentList) {
     String argumentValue = getFirstArgumentAsString(argumentList);
     if (argumentValue != null) {
+      //
+      // If the query has spaces, full parsing is required because it might be:
+      //   E[text='warning text']
+      //
       if (argumentValue.contains(" ")) {
         return null;
       }
+      //
+      // Otherwise, try to extract the tag based on http://www.w3.org/TR/CSS2/selector.html.
+      //
       String tag = argumentValue;
       tag = StringUtilities.substringBefore(tag, ":");
       tag = StringUtilities.substringBefore(tag, "[");
       tag = StringUtilities.substringBefore(tag, ".");
       tag = StringUtilities.substringBefore(tag, "#");
       tag = _HTML_ELEMENT_TO_CLASS_MAP[tag.toLowerCase()];
       ClassElement returnType = library.getType(tag);
       if (returnType != null) {
         return returnType.type;
       }
@@ skipping 44 matching lines @@
 
   /**
    * Return the static type of the given expression.
    *
    * @param expression the expression whose type is to be returned
    * @return the static type of the given expression
    */
   Type2 getStaticType(Expression expression) {
     Type2 type = expression.staticType;
     if (type == null) {
+      // TODO(brianwilkerson) Determine the conditions for which the static type is null.
       return _dynamicType;
     }
     return type;
   }
 
   /**
    * Return the type that should be recorded for a node that resolved to the given accessor.
    *
    * @param accessor the accessor that the node resolved to
    * @param context if the accessor element has context [by being the RHS of a
    *          [PrefixedIdentifier] or [PropertyAccess]], and the return type of the
    *          accessor is a parameter type, then the type of the LHS can be used to get more
    *          specific type information
    * @return the type that should be recorded for a node that resolved to the given accessor
    */
   Type2 getType(PropertyAccessorElement accessor, Type2 context) {
     FunctionType functionType = accessor.type;
     if (functionType == null) {
+      // TODO(brianwilkerson) Report this internal error. This happens when we are analyzing a
+      // reference to a property before we have analyzed the declaration of the property or when
+      // the property does not have a defined type.
       return _dynamicType;
     }
     if (accessor.isSetter) {
       List<Type2> parameterTypes = functionType.normalParameterTypes;
       if (parameterTypes != null && parameterTypes.length > 0) {
         return parameterTypes[0];
       }
       PropertyAccessorElement getter = accessor.variable.getter;
       if (getter != null) {
         functionType = getter.type;
         if (functionType != null) {
           return functionType.returnType;
         }
       }
       return _dynamicType;
     }
     Type2 returnType = functionType.returnType;
     if (returnType is TypeParameterType && context is InterfaceType) {
+      // if the return type is a TypeParameter, we try to use the context [that the function is being
+      // called on] to get a more accurate returnType type
       InterfaceType interfaceTypeContext = context;
+      //      Type[] argumentTypes = interfaceTypeContext.getTypeArguments();
       List<TypeParameterElement> typeParameterElements = interfaceTypeContext.element != null ? interfaceTypeContext.element.typeParameters : null;
       if (typeParameterElements != null) {
         for (int i = 0; i < typeParameterElements.length; i++) {
           TypeParameterElement typeParameterElement = typeParameterElements[i];
           if (returnType.name == typeParameterElement.name) {
             return interfaceTypeContext.typeArguments[i];
           }
         }
       }
     }
     return returnType;
   }
 
   /**
    * Return the type represented by the given type name.
    *
    * @param typeName the type name representing the type to be returned
    * @return the type represented by the type name
    */
   Type2 getType2(TypeName typeName) {
     Type2 type = typeName.type;
     if (type == null) {
+      //TODO(brianwilkerson) Determine the conditions for which the type is null.
       return _dynamicType;
     }
     return type;
   }
 
   /**
    * Return `true` if the given [Type] is the `Future` form the 'dart:async'
    * library.
    */
   bool isAsyncFutureType(Type2 type) => type is InterfaceType && type.name == "Future" && isAsyncLibrary(type.element.library);
@@ skipping 32 matching lines @@
    * @param functionElement the function element to record propagated return type for
    * @param body the boy of the function whose propagated return type is to be computed
    * @return the propagated return type that was computed, may be `null` if it is not more
    *         specific than the static return type.
    */
   void recordPropagatedType(ExecutableElement functionElement, FunctionBody body) {
     Type2 propagatedReturnType = computePropagatedReturnType2(body);
     if (propagatedReturnType == null) {
       return;
     }
+    // Ignore 'bottom' type.
     if (propagatedReturnType.isBottom) {
       return;
     }
+    // Record only if we inferred more specific type.
     Type2 staticReturnType = functionElement.returnType;
     if (!propagatedReturnType.isMoreSpecificThan(staticReturnType)) {
       return;
     }
+    // OK, do record.
     _propagatedReturnTypes[functionElement] = propagatedReturnType;
   }
 
   /**
    * Record that the propagated type of the given node is the given type.
    *
    * @param expression the node whose type is to be recorded
    * @param type the propagated type of the node
    */
   void recordPropagatedType2(Expression expression, Type2 type) {
@@ skipping 18 matching lines @@
 
   /**
    * Attempts to make a better guess for the static type of the given binary expression.
    *
    * @param node the binary expression to analyze
    * @param staticType the static type of the expression as resolved
    * @return the better type guess, or the same static type as given
    */
   Type2 refineBinaryExpressionType(BinaryExpression node, Type2 staticType) {
     sc.TokenType operator = node.operator.type;
+    // bool
     if (identical(operator, sc.TokenType.AMPERSAND_AMPERSAND) || identical(operator, sc.TokenType.BAR_BAR) || identical(operator, sc.TokenType.EQ_EQ) || identical(operator, sc.TokenType.BANG_EQ)) {
       return _typeProvider.boolType;
     }
     Type2 intType = _typeProvider.intType;
     if (getStaticType(node.leftOperand) == intType) {
+      // int op double
       if (identical(operator, sc.TokenType.MINUS) || identical(operator, sc.TokenType.PERCENT) || identical(operator, sc.TokenType.PLUS) || identical(operator, sc.TokenType.STAR)) {
         Type2 doubleType = _typeProvider.doubleType;
         if (getStaticType(node.rightOperand) == doubleType) {
           return doubleType;
         }
       }
+      // int op int
       if (identical(operator, sc.TokenType.MINUS) || identical(operator, sc.TokenType.PERCENT) || identical(operator, sc.TokenType.PLUS) || identical(operator, sc.TokenType.STAR) || identical(operator, sc.TokenType.TILDE_SLASH)) {
         if (getStaticType(node.rightOperand) == intType) {
           staticType = intType;
         }
       }
     }
+    // default
     return staticType;
   }
 
   get thisType_J2DAccessor => _thisType;
 
   set thisType_J2DAccessor(__v) => _thisType = __v;
 }
 
 class GeneralizingASTVisitor_StaticTypeAnalyzer_computePropagatedReturnType2 extends GeneralizingASTVisitor<Object> {
   List<Type2> result;
 
   GeneralizingASTVisitor_StaticTypeAnalyzer_computePropagatedReturnType2(this.result) : super();
 
   Object visitExpression(Expression node) => null;
 
   Object visitReturnStatement(ReturnStatement node) {
+    // prepare this 'return' type
     Type2 type;
     Expression expression = node.expression;
     if (expression != null) {
       type = expression.bestType;
     } else {
       type = BottomTypeImpl.instance;
     }
+    // merge types
     if (result[0] == null) {
       result[0] = type;
     } else {
       result[0] = result[0].getLeastUpperBound(type);
     }
     return null;
   }
 }
 
 /**
@@ skipping 12 matching lines @@
    * libraries visited by this manager.
    */
   Set<LibraryElement> _visitedLibraries = new Set<LibraryElement>();
 
   /**
    * Given some [ClassElement], return the set of all subtypes, and subtypes of subtypes.
    *
    * @param classElement the class to recursively return the set of subtypes of
    */
   Set<ClassElement> computeAllSubtypes(ClassElement classElement) {
+    // Ensure that we have generated the subtype map for the library
     computeSubtypesInLibrary(classElement.library);
+    // use the subtypeMap to compute the set of all subtypes and subtype's subtypes
     Set<ClassElement> allSubtypes = new Set<ClassElement>();
     computeAllSubtypes2(classElement, new Set<ClassElement>(), allSubtypes);
     return allSubtypes;
   }
 
   /**
    * Given some [LibraryElement], visit all of the types in the library, the passed library,
    * and any imported libraries, will be in the [visitedLibraries] set.
    *
    * @param libraryElement the library to visit, it it hasn't been visited already
    */
   void ensureLibraryVisited(LibraryElement libraryElement) {
     computeSubtypesInLibrary(libraryElement);
   }
 
   /**
    * Given some [ClassElement] and a [HashSet<ClassElement>], this method recursively
    * adds all of the subtypes of the [ClassElement] to the passed array.
    *
    * @param classElement the type to compute the set of subtypes of
    * @param visitedClasses the set of class elements that this method has already recursively seen
    * @param allSubtypes the computed set of subtypes of the passed class element
    */
   void computeAllSubtypes2(ClassElement classElement, Set<ClassElement> visitedClasses, Set<ClassElement> allSubtypes) {
     if (!visitedClasses.add(classElement)) {
+      // if this class has already been called on this class element
       return;
     }
     Set<ClassElement> subtypes = _subtypeMap[classElement];
     if (subtypes == null) {
       return;
     }
     for (ClassElement subtype in subtypes) {
       computeAllSubtypes2(subtype, visitedClasses, allSubtypes);
     }
     allSubtypes.addAll(subtypes);
@@ skipping 782 matching lines @@
    *          during resolution
    */
   TypeResolverVisitor.con3(LibraryElement definingLibrary, Source source, TypeProvider typeProvider, Scope nameScope, AnalysisErrorListener errorListener) : super.con3(definingLibrary, source, typeProvider, nameScope, errorListener) {
     _dynamicType = typeProvider.dynamicType;
   }
 
   Object visitCatchClause(CatchClause node) {
     super.visitCatchClause(node);
     SimpleIdentifier exception = node.exceptionParameter;
     if (exception != null) {
+      // If an 'on' clause is provided the type of the exception parameter is the type in the 'on'
+      // clause. Otherwise, the type of the exception parameter is 'Object'.
       TypeName exceptionTypeName = node.exceptionType;
       Type2 exceptionType;
       if (exceptionTypeName == null) {
         exceptionType = typeProvider.dynamicType;
       } else {
         exceptionType = getType3(exceptionTypeName);
       }
       recordType(exception, exceptionType);
       Element element = exception.staticElement;
       if (element is VariableElementImpl) {
@@ skipping 70 matching lines @@
     } else {
       declaredType = getType3(typeName);
     }
     LocalVariableElementImpl element = node.element as LocalVariableElementImpl;
     element.type = declaredType;
     return null;
   }
 
   Object visitDefaultFormalParameter(DefaultFormalParameter node) {
     super.visitDefaultFormalParameter(node);
+    //    Expression defaultValue = node.getDefaultValue();
+    //    if (defaultValue != null) {
+    //      Type valueType = getType(defaultValue);
+    //      Type parameterType = getType(node.getParameter());
+    //      if (!valueType.isAssignableTo(parameterType)) {
+    // TODO(brianwilkerson) Determine whether this is really an error. I can't find in the spec
+    // anything that says it is, but a side comment from Gilad states that it should be a static
+    // warning.
+    //        resolver.reportError(ResolverErrorCode.?, defaultValue);
+    //      }
+    //    }
     return null;
   }
 
   Object visitFieldFormalParameter(FieldFormalParameter node) {
     super.visitFieldFormalParameter(node);
     Element element = node.identifier.staticElement;
     if (element is ParameterElementImpl) {
       ParameterElementImpl parameter = element;
       FormalParameterList parameterList = node.parameters;
       if (parameterList == null) {
         Type2 type;
         TypeName typeName = node.type;
         if (typeName == null) {
+          // TODO(brianwilkerson) Find the field's declaration and use it's type.
           type = _dynamicType;
         } else {
           type = getType3(typeName);
         }
         parameter.type = type;
       } else {
         setFunctionTypedParameterType(parameter, node.type, node.parameters);
       }
     } else {
     }
@@ skipping 76 matching lines @@
     _hasReferenceToSuper = true;
     return super.visitSuperExpression(node);
   }
 
   Object visitTypeName(TypeName node) {
     super.visitTypeName(node);
     Identifier typeName = node.name;
     TypeArgumentList argumentList = node.typeArguments;
     Element element = nameScope.lookup(typeName, definingLibrary);
     if (element == null) {
+      //
+      // Check to see whether the type name is either 'dynamic' or 'void', neither of which are in
+      // the name scope and hence will not be found by normal means.
+      //
       if (typeName.name == this._dynamicType.name) {
         setElement(typeName, this._dynamicType.element);
         if (argumentList != null) {
         }
         typeName.staticType = this._dynamicType;
         node.type = this._dynamicType;
         return null;
       }
       VoidTypeImpl voidType = VoidTypeImpl.instance;
       if (typeName.name == voidType.name) {
+        // There is no element for 'void'.
         if (argumentList != null) {
         }
         typeName.staticType = voidType;
         node.type = voidType;
         return null;
       }
+      //
+      // If not, the look to see whether we might have created the wrong AST structure for a
+      // constructor name. If so, fix the AST structure and then proceed.
+      //
       ASTNode parent = node.parent;
       if (typeName is PrefixedIdentifier && parent is ConstructorName && argumentList == null) {
         ConstructorName name = parent;
         if (name.name == null) {
           PrefixedIdentifier prefixedIdentifier = typeName as PrefixedIdentifier;
           SimpleIdentifier prefix = prefixedIdentifier.prefix;
           element = nameScope.lookup(prefix, definingLibrary);
           if (element is PrefixElement) {
             if (parent.parent is InstanceCreationExpression && (parent.parent as InstanceCreationExpression).isConst) {
+              // If, if this is a const expression, then generate a
+              // CompileTimeErrorCode.CONST_WITH_NON_TYPE error.
               reportError7(CompileTimeErrorCode.CONST_WITH_NON_TYPE, prefixedIdentifier.identifier, [prefixedIdentifier.identifier.name]);
             } else {
+              // Else, if this expression is a new expression, report a NEW_WITH_NON_TYPE warning.
               reportError7(StaticWarningCode.NEW_WITH_NON_TYPE, prefixedIdentifier.identifier, [prefixedIdentifier.identifier.name]);
             }
             setElement(prefix, element);
             return null;
           } else if (element != null) {
+            //
+            // Rewrite the constructor name. The parser, when it sees a constructor named "a.b",
+            // cannot tell whether "a" is a prefix and "b" is a class name, or whether "a" is a
+            // class name and "b" is a constructor name. It arbitrarily chooses the former, but
+            // in this case was wrong.
+            //
             name.name = prefixedIdentifier.identifier;
             name.period = prefixedIdentifier.period;
             node.name = prefix;
             typeName = prefix;
           }
         }
       }
     }
+    // check element
     bool elementValid = element is! MultiplyDefinedElement;
     if (elementValid && element is! ClassElement && isTypeNameInInstanceCreationExpression(node)) {
       SimpleIdentifier typeNameSimple = getTypeSimpleIdentifier(typeName);
       InstanceCreationExpression creation = node.parent.parent as InstanceCreationExpression;
       if (creation.isConst) {
         if (element == null) {
           reportError7(CompileTimeErrorCode.UNDEFINED_CLASS, typeNameSimple, [typeName]);
         } else {
           reportError7(CompileTimeErrorCode.CONST_WITH_NON_TYPE, typeNameSimple, [typeName]);
         }
         elementValid = false;
       } else {
         if (element != null) {
           reportError7(StaticWarningCode.NEW_WITH_NON_TYPE, typeNameSimple, [typeName]);
           elementValid = false;
         }
       }
     }
     if (elementValid && element == null) {
+      // We couldn't resolve the type name.
+      // TODO(jwren) Consider moving the check for CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE
+      // from the ErrorVerifier, so that we don't have two errors on a built in identifier being
+      // used as a class name. See CompileTimeErrorCodeTest.test_builtInIdentifierAsType().
       SimpleIdentifier typeNameSimple = getTypeSimpleIdentifier(typeName);
       RedirectingConstructorKind redirectingConstructorKind;
       if (isBuiltInIdentifier(node) && isTypeAnnotation(node)) {
         reportError7(CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE, typeName, [typeName.name]);
       } else if (typeNameSimple.name == "boolean") {
         reportError7(StaticWarningCode.UNDEFINED_CLASS_BOOLEAN, typeNameSimple, []);
       } else if (isTypeNameInCatchClause(node)) {
         reportError7(StaticWarningCode.NON_TYPE_IN_CATCH_CLAUSE, typeName, [typeName.name]);
       } else if (isTypeNameInAsExpression(node)) {
         reportError7(StaticWarningCode.CAST_TO_NON_TYPE, typeName, [typeName.name]);
@@ skipping 31 matching lines @@
       type = (element as TypeParameterElement).type;
       if (argumentList != null) {
       }
     } else if (element is MultiplyDefinedElement) {
       List<Element> elements = (element as MultiplyDefinedElement).conflictingElements;
       type = getType(elements);
       if (type != null) {
         node.type = type;
       }
     } else {
+      // The name does not represent a type.
       RedirectingConstructorKind redirectingConstructorKind;
       if (isTypeNameInCatchClause(node)) {
         reportError7(StaticWarningCode.NON_TYPE_IN_CATCH_CLAUSE, typeName, [typeName.name]);
       } else if (isTypeNameInAsExpression(node)) {
         reportError7(StaticWarningCode.CAST_TO_NON_TYPE, typeName, [typeName.name]);
       } else if (isTypeNameInIsExpression(node)) {
         reportError7(StaticWarningCode.TYPE_TEST_NON_TYPE, typeName, [typeName.name]);
       } else if ((redirectingConstructorKind = getRedirectingConstructorKind(node)) != null) {
         ErrorCode errorCode = (identical(redirectingConstructorKind, RedirectingConstructorKind.CONST) ? CompileTimeErrorCode.REDIRECT_TO_NON_CLASS : StaticWarningCode.REDIRECT_TO_NON_CLASS) as ErrorCode;
         reportError7(errorCode, typeName, [typeName.name]);
@@ skipping 25 matching lines @@
         Type2 argumentType = getType3(arguments[i]);
         if (argumentType != null) {
           typeArguments.add(argumentType);
         }
       }
       if (argumentCount != parameterCount) {
         reportError7(getInvalidTypeParametersErrorCode(node), node, [typeName.name, parameterCount, argumentCount]);
       }
       argumentCount = typeArguments.length;
       if (argumentCount < parameterCount) {
+        //
+        // If there were too many arguments, we already handled it by not adding the values of the
+        // extra arguments to the list. If there are too few, we handle it by adding 'dynamic'
+        // enough times to make the count equal.
+        //
         for (int i = argumentCount; i < parameterCount; i++) {
           typeArguments.add(this._dynamicType);
         }
       }
       if (type is InterfaceTypeImpl) {
         InterfaceTypeImpl interfaceType = type as InterfaceTypeImpl;
         type = interfaceType.substitute4(new List.from(typeArguments));
       } else if (type is FunctionTypeImpl) {
         FunctionTypeImpl functionType = type as FunctionTypeImpl;
         type = functionType.substitute3(new List.from(typeArguments));
       } else {
       }
     } else {
+      //
+      // Check for the case where there are no type arguments given for a parameterized type.
+      //
       List<Type2> parameters = getTypeArguments(type);
       int parameterCount = parameters.length;
       if (parameterCount > 0) {
         DynamicTypeImpl dynamicType = DynamicTypeImpl.instance;
         List<Type2> arguments = new List<Type2>(parameterCount);
         for (int i = 0; i < parameterCount; i++) {
           arguments[i] = dynamicType;
         }
         type = type.substitute2(arguments, parameters);
       }
@@ skipping 59 matching lines @@
     }
   }
 
   /**
    * Return the class element that represents the class whose name was provided.
    *
    * @param identifier the name from the declaration of a class
    * @return the class element that represents the class
    */
   ClassElementImpl getClassElement(SimpleIdentifier identifier) {
+    // TODO(brianwilkerson) Seems like we should be using ClassDeclaration.getElement().
     if (identifier == null) {
+      // TODO(brianwilkerson) Report this
+      // Internal error: We should never build a class declaration without a name.
       return null;
     }
     Element element = identifier.staticElement;
     if (element is! ClassElementImpl) {
+      // TODO(brianwilkerson) Report this
+      // Internal error: Failed to create an element for a class declaration.
       return null;
     }
     return element as ClassElementImpl;
   }
 
   /**
    * Return an array containing all of the elements associated with the parameters in the given
    * list.
    *
    * @param parameterList the list of parameters whose elements are to be returned
    * @return the elements associated with the parameters
    */
   List<ParameterElement> getElements(FormalParameterList parameterList) {
     List<ParameterElement> elements = new List<ParameterElement>();
     for (FormalParameter parameter in parameterList.parameters) {
       ParameterElement element = parameter.identifier.staticElement as ParameterElement;
+      // TODO(brianwilkerson) Understand why the element would be null.
       if (element != null) {
         elements.add(element);
       }
     }
     return new List.from(elements);
   }
 
   /**
    * The number of type arguments in the given type name does not match the number of parameters in
    * the corresponding class element. Return the error code that should be used to report this
@@ skipping 205 matching lines @@
       if (classElement != null) {
         classElement.mixins = mixinTypes;
       }
     }
     if (implementsClause != null) {
       NodeList<TypeName> interfaces = implementsClause.interfaces;
       List<InterfaceType> interfaceTypes = resolveTypes(interfaces, CompileTimeErrorCode.IMPLEMENTS_NON_CLASS, CompileTimeErrorCode.IMPLEMENTS_DYNAMIC);
       if (classElement != null) {
         classElement.interfaces = interfaceTypes;
       }
+      // TODO(brianwilkerson) Move the following checks to ErrorVerifier.
       List<TypeName> typeNames = new List.from(interfaces);
       List<bool> detectedRepeatOnIndex = new List<bool>.filled(typeNames.length, false);
       for (int i = 0; i < detectedRepeatOnIndex.length; i++) {
         detectedRepeatOnIndex[i] = false;
       }
       for (int i = 0; i < typeNames.length; i++) {
         TypeName typeName = typeNames[i];
         if (!detectedRepeatOnIndex[i]) {
           Element element = typeName.name.staticElement;
           for (int j = i + 1; j < typeNames.length; j++) {
@@ skipping 18 matching lines @@
    * @param nonTypeError the error to produce if the type name is defined to be something other than
    *          a type
    * @param dynamicTypeError the error to produce if the type name is "dynamic"
    * @return the type specified by the type name
    */
   InterfaceType resolveType(TypeName typeName, ErrorCode nonTypeError, ErrorCode dynamicTypeError) {
     Type2 type = typeName.type;
     if (type is InterfaceType) {
       return type;
     }
+    // If the type is not an InterfaceType, then visitTypeName() sets the type to be a DynamicTypeImpl
     Identifier name = typeName.name;
     if (name.name == sc.Keyword.DYNAMIC.syntax) {
       reportError7(dynamicTypeError, name, [name.name]);
     } else {
       reportError7(nonTypeError, name, [name.name]);
     }
     return null;
   }
 
   /**
@@ skipping 132 matching lines @@
         return super.visitFunctionExpression(node);
       } finally {
         _enclosingFunction = outerFunction;
       }
     } else {
       return super.visitFunctionExpression(node);
     }
   }
 
   Object visitSimpleIdentifier(SimpleIdentifier node) {
+    // Ignore if already resolved - declaration or type.
     if (node.staticElement != null) {
       return null;
     }
+    // Ignore if qualified.
     ASTNode parent = node.parent;
     if (parent is PrefixedIdentifier && identical(parent.identifier, node)) {
       return null;
     }
     if (parent is PropertyAccess && identical(parent.propertyName, node)) {
       return null;
     }
     if (parent is MethodInvocation && identical(parent.methodName, node)) {
       return null;
     }
     if (parent is ConstructorName) {
       return null;
     }
     if (parent is Label) {
       return null;
     }
+    // Prepare VariableElement.
     Element element = nameScope.lookup(node, definingLibrary);
     if (element is! VariableElement) {
       return null;
     }
+    // Must be local or parameter.
     ElementKind kind = element.kind;
     if (identical(kind, ElementKind.LOCAL_VARIABLE)) {
       node.staticElement = element;
       if (node.inSetterContext()) {
         LocalVariableElementImpl variableImpl = element as LocalVariableElementImpl;
         variableImpl.markPotentiallyMutatedInScope();
         if (element.enclosingElement != _enclosingFunction) {
           variableImpl.markPotentiallyMutatedInClosure();
         }
       }
     } else if (identical(kind, ElementKind.PARAMETER)) {
       node.staticElement = element;
       if (node.inSetterContext()) {
         ParameterElementImpl parameterImpl = element as ParameterElementImpl;
         parameterImpl.markPotentiallyMutatedInScope();
+        // If we are in some closure, check if it is not the same as where variable is declared.
         if (_enclosingFunction != null && (element.enclosingElement != _enclosingFunction)) {
           parameterImpl.markPotentiallyMutatedInClosure();
         }
       }
     }
     return null;
   }
 }
 
 /**
@@ skipping 99 matching lines @@
         _hasHiddenName = true;
       }
     }
   }
 
   Element lookup3(Identifier identifier, String name, LibraryElement referencingLibrary) {
     Element element = localLookup(name, referencingLibrary);
     if (element != null) {
       return element;
     }
+    // May be there is a hidden Element.
     if (_hasHiddenName) {
       Element hiddenElement = _hiddenElements[name];
       if (hiddenElement != null) {
         errorListener.onError(new AnalysisError.con2(getSource(identifier), identifier.offset, identifier.length, CompileTimeErrorCode.REFERENCED_BEFORE_DECLARATION, []));
         return hiddenElement;
       }
     }
+    // Check enclosing scope.
     return enclosingScope.lookup3(identifier, name, referencingLibrary);
   }
 }
 
 /**
  * Instances of the class `FunctionScope` implement the scope defined by a function.
  *
  * @coverage dart.engine.resolver
  */
 class FunctionScope extends EnclosedScope {
@@ skipping 224 matching lines @@
       }
     }
     if (foundElement is MultiplyDefinedElementImpl) {
       foundElement = removeSdkElements(identifier, name, foundElement as MultiplyDefinedElementImpl);
     }
     if (foundElement is MultiplyDefinedElementImpl) {
       String foundEltName = foundElement.displayName;
       List<Element> conflictingMembers = (foundElement as MultiplyDefinedElementImpl).conflictingElements;
       String libName1 = getLibraryName(conflictingMembers[0], "");
       String libName2 = getLibraryName(conflictingMembers[1], "");
+      // TODO (jwren) Change the error message to include a list of all library names instead of
+      // just the first two
       errorListener.onError(new AnalysisError.con2(getSource(identifier), identifier.offset, identifier.length, StaticWarningCode.AMBIGUOUS_IMPORT, [foundEltName, libName1, libName2]));
       return foundElement;
     }
     if (foundElement != null) {
       defineWithoutChecking2(name, foundElement);
     }
     return foundElement;
   }
 
   /**
@@ skipping 52 matching lines @@
       } else {
         conflictingMembers[to++] = member;
       }
     }
     if (sdkElement != null && to > 0) {
       String sdkLibName = getLibraryName(sdkElement, "");
       String otherLibName = getLibraryName(conflictingMembers[0], "");
       errorListener.onError(new AnalysisError.con2(getSource(identifier), identifier.offset, identifier.length, StaticWarningCode.CONFLICTING_DART_IMPORT, [name, sdkLibName, otherLibName]));
     }
     if (to == length) {
+      // None of the members were removed
       return foundElement;
     } else if (to == 1) {
+      // All but one member was removed
       return conflictingMembers[0];
     } else if (to == 0) {
+      // All members were removed
       AnalysisEngine.instance.logger.logInformation("Multiply defined SDK element: ${foundElement}");
       return foundElement;
     }
     List<Element> remaining = new List<Element>(to);
     JavaSystem.arraycopy(conflictingMembers, 0, remaining, 0, to);
     return new MultiplyDefinedElementImpl(_definingLibrary.context, remaining);
   }
 }
 
 /**
  * Instances of the class `LibraryScope` implement a scope containing all of the names defined
  * in a given library.
  *
  * @coverage dart.engine.resolver
  */
 class LibraryScope extends EnclosedScope {
   /**
    * Initialize a newly created scope representing the names defined in the given library.
    *
    * @param definingLibrary the element representing the library represented by this scope
    * @param errorListener the listener that is to be informed when an error is encountered
    */
   LibraryScope(LibraryElement definingLibrary, AnalysisErrorListener errorListener) : super(new LibraryImportScope(definingLibrary, errorListener)) {
     defineTopLevelNames(definingLibrary);
   }
 
   AnalysisError getErrorForDuplicate(Element existing, Element duplicate) {
     if (existing is PrefixElement) {
+      // TODO(scheglov) consider providing actual 'nameOffset' from the synthetic accessor
       int offset = duplicate.nameOffset;
       if (duplicate is PropertyAccessorElement) {
         PropertyAccessorElement accessor = duplicate;
         if (accessor.isSynthetic) {
           offset = accessor.variable.nameOffset;
         }
       }
       return new AnalysisError.con2(duplicate.source, offset, duplicate.displayName.length, CompileTimeErrorCode.PREFIX_COLLIDES_WITH_TOP_LEVEL_MEMBER, [existing.displayName]);
     }
     return super.getErrorForDuplicate(existing, duplicate);
@@ skipping 92 matching lines @@
 class NamespaceBuilder {
   /**
    * Create a namespace representing the export namespace of the given [ExportElement].
    *
    * @param element the export element whose export namespace is to be created
    * @return the export namespace that was created
    */
   Namespace createExportNamespace(ExportElement element) {
     LibraryElement exportedLibrary = element.exportedLibrary;
     if (exportedLibrary == null) {
+      //
+      // The exported library will be null if the URI does not reference a valid library.
+      //
       return Namespace.EMPTY;
     }
     Map<String, Element> definedNames = createExportMapping(exportedLibrary, new Set<LibraryElement>());
     definedNames = apply(definedNames, element.combinators);
     return new Namespace(definedNames);
   }
 
   /**
    * Create a namespace representing the export namespace of the given library.
    *
    * @param library the library whose export namespace is to be created
    * @return the export namespace that was created
    */
   Namespace createExportNamespace2(LibraryElement library) => new Namespace(createExportMapping(library, new Set<LibraryElement>()));
 
   /**
    * Create a namespace representing the import namespace of the given library.
    *
    * @param library the library whose import namespace is to be created
    * @return the import namespace that was created
    */
   Namespace createImportNamespace(ImportElement element) {
     LibraryElement importedLibrary = element.importedLibrary;
     if (importedLibrary == null) {
+      //
+      // The imported library will be null if the URI does not reference a valid library.
+      //
       return Namespace.EMPTY;
     }
     Map<String, Element> definedNames = createExportMapping(importedLibrary, new Set<LibraryElement>());
     definedNames = apply(definedNames, element.combinators);
     definedNames = apply2(definedNames, element.prefix);
     return new Namespace(definedNames);
   }
 
   /**
    * Create a namespace representing the public namespace of the given library.
@@ skipping 76 matching lines @@
    * @param definedNames the mapping table to which the namespace operations are to be applied
    * @param combinators the combinators to be applied
    */
   Map<String, Element> apply(Map<String, Element> definedNames, List<NamespaceCombinator> combinators) {
     for (NamespaceCombinator combinator in combinators) {
       if (combinator is HideElementCombinator) {
         hide(definedNames, combinator.hiddenNames);
       } else if (combinator is ShowElementCombinator) {
         definedNames = show(definedNames, combinator.shownNames);
       } else {
+        // Internal error.
         AnalysisEngine.instance.logger.logError("Unknown type of combinator: ${combinator.runtimeType.toString()}");
       }
     }
     return definedNames;
   }
 
   /**
    * Apply the given prefix to all of the names in the table of defined names.
    *
    * @param definedNames the names that were defined before this operation
@@ skipping 21 matching lines @@
    *          be added by another library
    * @return the mapping table that was created
    */
   Map<String, Element> createExportMapping(LibraryElement library, Set<LibraryElement> visitedElements) {
     visitedElements.add(library);
     try {
       Map<String, Element> definedNames = new Map<String, Element>();
       for (ExportElement element in library.exports) {
         LibraryElement exportedLibrary = element.exportedLibrary;
         if (exportedLibrary != null && !visitedElements.contains(exportedLibrary)) {
+          //
+          // The exported library will be null if the URI does not reference a valid library.
+          //
           Map<String, Element> exportedNames = createExportMapping(exportedLibrary, visitedElements);
           exportedNames = apply(exportedNames, element.combinators);
           addAll(definedNames, exportedNames);
         }
       }
       addAll2(definedNames, (library.context as InternalAnalysisContext).getPublicNamespace(library));
       return definedNames;
     } finally {
       visitedElements.remove(library);
     }
@@ skipping 140 matching lines @@
 
   /**
    * Return the error code to be used when reporting that a name being defined locally conflicts
    * with another element of the same name in the local scope.
    *
    * @param existing the first element to be declared with the conflicting name
    * @param duplicate another element declared with the conflicting name
    * @return the error code used to report duplicate names within a scope
    */
   AnalysisError getErrorForDuplicate(Element existing, Element duplicate) {
+    // TODO(brianwilkerson) Customize the error message based on the types of elements that share
+    // the same name.
+    // TODO(jwren) There are 4 error codes for duplicate, but only 1 is being generated.
     Source source = duplicate.source;
     return new AnalysisError.con2(source, duplicate.nameOffset, duplicate.displayName.length, CompileTimeErrorCode.DUPLICATE_DEFINITION, [existing.displayName]);
   }
 
   /**
    * Return the listener that is to be informed when an error is encountered.
    *
    * @return the listener that is to be informed when an error is encountered
    */
   AnalysisErrorListener get errorListener;
@@ skipping 209 matching lines @@
     this._errorReporter = errorReporter;
     this._typeProvider = typeProvider;
     this._boolType = typeProvider.boolType;
     this._intType = typeProvider.intType;
     this._numType = typeProvider.numType;
     this._stringType = typeProvider.stringType;
   }
 
   Object visitAnnotation(Annotation node) {
     super.visitAnnotation(node);
+    // check annotation creation
     Element element = node.element;
     if (element is ConstructorElement) {
       ConstructorElement constructorElement = element;
+      // should 'const' constructor
       if (!constructorElement.isConst) {
         _errorReporter.reportError3(CompileTimeErrorCode.NON_CONSTANT_ANNOTATION_CONSTRUCTOR, node, []);
         return null;
       }
+      // should have arguments
       ArgumentList argumentList = node.arguments;
       if (argumentList == null) {
         _errorReporter.reportError3(CompileTimeErrorCode.NO_ANNOTATION_CONSTRUCTOR_ARGUMENTS, node, []);
         return null;
       }
+      // arguments should be constants
       validateConstantArguments(argumentList);
     }
     return null;
   }
 
   Object visitConstructorDeclaration(ConstructorDeclaration node) {
     if (node.constKeyword != null) {
       validateInitializers(node);
     }
     validateDefaultValues(node.parameters);
@@ skipping 74 matching lines @@
     return null;
   }
 
   Object visitVariableDeclaration(VariableDeclaration node) {
     super.visitVariableDeclaration(node);
     Expression initializer = node.initializer;
     if (initializer != null && node.isConst) {
       VariableElementImpl element = node.element as VariableElementImpl;
       EvaluationResultImpl result = element.evaluationResult;
       if (result == null) {
+        //
+        // Normally we don't need to visit const variable declarations because we have already
+        // computed their values. But if we missed it for some reason, this gives us a second
+        // chance.
+        //
         result = validate(initializer, CompileTimeErrorCode.CONST_INITIALIZED_WITH_NON_CONSTANT_VALUE);
         element.evaluationResult = result;
       } else if (result is ErrorResult) {
         reportErrors(result, CompileTimeErrorCode.CONST_INITIALIZED_WITH_NON_CONSTANT_VALUE);
       }
     }
     return null;
   }
 
   /**
@@ skipping 448 matching lines @@
       checkForNoDefaultSuperConstructorImplicit(node);
       checkForAllMixinErrorCodes(withClause);
       checkForConflictingTypeVariableErrorCodes(node);
       if (implementsClause != null || extendsClause != null) {
         if (!checkForImplementsDisallowedClass(implementsClause) && !checkForExtendsDisallowedClass(extendsClause)) {
           checkForNonAbstractClassInheritsAbstractMember(node);
           checkForInconsistentMethodInheritance();
           checkForRecursiveInterfaceInheritance(_enclosingClass);
         }
       }
+      // initialize initialFieldElementsMap
       ClassElement classElement = node.element;
       if (classElement != null) {
         List<FieldElement> fieldElements = classElement.fields;
         _initialFieldElementsMap = new Map<FieldElement, INIT_STATE>();
         for (FieldElement fieldElement in fieldElements) {
           if (!fieldElement.isSynthetic) {
             _initialFieldElementsMap[fieldElement] = fieldElement.initializer == null ? INIT_STATE.NOT_INIT : INIT_STATE.INIT_IN_DECLARATION;
           }
         }
       }
@@ skipping 144 matching lines @@
           checkForNonVoidReturnTypeForSetter(returnType);
         }
       }
       return super.visitFunctionDeclaration(node);
     } finally {
       _enclosingFunction = outerFunction;
     }
   }
 
   Object visitFunctionExpression(FunctionExpression node) {
+    // If this function expression is wrapped in a function declaration, don't change the
+    // enclosingFunction field.
     if (node.parent is! FunctionDeclaration) {
       ExecutableElement outerFunction = _enclosingFunction;
       try {
         _enclosingFunction = node.element;
         return super.visitFunctionExpression(node);
       } finally {
         _enclosingFunction = outerFunction;
       }
     } else {
       return super.visitFunctionExpression(node);
@@ skipping 139 matching lines @@
       ClassElement typeReference = ElementResolver.getTypeReference(target);
       checkForStaticAccessToInstanceMember(typeReference, methodName);
       checkForInstanceAccessToStaticMember(typeReference, methodName);
     } else {
       checkForUnqualifiedReferenceToNonLocalStaticMember(methodName);
     }
     return super.visitMethodInvocation(node);
   }
 
   Object visitNativeClause(NativeClause node) {
+    // TODO(brianwilkerson) Figure out the right rule for when 'native' is allowed.
     if (!_isInSystemLibrary) {
       _errorReporter.reportError3(ParserErrorCode.NATIVE_CLAUSE_IN_NON_SDK_CODE, node, []);
     }
     return super.visitNativeClause(node);
   }
 
   Object visitNativeFunctionBody(NativeFunctionBody node) {
     checkForNativeFunctionBodyInNonSDKCode(node);
     return super.visitNativeFunctionBody(node);
   }
@@ skipping 111 matching lines @@
 
   Object visitTypeParameter(TypeParameter node) {
     checkForBuiltInIdentifierAsName(node.name, CompileTimeErrorCode.BUILT_IN_IDENTIFIER_AS_TYPE_PARAMETER_NAME);
     checkForTypeParameterSupertypeOfItsBound(node);
     return super.visitTypeParameter(node);
   }
 
   Object visitVariableDeclaration(VariableDeclaration node) {
     SimpleIdentifier nameNode = node.name;
     Expression initializerNode = node.initializer;
+    // do checks
     checkForInvalidAssignment2(nameNode, initializerNode);
+    // visit name
     nameNode.accept(this);
+    // visit initializer
     String name = nameNode.name;
     _namesForReferenceToDeclaredVariableInInitializer.add(name);
     _isInInstanceVariableInitializer = _isInInstanceVariableDeclaration;
     try {
       if (initializerNode != null) {
         initializerNode.accept(this);
       }
     } finally {
       _isInInstanceVariableInitializer = false;
       _namesForReferenceToDeclaredVariableInInitializer.remove(name);
     }
+    // done
     return null;
   }
 
   Object visitVariableDeclarationList(VariableDeclarationList node) => super.visitVariableDeclarationList(node);
 
   Object visitVariableDeclarationStatement(VariableDeclarationStatement node) {
     checkForFinalNotInitialized2(node.variables);
     return super.visitVariableDeclarationStatement(node);
   }
 
   Object visitWhileStatement(WhileStatement node) {
     checkForNonBoolCondition(node.condition);
     return super.visitWhileStatement(node);
   }
 
   /**
    * This verifies if the passed map literal has type arguments then there is exactly two.
    *
    * @param node the map literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#EXPECTED_TWO_MAP_TYPE_ARGUMENTS
    */
   bool checkExpectedTwoMapTypeArguments(TypeArgumentList typeArguments) {
+    // has type arguments
     if (typeArguments == null) {
       return false;
     }
+    // check number of type arguments
     int num = typeArguments.arguments.length;
     if (num == 2) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticTypeWarningCode.EXPECTED_TWO_MAP_TYPE_ARGUMENTS, typeArguments, [num]);
     return true;
   }
 
   /**
    * This verifies that the passed constructor declaration does not violate any of the error codes
    * relating to the initialization of fields in the enclosing class.
    *
    * @param node the [ConstructorDeclaration] to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see #initialFieldElementsMap
    * @see CompileTimeErrorCode#FINAL_INITIALIZED_IN_DECLARATION_AND_CONSTRUCTOR
    * @see CompileTimeErrorCode#FINAL_INITIALIZED_MULTIPLE_TIMES
    */
   bool checkForAllFinalInitializedErrorCodes(ConstructorDeclaration node) {
     if (node.factoryKeyword != null || node.redirectedConstructor != null || node.externalKeyword != null) {
       return false;
     }
+    // Ignore if native class.
     if (_isInNativeClass) {
       return false;
     }
     bool foundError = false;
     Map<FieldElement, INIT_STATE> fieldElementsMap = new Map<FieldElement, INIT_STATE>.from(_initialFieldElementsMap);
+    // Visit all of the field formal parameters
     NodeList<FormalParameter> formalParameters = node.parameters.parameters;
     for (FormalParameter formalParameter in formalParameters) {
       FormalParameter parameter = formalParameter;
       if (parameter is DefaultFormalParameter) {
         parameter = (parameter as DefaultFormalParameter).parameter;
       }
       if (parameter is FieldFormalParameter) {
         FieldElement fieldElement = (parameter.element as FieldFormalParameterElementImpl).field;
         INIT_STATE state = fieldElementsMap[fieldElement];
         if (identical(state, INIT_STATE.NOT_INIT)) {
           fieldElementsMap[fieldElement] = INIT_STATE.INIT_IN_FIELD_FORMAL;
         } else if (identical(state, INIT_STATE.INIT_IN_DECLARATION)) {
           if (fieldElement.isFinal || fieldElement.isConst) {
             _errorReporter.reportError3(StaticWarningCode.FINAL_INITIALIZED_IN_DECLARATION_AND_CONSTRUCTOR, formalParameter.identifier, [fieldElement.displayName]);
             foundError = true;
           }
         } else if (identical(state, INIT_STATE.INIT_IN_FIELD_FORMAL)) {
           if (fieldElement.isFinal || fieldElement.isConst) {
             _errorReporter.reportError3(CompileTimeErrorCode.FINAL_INITIALIZED_MULTIPLE_TIMES, formalParameter.identifier, [fieldElement.displayName]);
             foundError = true;
           }
         }
       }
     }
+    // Visit all of the initializers
     NodeList<ConstructorInitializer> initializers = node.initializers;
     for (ConstructorInitializer constructorInitializer in initializers) {
       if (constructorInitializer is RedirectingConstructorInvocation) {
         return false;
       }
       if (constructorInitializer is ConstructorFieldInitializer) {
         ConstructorFieldInitializer constructorFieldInitializer = constructorInitializer;
         SimpleIdentifier fieldName = constructorFieldInitializer.fieldName;
         Element element = fieldName.staticElement;
         if (element is FieldElement) {
           FieldElement fieldElement = element;
           INIT_STATE state = fieldElementsMap[fieldElement];
           if (identical(state, INIT_STATE.NOT_INIT)) {
             fieldElementsMap[fieldElement] = INIT_STATE.INIT_IN_INITIALIZERS;
           } else if (identical(state, INIT_STATE.INIT_IN_DECLARATION)) {
             if (fieldElement.isFinal || fieldElement.isConst) {
               _errorReporter.reportError3(StaticWarningCode.FIELD_INITIALIZED_IN_INITIALIZER_AND_DECLARATION, fieldName, []);
               foundError = true;
             }
           } else if (identical(state, INIT_STATE.INIT_IN_FIELD_FORMAL)) {
             _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZED_IN_PARAMETER_AND_INITIALIZER, fieldName, []);
             foundError = true;
           } else if (identical(state, INIT_STATE.INIT_IN_INITIALIZERS)) {
             _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZED_BY_MULTIPLE_INITIALIZERS, fieldName, [fieldElement.displayName]);
             foundError = true;
           }
         }
       }
     }
+    // Visit all of the states in the map to ensure that none were never initialized.
     for (MapEntry<FieldElement, INIT_STATE> entry in getMapEntrySet(fieldElementsMap)) {
       if (identical(entry.getValue(), INIT_STATE.NOT_INIT)) {
         FieldElement fieldElement = entry.getKey();
         if (fieldElement.isConst) {
           _errorReporter.reportError3(CompileTimeErrorCode.CONST_NOT_INITIALIZED, node.returnType, [fieldElement.name]);
           foundError = true;
         } else if (fieldElement.isFinal) {
           _errorReporter.reportError3(StaticWarningCode.FINAL_NOT_INITIALIZED, node.returnType, [fieldElement.name]);
           foundError = true;
         }
@@ skipping 25 matching lines @@
     String executableElementName = executableElement.name;
     bool executableElementPrivate = Identifier.isPrivateName(executableElementName);
     ExecutableElement overriddenExecutable = _inheritanceManager.lookupInheritance(_enclosingClass, executableElementName);
     bool isGetter = false;
     bool isSetter = false;
     if (executableElement is PropertyAccessorElement) {
       PropertyAccessorElement accessorElement = executableElement;
       isGetter = accessorElement.isGetter;
       isSetter = accessorElement.isSetter;
     }
+    // SWC.INSTANCE_METHOD_NAME_COLLIDES_WITH_SUPERCLASS_STATIC
     if (overriddenExecutable == null) {
       if (!isGetter && !isSetter && !executableElement.isOperator) {
         Set<ClassElement> visitedClasses = new Set<ClassElement>();
         InterfaceType superclassType = _enclosingClass.supertype;
         ClassElement superclassElement = superclassType == null ? null : superclassType.element;
         while (superclassElement != null && !visitedClasses.contains(superclassElement)) {
           visitedClasses.add(superclassElement);
           LibraryElement superclassLibrary = superclassElement.library;
+          // Check fields.
           List<FieldElement> fieldElts = superclassElement.fields;
           for (FieldElement fieldElt in fieldElts) {
+            // We need the same name.
             if (fieldElt.name != executableElementName) {
               continue;
             }
+            // Ignore if private in a different library - cannot collide.
             if (executableElementPrivate && _currentLibrary != superclassLibrary) {
               continue;
             }
+            // instance vs. static
             if (fieldElt.isStatic) {
               _errorReporter.reportError3(StaticWarningCode.INSTANCE_METHOD_NAME_COLLIDES_WITH_SUPERCLASS_STATIC, errorNameTarget, [
                   executableElementName,
                   fieldElt.enclosingElement.displayName]);
               return true;
             }
           }
+          // Check methods.
           List<MethodElement> methodElements = superclassElement.methods;
           for (MethodElement methodElement in methodElements) {
+            // We need the same name.
             if (methodElement.name != executableElementName) {
               continue;
             }
+            // Ignore if private in a different library - cannot collide.
             if (executableElementPrivate && _currentLibrary != superclassLibrary) {
               continue;
             }
+            // instance vs. static
             if (methodElement.isStatic) {
               _errorReporter.reportError3(StaticWarningCode.INSTANCE_METHOD_NAME_COLLIDES_WITH_SUPERCLASS_STATIC, errorNameTarget, [
                   executableElementName,
                   methodElement.enclosingElement.displayName]);
               return true;
             }
           }
           superclassType = superclassElement.supertype;
           superclassElement = superclassType == null ? null : superclassType.element;
         }
       }
       return false;
     }
     FunctionType overridingFT = executableElement.type;
     FunctionType overriddenFT = overriddenExecutable.type;
     InterfaceType enclosingType = _enclosingClass.type;
     overriddenFT = _inheritanceManager.substituteTypeArgumentsInMemberFromInheritance(overriddenFT, executableElementName, enclosingType);
     if (overridingFT == null || overriddenFT == null) {
       return false;
     }
     Type2 overridingFTReturnType = overridingFT.returnType;
     Type2 overriddenFTReturnType = overriddenFT.returnType;
     List<Type2> overridingNormalPT = overridingFT.normalParameterTypes;
     List<Type2> overriddenNormalPT = overriddenFT.normalParameterTypes;
     List<Type2> overridingPositionalPT = overridingFT.optionalParameterTypes;
     List<Type2> overriddenPositionalPT = overriddenFT.optionalParameterTypes;
     Map<String, Type2> overridingNamedPT = overridingFT.namedParameterTypes;
     Map<String, Type2> overriddenNamedPT = overriddenFT.namedParameterTypes;
+    // CTEC.INVALID_OVERRIDE_REQUIRED, CTEC.INVALID_OVERRIDE_POSITIONAL and CTEC.INVALID_OVERRIDE_NAMED
     if (overridingNormalPT.length > overriddenNormalPT.length) {
       _errorReporter.reportError3(StaticWarningCode.INVALID_OVERRIDE_REQUIRED, errorNameTarget, [
           overriddenNormalPT.length,
           overriddenExecutable.enclosingElement.displayName]);
       return true;
     }
     if (overridingNormalPT.length + overridingPositionalPT.length < overriddenPositionalPT.length + overriddenNormalPT.length) {
       _errorReporter.reportError3(StaticWarningCode.INVALID_OVERRIDE_POSITIONAL, errorNameTarget, [
           overriddenPositionalPT.length + overriddenNormalPT.length,
           overriddenExecutable.enclosingElement.displayName]);
       return true;
     }
+    // For each named parameter in the overridden method, verify that there is the same name in
+    // the overriding method, and in the same order.
     Set<String> overridingParameterNameSet = overridingNamedPT.keys.toSet();
     JavaIterator<String> overriddenParameterNameIterator = new JavaIterator(overriddenNamedPT.keys.toSet());
     while (overriddenParameterNameIterator.hasNext) {
       String overriddenParamName = overriddenParameterNameIterator.next();
       if (!overridingParameterNameSet.contains(overriddenParamName)) {
+        // The overridden method expected the overriding method to have overridingParamName,
+        // but it does not.
         _errorReporter.reportError3(StaticWarningCode.INVALID_OVERRIDE_NAMED, errorNameTarget, [
             overriddenParamName,
             overriddenExecutable.enclosingElement.displayName]);
         return true;
       }
     }
+    // SWC.INVALID_METHOD_OVERRIDE_RETURN_TYPE
     if (overriddenFTReturnType != VoidTypeImpl.instance && !overridingFTReturnType.isAssignableTo(overriddenFTReturnType)) {
       _errorReporter.reportError3(!isGetter ? StaticWarningCode.INVALID_METHOD_OVERRIDE_RETURN_TYPE : StaticWarningCode.INVALID_GETTER_OVERRIDE_RETURN_TYPE, errorNameTarget, [
           overridingFTReturnType.displayName,
           overriddenFTReturnType.displayName,
           overriddenExecutable.enclosingElement.displayName]);
       return true;
     }
+    // SWC.INVALID_METHOD_OVERRIDE_NORMAL_PARAM_TYPE
     if (parameterLocations == null) {
       return false;
     }
     int parameterIndex = 0;
     for (int i = 0; i < overridingNormalPT.length; i++) {
       if (!overridingNormalPT[i].isAssignableTo(overriddenNormalPT[i])) {
         _errorReporter.reportError3(!isSetter ? StaticWarningCode.INVALID_METHOD_OVERRIDE_NORMAL_PARAM_TYPE : StaticWarningCode.INVALID_SETTER_OVERRIDE_NORMAL_PARAM_TYPE, parameterLocations[parameterIndex], [
             overridingNormalPT[i].displayName,
             overriddenNormalPT[i].displayName,
             overriddenExecutable.enclosingElement.displayName]);
         return true;
       }
       parameterIndex++;
     }
+    // SWC.INVALID_METHOD_OVERRIDE_OPTIONAL_PARAM_TYPE
     for (int i = 0; i < overriddenPositionalPT.length; i++) {
       if (!overridingPositionalPT[i].isAssignableTo(overriddenPositionalPT[i])) {
         _errorReporter.reportError3(StaticWarningCode.INVALID_METHOD_OVERRIDE_OPTIONAL_PARAM_TYPE, parameterLocations[parameterIndex], [
             overridingPositionalPT[i].displayName,
             overriddenPositionalPT[i].displayName,
             overriddenExecutable.enclosingElement.displayName]);
         return true;
       }
       parameterIndex++;
     }
+    // SWC.INVALID_METHOD_OVERRIDE_NAMED_PARAM_TYPE & SWC.INVALID_OVERRIDE_DIFFERENT_DEFAULT_VALUES
     JavaIterator<MapEntry<String, Type2>> overriddenNamedPTIterator = new JavaIterator(getMapEntrySet(overriddenNamedPT));
     while (overriddenNamedPTIterator.hasNext) {
       MapEntry<String, Type2> overriddenNamedPTEntry = overriddenNamedPTIterator.next();
       Type2 overridingType = overridingNamedPT[overriddenNamedPTEntry.getKey()];
       if (overridingType == null) {
+        // Error, this is never reached- INVALID_OVERRIDE_NAMED would have been created above if
+        // this could be reached.
         continue;
       }
       if (!overriddenNamedPTEntry.getValue().isAssignableTo(overridingType)) {
+        // lookup the parameter for the error to select
         ParameterElement parameterToSelect = null;
         ASTNode parameterLocationToSelect = null;
         for (int i = 0; i < parameters.length; i++) {
           ParameterElement parameter = parameters[i];
           if (identical(parameter.parameterKind, ParameterKind.NAMED) && overriddenNamedPTEntry.getKey() == parameter.name) {
             parameterToSelect = parameter;
             parameterLocationToSelect = parameterLocations[i];
             break;
           }
         }
         if (parameterToSelect != null) {
           _errorReporter.reportError3(StaticWarningCode.INVALID_METHOD_OVERRIDE_NAMED_PARAM_TYPE, parameterLocationToSelect, [
               overridingType.displayName,
               overriddenNamedPTEntry.getValue().displayName,
               overriddenExecutable.enclosingElement.displayName]);
           return true;
         }
       }
     }
+    // SWC.INVALID_OVERRIDE_DIFFERENT_DEFAULT_VALUES
+    //
+    // Create three arrays: an array of the optional parameter ASTs (FormalParameters), an array of
+    // the optional parameters elements from our method, and finally an array of the optional
+    // parameter elements from the method we are overriding.
+    //
     bool foundError = false;
     List<ASTNode> formalParameters = new List<ASTNode>();
     List<ParameterElementImpl> parameterElts = new List<ParameterElementImpl>();
     List<ParameterElementImpl> overriddenParameterElts = new List<ParameterElementImpl>();
     List<ParameterElement> overriddenPEs = overriddenExecutable.parameters;
     for (int i = 0; i < parameters.length; i++) {
       ParameterElement parameter = parameters[i];
       if (parameter.parameterKind.isOptional) {
         formalParameters.add(parameterLocations[i]);
         parameterElts.add(parameter as ParameterElementImpl);
       }
     }
     for (ParameterElement parameterElt in overriddenPEs) {
       if (parameterElt.parameterKind.isOptional) {
         if (parameterElt is ParameterElementImpl) {
           overriddenParameterElts.add(parameterElt);
         }
       }
     }
+    //
+    // Next compare the list of optional parameter elements to the list of overridden optional
+    // parameter elements.
+    //
     if (parameterElts.length > 0) {
       if (identical(parameterElts[0].parameterKind, ParameterKind.NAMED)) {
+        // Named parameters, consider the names when matching the parameterElts to the overriddenParameterElts
         for (int i = 0; i < parameterElts.length; i++) {
           ParameterElementImpl parameterElt = parameterElts[i];
           EvaluationResultImpl result = parameterElt.evaluationResult;
+          // TODO (jwren) Ignore Object types, see Dart bug 11287
           if (isUserDefinedObject(result)) {
             continue;
           }
           String parameterName = parameterElt.name;
           for (int j = 0; j < overriddenParameterElts.length; j++) {
             ParameterElementImpl overriddenParameterElt = overriddenParameterElts[j];
             String overriddenParameterName = overriddenParameterElt.name;
             if (parameterName != null && parameterName == overriddenParameterName) {
               EvaluationResultImpl overriddenResult = overriddenParameterElt.evaluationResult;
               if (isUserDefinedObject(overriddenResult)) {
                 break;
               }
               if (!result.equalValues(_typeProvider, overriddenResult)) {
                 _errorReporter.reportError3(StaticWarningCode.INVALID_OVERRIDE_DIFFERENT_DEFAULT_VALUES_NAMED, formalParameters[i], [
                     overriddenExecutable.enclosingElement.displayName,
                     overriddenExecutable.displayName,
                     parameterName]);
                 foundError = true;
               }
             }
           }
         }
       } else {
+        // Positional parameters, consider the positions when matching the parameterElts to the overriddenParameterElts
         for (int i = 0; i < parameterElts.length && i < overriddenParameterElts.length; i++) {
           ParameterElementImpl parameterElt = parameterElts[i];
           EvaluationResultImpl result = parameterElt.evaluationResult;
+          // TODO (jwren) Ignore Object types, see Dart bug 11287
           if (isUserDefinedObject(result)) {
             continue;
           }
           ParameterElementImpl overriddenParameterElt = overriddenParameterElts[i];
           EvaluationResultImpl overriddenResult = overriddenParameterElt.evaluationResult;
           if (isUserDefinedObject(overriddenResult)) {
             continue;
           }
           if (!result.equalValues(_typeProvider, overriddenResult)) {
             _errorReporter.reportError3(StaticWarningCode.INVALID_OVERRIDE_DIFFERENT_DEFAULT_VALUES_POSITIONAL, formalParameters[i], [
@@ skipping 97 matching lines @@
   /**
    * This checks error related to the redirected constructors.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#REDIRECT_TO_INVALID_RETURN_TYPE
    * @see StaticWarningCode#REDIRECT_TO_INVALID_FUNCTION_TYPE
    * @see StaticWarningCode#REDIRECT_TO_MISSING_CONSTRUCTOR
    */
   bool checkForAllRedirectConstructorErrorCodes(ConstructorDeclaration node) {
+    //
+    // Prepare redirected constructor node
+    //
     ConstructorName redirectedConstructor = node.redirectedConstructor;
     if (redirectedConstructor == null) {
       return false;
     }
+    //
+    // Prepare redirected constructor type
+    //
     ConstructorElement redirectedElement = redirectedConstructor.staticElement;
     if (redirectedElement == null) {
+      //
+      // If the element is null, we check for the REDIRECT_TO_MISSING_CONSTRUCTOR case
+      //
       TypeName constructorTypeName = redirectedConstructor.type;
       Type2 redirectedType = constructorTypeName.type;
       if (redirectedType != null && redirectedType.element != null && !redirectedType.isDynamic) {
+        //
+        // Prepare the constructor name
+        //
         String constructorStrName = constructorTypeName.name.name;
         if (redirectedConstructor.name != null) {
           constructorStrName += ".${redirectedConstructor.name.name}";
         }
         ErrorCode errorCode = (node.constKeyword != null ? CompileTimeErrorCode.REDIRECT_TO_MISSING_CONSTRUCTOR : StaticWarningCode.REDIRECT_TO_MISSING_CONSTRUCTOR) as ErrorCode;
         _errorReporter.reportError3(errorCode, redirectedConstructor, [constructorStrName, redirectedType.displayName]);
         return true;
       }
       return false;
     }
     FunctionType redirectedType = redirectedElement.type;
     Type2 redirectedReturnType = redirectedType.returnType;
+    //
+    // Report specific problem when return type is incompatible
+    //
     FunctionType constructorType = node.element.type;
     Type2 constructorReturnType = constructorType.returnType;
     if (!redirectedReturnType.isAssignableTo(constructorReturnType)) {
       _errorReporter.reportError3(StaticWarningCode.REDIRECT_TO_INVALID_RETURN_TYPE, redirectedConstructor, [redirectedReturnType, constructorReturnType]);
       return true;
     }
+    //
+    // Check parameters
+    //
     if (!redirectedType.isSubtypeOf(constructorType)) {
       _errorReporter.reportError3(StaticWarningCode.REDIRECT_TO_INVALID_FUNCTION_TYPE, redirectedConstructor, [redirectedType, constructorType]);
       return true;
     }
     return false;
   }
 
   /**
    * This checks that the return statement of the form <i>return e;</i> is not in a generative
    * constructor.
    *
    * This checks that return statements without expressions are not in a generative constructor and
    * the return type is not assignable to `null`; that is, we don't have `return;` if
    * the enclosing method has a return type.
    *
    * This checks that the return type matches the type of the declared return type in the enclosing
    * method or function.
    *
    * @param node the return statement to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#RETURN_IN_GENERATIVE_CONSTRUCTOR
    * @see StaticWarningCode#RETURN_WITHOUT_VALUE
    * @see StaticTypeWarningCode#RETURN_OF_INVALID_TYPE
    */
   bool checkForAllReturnStatementErrorCodes(ReturnStatement node) {
     FunctionType functionType = _enclosingFunction == null ? null : _enclosingFunction.type;
     Type2 expectedReturnType = functionType == null ? DynamicTypeImpl.instance : functionType.returnType;
     Expression returnExpression = node.expression;
+    // RETURN_IN_GENERATIVE_CONSTRUCTOR
     bool isGenerativeConstructor = _enclosingFunction is ConstructorElement && !(_enclosingFunction as ConstructorElement).isFactory;
     if (isGenerativeConstructor) {
       if (returnExpression == null) {
         return false;
       }
       _errorReporter.reportError3(CompileTimeErrorCode.RETURN_IN_GENERATIVE_CONSTRUCTOR, returnExpression, []);
       return true;
     }
+    // RETURN_WITHOUT_VALUE
     if (returnExpression == null) {
       if (VoidTypeImpl.instance.isAssignableTo(expectedReturnType)) {
         return false;
       }
       _errorReporter.reportError3(StaticWarningCode.RETURN_WITHOUT_VALUE, node, []);
       return true;
     }
+    // RETURN_OF_INVALID_TYPE
     return checkForReturnOfInvalidType(returnExpression, expectedReturnType);
   }
 
   /**
    * This verifies that the export namespace of the passed export directive does not export any name
    * already exported by other export directive.
    *
    * @param node the export directive node to report problem on
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#AMBIGUOUS_EXPORT
    */
   bool checkForAmbiguousExport(ExportDirective node) {
+    // prepare ExportElement
     if (node.element is! ExportElement) {
       return false;
     }
     ExportElement exportElement = node.element as ExportElement;
+    // prepare exported library
     LibraryElement exportedLibrary = exportElement.exportedLibrary;
     if (exportedLibrary == null) {
       return false;
     }
+    // check exported names
     Namespace namespace = new NamespaceBuilder().createExportNamespace(exportElement);
     Map<String, Element> definedNames = namespace.definedNames;
     for (MapEntry<String, Element> definedEntry in getMapEntrySet(definedNames)) {
       String name = definedEntry.getKey();
       Element element = definedEntry.getValue();
       Element prevElement = _exportedElements[name];
       if (element != null && prevElement != null && prevElement != element) {
         _errorReporter.reportError3(CompileTimeErrorCode.AMBIGUOUS_EXPORT, node, [
             name,
             prevElement.library.definingCompilationUnit.displayName,
@@ skipping 31 matching lines @@
    * @see StaticWarningCode#ARGUMENT_TYPE_NOT_ASSIGNABLE
    */
   bool checkForArgumentTypeNotAssignable(ArgumentList argumentList) {
     if (argumentList == null) {
       return false;
     }
     bool problemReported = false;
     for (Expression argument in argumentList.arguments) {
       problemReported = javaBooleanOr(problemReported, checkForArgumentTypeNotAssignable2(argument));
     }
+    // done
     return problemReported;
   }
 
   /**
    * This verifies that the passed argument can be assigned to its corresponding parameter.
    *
    * @param argument the argument to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#ARGUMENT_TYPE_NOT_ASSIGNABLE
    */
@@ skipping 25 matching lines @@
    * @param expression the expression to evaluate
    * @param expectedStaticType the expected static type of the parameter
    * @param actualStaticType the actual static type of the argument
    * @param expectedPropagatedType the expected propagated type of the parameter, may be
    *          `null`
    * @param actualPropagatedType the expected propagated type of the parameter, may be `null`
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#ARGUMENT_TYPE_NOT_ASSIGNABLE
    */
   bool checkForArgumentTypeNotAssignable4(Expression expression, Type2 expectedStaticType, Type2 actualStaticType, Type2 expectedPropagatedType, Type2 actualPropagatedType, ErrorCode errorCode) {
+    //
+    // Test static type information
+    //
     if (actualStaticType == null || expectedStaticType == null) {
       return false;
     }
     if (actualStaticType.isAssignableTo(expectedStaticType)) {
       return false;
     }
     _errorReporter.reportError3(errorCode, expression, [
         actualStaticType.displayName,
         expectedStaticType.displayName]);
     return true;
@@ skipping 14 matching lines @@
   /**
    * This verifies that the passed expression is not final.
    *
    * @param node the expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#ASSIGNMENT_TO_CONST
    * @see StaticWarningCode#ASSIGNMENT_TO_FINAL
    * @see StaticWarningCode#ASSIGNMENT_TO_METHOD
    */
   bool checkForAssignmentToFinal2(Expression expression) {
+    // prepare element
     Element element = null;
     if (expression is Identifier) {
       element = expression.staticElement;
     }
     if (expression is PropertyAccess) {
       element = expression.propertyName.staticElement;
     }
+    // check if element is assignable
     if (element is PropertyAccessorElement) {
       PropertyAccessorElement accessor = element as PropertyAccessorElement;
       element = accessor.variable;
     }
     if (element is VariableElement) {
       VariableElement variable = element as VariableElement;
       if (variable.isConst) {
         _errorReporter.reportError3(StaticWarningCode.ASSIGNMENT_TO_CONST, expression, []);
         return true;
       }
@@ skipping 38 matching lines @@
    * This verifies that the given switch case is terminated with 'break', 'continue', 'return' or
    * 'throw'.
    *
    * @param node the switch case to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#CASE_BLOCK_NOT_TERMINATED
    */
   bool checkForCaseBlockNotTerminated(SwitchCase node) {
     NodeList<Statement> statements = node.statements;
     if (statements.isEmpty) {
+      // fall-through without statements at all
       ASTNode parent = node.parent;
       if (parent is SwitchStatement) {
         SwitchStatement switchStatement = parent;
         NodeList<SwitchMember> members = switchStatement.members;
         int index = members.indexOf(node);
         if (index != -1 && index < members.length - 1) {
           return false;
         }
       }
     } else {
       Statement statement = statements[statements.length - 1];
+      // terminated with statement
       if (statement is BreakStatement || statement is ContinueStatement || statement is ReturnStatement) {
         return false;
       }
+      // terminated with 'throw' expression
       if (statement is ExpressionStatement) {
         Expression expression = statement.expression;
         if (expression is ThrowExpression) {
           return false;
         }
       }
     }
+    // report error
     _errorReporter.reportError6(StaticWarningCode.CASE_BLOCK_NOT_TERMINATED, node.keyword, []);
     return true;
   }
 
   /**
    * This verifies that the switch cases in the given switch statement is terminated with 'break',
    * 'continue', 'return' or 'throw'.
    *
    * @param node the switch statement containing the cases to be checked
    * @return `true` if and only if an error code is generated on the passed node
@@ skipping 18 matching lines @@
    *
    * @param node the switch statement to evaluate
    * @param type the common type of all 'case' expressions
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CASE_EXPRESSION_TYPE_IMPLEMENTS_EQUALS
    */
   bool checkForCaseExpressionTypeImplementsEquals(SwitchStatement node, Type2 type) {
     if (!implementsEqualsWhenNotAllowed(type)) {
       return false;
     }
+    // report error
     _errorReporter.reportError6(CompileTimeErrorCode.CASE_EXPRESSION_TYPE_IMPLEMENTS_EQUALS, node.keyword, [type.displayName]);
     return true;
   }
 
   /**
    * This verifies that the passed method declaration is abstract only if the enclosing class is
    * also abstract.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
@@ skipping 17 matching lines @@
    * @see CompileTimeErrorCode#DUPLICATE_CONSTRUCTOR_DEFAULT
    * @see CompileTimeErrorCode#DUPLICATE_CONSTRUCTOR_NAME
    * @see CompileTimeErrorCode#CONFLICTING_CONSTRUCTOR_NAME_AND_FIELD
    * @see CompileTimeErrorCode#CONFLICTING_CONSTRUCTOR_NAME_AND_METHOD
    */
   bool checkForConflictingConstructorNameAndMember(ConstructorDeclaration node) {
     ConstructorElement constructorElement = node.element;
     SimpleIdentifier constructorName = node.name;
     String name = constructorElement.name;
     ClassElement classElement = constructorElement.enclosingElement;
+    // constructors
     List<ConstructorElement> constructors = classElement.constructors;
     for (ConstructorElement otherConstructor in constructors) {
       if (identical(otherConstructor, constructorElement)) {
         continue;
       }
       if (name == otherConstructor.name) {
         if (name == null || name.length == 0) {
           _errorReporter.reportError3(CompileTimeErrorCode.DUPLICATE_CONSTRUCTOR_DEFAULT, node, []);
         } else {
           _errorReporter.reportError3(CompileTimeErrorCode.DUPLICATE_CONSTRUCTOR_NAME, node, [name]);
         }
         return true;
       }
     }
+    // conflict with class member
     if (constructorName != null && constructorElement != null && !constructorName.isSynthetic) {
+      // fields
       FieldElement field = classElement.getField(name);
       if (field != null) {
         _errorReporter.reportError3(CompileTimeErrorCode.CONFLICTING_CONSTRUCTOR_NAME_AND_FIELD, node, [name]);
         return true;
       }
+      // methods
       MethodElement method = classElement.getMethod(name);
       if (method != null) {
         _errorReporter.reportError3(CompileTimeErrorCode.CONFLICTING_CONSTRUCTOR_NAME_AND_METHOD, node, [name]);
         return true;
       }
     }
     return false;
   }
 
   /**
    * This verifies that the [enclosingClass] does not have method and getter with the same
    * names.
    *
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONFLICTING_GETTER_AND_METHOD
    * @see CompileTimeErrorCode#CONFLICTING_METHOD_AND_GETTER
    */
   bool checkForConflictingGetterAndMethod() {
     if (_enclosingClass == null) {
       return false;
     }
     bool hasProblem = false;
+    // method declared in the enclosing class vs. inherited getter
     for (MethodElement method in _enclosingClass.methods) {
       String name = method.name;
+      // find inherited property accessor (and can be only getter)
       ExecutableElement inherited = _inheritanceManager.lookupInheritance(_enclosingClass, name);
       if (inherited is! PropertyAccessorElement) {
         continue;
       }
+      // report problem
       hasProblem = true;
       _errorReporter.reportError5(CompileTimeErrorCode.CONFLICTING_GETTER_AND_METHOD, method.nameOffset, name.length, [
           _enclosingClass.displayName,
           inherited.enclosingElement.displayName,
           name]);
     }
+    // getter declared in the enclosing class vs. inherited method
     for (PropertyAccessorElement accessor in _enclosingClass.accessors) {
       if (!accessor.isGetter) {
         continue;
       }
       String name = accessor.name;
+      // find inherited method
       ExecutableElement inherited = _inheritanceManager.lookupInheritance(_enclosingClass, name);
       if (inherited is! MethodElement) {
         continue;
       }
+      // report problem
       hasProblem = true;
       _errorReporter.reportError5(CompileTimeErrorCode.CONFLICTING_METHOD_AND_GETTER, accessor.nameOffset, name.length, [
           _enclosingClass.displayName,
           inherited.enclosingElement.displayName,
           name]);
     }
+    // done
     return hasProblem;
   }
 
   /**
    * This verifies that the superclass of the [enclosingClass] does not declare accessible
    * static members with the same name as the instance getters/setters declared in
    * [enclosingClass].
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#CONFLICTING_INSTANCE_GETTER_AND_SUPERCLASS_MEMBER
    * @see StaticWarningCode#CONFLICTING_INSTANCE_SETTER_AND_SUPERCLASS_MEMBER
    */
   bool checkForConflictingInstanceGetterAndSuperclassMember() {
     if (_enclosingClass == null) {
       return false;
     }
     InterfaceType enclosingType = _enclosingClass.type;
+    // check every accessor
     bool hasProblem = false;
     for (PropertyAccessorElement accessor in _enclosingClass.accessors) {
+      // we analyze instance accessors here
       if (accessor.isStatic) {
         continue;
       }
+      // prepare accessor properties
       String name = accessor.displayName;
       bool getter = accessor.isGetter;
+      // if non-final variable, ignore setter - we alreay reported problem for getter
       if (accessor.isSetter && accessor.isSynthetic) {
         continue;
       }
+      // try to find super element
       ExecutableElement superElement;
       superElement = enclosingType.lookUpGetterInSuperclass(name, _currentLibrary);
       if (superElement == null) {
         superElement = enclosingType.lookUpSetterInSuperclass(name, _currentLibrary);
       }
       if (superElement == null) {
         superElement = enclosingType.lookUpMethodInSuperclass(name, _currentLibrary);
       }
       if (superElement == null) {
         continue;
       }
+      // OK, not static
       if (!superElement.isStatic) {
         continue;
       }
+      // prepare "super" type to report its name
       ClassElement superElementClass = superElement.enclosingElement as ClassElement;
       InterfaceType superElementType = superElementClass.type;
+      // report problem
       hasProblem = true;
       if (getter) {
         _errorReporter.reportError4(StaticWarningCode.CONFLICTING_INSTANCE_GETTER_AND_SUPERCLASS_MEMBER, accessor, [superElementType.displayName]);
       } else {
         _errorReporter.reportError4(StaticWarningCode.CONFLICTING_INSTANCE_SETTER_AND_SUPERCLASS_MEMBER, accessor, [superElementType.displayName]);
       }
     }
+    // done
     return hasProblem;
   }
 
   /**
    * This verifies that the enclosing class does not have a setter with the same name as the passed
    * instance method declaration.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#CONFLICTING_INSTANCE_METHOD_SETTER
    */
   bool checkForConflictingInstanceMethodSetter(MethodDeclaration node) {
     if (node.isStatic) {
       return false;
     }
+    // prepare name
     SimpleIdentifier nameNode = node.name;
     if (nameNode == null) {
       return false;
     }
     String name = nameNode.name;
+    // ensure that we have enclosing class
     if (_enclosingClass == null) {
       return false;
     }
+    // try to find setter
     ExecutableElement setter = _inheritanceManager.lookupMember(_enclosingClass, "${name}=");
     if (setter == null) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticWarningCode.CONFLICTING_INSTANCE_METHOD_SETTER, nameNode, [
         _enclosingClass.displayName,
         name,
         setter.enclosingElement.displayName]);
     return true;
   }
 
   /**
    * This verifies that the enclosing class does not have an instance member with the same name as
    * the passed static getter method declaration.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#CONFLICTING_STATIC_GETTER_AND_INSTANCE_SETTER
    */
   bool checkForConflictingStaticGetterAndInstanceSetter(MethodDeclaration node) {
     if (!node.isStatic) {
       return false;
     }
+    // prepare name
     SimpleIdentifier nameNode = node.name;
     if (nameNode == null) {
       return false;
     }
     String name = nameNode.name;
+    // prepare enclosing type
     if (_enclosingClass == null) {
       return false;
     }
     InterfaceType enclosingType = _enclosingClass.type;
+    // try to find setter
     ExecutableElement setter = enclosingType.lookUpSetter(name, _currentLibrary);
     if (setter == null) {
       return false;
     }
+    // OK, also static
     if (setter.isStatic) {
       return false;
     }
+    // prepare "setter" type to report its name
     ClassElement setterClass = setter.enclosingElement as ClassElement;
     InterfaceType setterType = setterClass.type;
+    // report problem
     _errorReporter.reportError3(StaticWarningCode.CONFLICTING_STATIC_GETTER_AND_INSTANCE_SETTER, nameNode, [setterType.displayName]);
     return true;
   }
 
   /**
    * This verifies that the enclosing class does not have an instance member with the same name as
    * the passed static getter method declaration.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#CONFLICTING_STATIC_SETTER_AND_INSTANCE_MEMBER
    */
   bool checkForConflictingStaticSetterAndInstanceMember(MethodDeclaration node) {
     if (!node.isStatic) {
       return false;
     }
+    // prepare name
     SimpleIdentifier nameNode = node.name;
     if (nameNode == null) {
       return false;
     }
     String name = nameNode.name;
+    // prepare enclosing type
     if (_enclosingClass == null) {
       return false;
     }
     InterfaceType enclosingType = _enclosingClass.type;
+    // try to find member
     ExecutableElement member;
     member = enclosingType.lookUpMethod(name, _currentLibrary);
     if (member == null) {
       member = enclosingType.lookUpGetter(name, _currentLibrary);
     }
     if (member == null) {
       member = enclosingType.lookUpSetter(name, _currentLibrary);
     }
     if (member == null) {
       return false;
     }
+    // OK, also static
     if (member.isStatic) {
       return false;
     }
+    // prepare "member" type to report its name
     ClassElement memberClass = member.enclosingElement as ClassElement;
     InterfaceType memberType = memberClass.type;
+    // report problem
     _errorReporter.reportError3(StaticWarningCode.CONFLICTING_STATIC_SETTER_AND_INSTANCE_MEMBER, nameNode, [memberType.displayName]);
     return true;
   }
 
   /**
    * This verifies all conflicts between type variable and enclosing class. TODO(scheglov)
    *
    * @param node the class declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONFLICTING_TYPE_VARIABLE_AND_CLASS
    * @see CompileTimeErrorCode#CONFLICTING_TYPE_VARIABLE_AND_MEMBER
    */
   bool checkForConflictingTypeVariableErrorCodes(ClassDeclaration node) {
     bool problemReported = false;
     for (TypeParameterElement typeParameter in _enclosingClass.typeParameters) {
       String name = typeParameter.name;
+      // name is same as the name of the enclosing class
       if (_enclosingClass.name == name) {
         _errorReporter.reportError5(CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_CLASS, typeParameter.nameOffset, name.length, [name]);
         problemReported = true;
       }
+      // check members
       if (_enclosingClass.getMethod(name) != null || _enclosingClass.getGetter(name) != null || _enclosingClass.getSetter(name) != null) {
         _errorReporter.reportError5(CompileTimeErrorCode.CONFLICTING_TYPE_VARIABLE_AND_MEMBER, typeParameter.nameOffset, name.length, [name]);
         problemReported = true;
       }
     }
     return problemReported;
   }
 
   /**
    * This verifies that if the passed constructor declaration is 'const' then there are no
    * invocations of non-'const' super constructors.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_CONSTRUCTOR_WITH_NON_CONST_SUPER
    */
   bool checkForConstConstructorWithNonConstSuper(ConstructorDeclaration node) {
     if (!_isEnclosingConstructorConst) {
       return false;
     }
+    // OK, const factory, checked elsewhere
     if (node.factoryKeyword != null) {
       return false;
     }
+    // try to find and check super constructor invocation
     for (ConstructorInitializer initializer in node.initializers) {
       if (initializer is SuperConstructorInvocation) {
         SuperConstructorInvocation superInvocation = initializer;
         ConstructorElement element = superInvocation.staticElement;
         if (element == null || element.isConst) {
           return false;
         }
         _errorReporter.reportError3(CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_NON_CONST_SUPER, superInvocation, []);
         return true;
       }
     }
+    // no explicit super constructor invocation, check default constructor
     InterfaceType supertype = _enclosingClass.supertype;
     if (supertype == null) {
       return false;
     }
     if (supertype.isObject) {
       return false;
     }
     ConstructorElement unnamedConstructor = supertype.element.unnamedConstructor;
     if (unnamedConstructor == null) {
       return false;
     }
     if (unnamedConstructor.isConst) {
       return false;
     }
+    // default constructor is not 'const', report problem
     _errorReporter.reportError3(CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_NON_CONST_SUPER, node, []);
     return true;
   }
 
   /**
    * This verifies that if the passed constructor declaration is 'const' then there are no non-final
    * instance variable.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_CONSTRUCTOR_WITH_NON_FINAL_FIELD
    */
   bool checkForConstConstructorWithNonFinalField(ConstructorDeclaration node) {
     if (!_isEnclosingConstructorConst) {
       return false;
     }
+    // check if there is non-final field
     ConstructorElement constructorElement = node.element;
     ClassElement classElement = constructorElement.enclosingElement;
     if (!classElement.hasNonFinalField()) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.CONST_CONSTRUCTOR_WITH_NON_FINAL_FIELD, node, []);
     return true;
   }
 
   /**
    * This verifies that the passed throw expression is not enclosed in a 'const' constructor
    * declaration.
    *
    * @param node the throw expression expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
@@ skipping 28 matching lines @@
    *
    * @param key the expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_MAP_KEY_EXPRESSION_TYPE_IMPLEMENTS_EQUALS
    */
   bool checkForConstMapKeyExpressionTypeImplementsEquals(Expression key) {
     Type2 type = key.staticType;
     if (!implementsEqualsWhenNotAllowed(type)) {
       return false;
     }
+    // report error
     _errorReporter.reportError3(CompileTimeErrorCode.CONST_MAP_KEY_EXPRESSION_TYPE_IMPLEMENTS_EQUALS, key, [type.displayName]);
     return true;
   }
 
   /**
    * This verifies that the all keys of the passed map literal have class type that does not declare
    * operator <i>==<i>.
    *
    * @param key the map literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_MAP_KEY_EXPRESSION_TYPE_IMPLEMENTS_EQUALS
    */
   bool checkForConstMapKeyExpressionTypeImplementsEquals2(MapLiteral node) {
+    // OK, not const.
     if (node.constKeyword == null) {
       return false;
     }
+    // Check every map entry.
     bool hasProblems = false;
     for (MapLiteralEntry entry in node.entries) {
       Expression key = entry.key;
       hasProblems = javaBooleanOr(hasProblems, checkForConstMapKeyExpressionTypeImplementsEquals(key));
     }
     return hasProblems;
   }
 
   /**
    * This verifies that the passed instance creation expression is not being invoked on an abstract
@@ skipping 61 matching lines @@
   }
 
   /**
    * This verifies that the passed type name does not reference any type parameters.
    *
    * @param typeName the type name to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_WITH_TYPE_PARAMETERS
    */
   bool checkForConstWithTypeParameters2(TypeName typeName) {
+    // something wrong with AST
     if (typeName == null) {
       return false;
     }
     Identifier name = typeName.name;
     if (name == null) {
       return false;
     }
+    // should not be a type parameter
     if (name.staticElement is TypeParameterElement) {
       _errorReporter.reportError3(CompileTimeErrorCode.CONST_WITH_TYPE_PARAMETERS, name, []);
     }
+    // check type arguments
     TypeArgumentList typeArguments = typeName.typeArguments;
     if (typeArguments != null) {
       bool hasError = false;
       for (TypeName argument in typeArguments.arguments) {
         hasError = javaBooleanOr(hasError, checkForConstWithTypeParameters2(argument));
       }
       return hasError;
     }
+    // OK
     return false;
   }
 
   /**
    * This verifies that if the passed 'const' instance creation expression is being invoked on the
    * resolved constructor.
    *
    * This method assumes that the instance creation was tested to be 'const' before being called.
    *
    * @param node the instance creation expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_WITH_UNDEFINED_CONSTRUCTOR
    * @see CompileTimeErrorCode#CONST_WITH_UNDEFINED_CONSTRUCTOR_DEFAULT
    */
   bool checkForConstWithUndefinedConstructor(InstanceCreationExpression node) {
+    // OK if resolved
     if (node.staticElement != null) {
       return false;
     }
+    // prepare constructor name
     ConstructorName constructorName = node.constructorName;
     if (constructorName == null) {
       return false;
     }
+    // prepare class name
     TypeName type = constructorName.type;
     if (type == null) {
       return false;
     }
     Identifier className = type.name;
+    // report as named or default constructor absence
     SimpleIdentifier name = constructorName.name;
     if (name != null) {
       _errorReporter.reportError3(CompileTimeErrorCode.CONST_WITH_UNDEFINED_CONSTRUCTOR, name, [className, name]);
     } else {
       _errorReporter.reportError3(CompileTimeErrorCode.CONST_WITH_UNDEFINED_CONSTRUCTOR_DEFAULT, constructorName, [className]);
     }
     return true;
   }
 
   /**
@@ skipping 21 matching lines @@
 
   /**
    * This verifies that the given default formal parameter is not part of a function typed
    * parameter.
    *
    * @param node the default formal parameter to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#DEFAULT_VALUE_IN_FUNCTION_TYPED_PARAMETER
    */
   bool checkForDefaultValueInFunctionTypedParameter(DefaultFormalParameter node) {
+    // OK, not in a function typed parameter.
     if (!_isInFunctionTypedFormalParameter) {
       return false;
     }
+    // OK, no default value.
     if (node.defaultValue == null) {
       return false;
     }
+    // Report problem.
     _errorReporter.reportError3(CompileTimeErrorCode.DEFAULT_VALUE_IN_FUNCTION_TYPED_PARAMETER, node, []);
     return true;
   }
 
   /**
    * This verifies that the enclosing class does not have an instance member with the given name of
    * the static member.
    *
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#DUPLICATE_DEFINITION_INHERITANCE
@@ skipping 20 matching lines @@
 
   /**
    * This verifies that the enclosing class does not have an instance member with the given name of
    * the static member.
    *
    * @param staticMember the static member to check conflict for
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#DUPLICATE_DEFINITION_INHERITANCE
    */
   bool checkForDuplicateDefinitionInheritance2(ExecutableElement staticMember) {
+    // prepare name
     String name = staticMember.name;
     if (name == null) {
       return false;
     }
+    // try to find member
     ExecutableElement inheritedMember = _inheritanceManager.lookupInheritance(_enclosingClass, name);
     if (inheritedMember == null) {
       return false;
     }
+    // OK, also static
     if (inheritedMember.isStatic) {
       return false;
     }
+    // report problem
     _errorReporter.reportError5(CompileTimeErrorCode.DUPLICATE_DEFINITION_INHERITANCE, staticMember.nameOffset, name.length, [name, inheritedMember.enclosingElement.displayName]);
     return true;
   }
 
   /**
    * This verifies if the passed list literal has type arguments then there is exactly one.
    *
    * @param node the list literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#EXPECTED_ONE_LIST_TYPE_ARGUMENTS
    */
   bool checkForExpectedOneListTypeArgument(ListLiteral node) {
+    // prepare type arguments
     TypeArgumentList typeArguments = node.typeArguments;
     if (typeArguments == null) {
       return false;
     }
+    // check number of type arguments
     int num = typeArguments.arguments.length;
     if (num == 1) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticTypeWarningCode.EXPECTED_ONE_LIST_TYPE_ARGUMENTS, typeArguments, [num]);
     return true;
   }
 
   /**
    * This verifies the passed import has unique name among other exported libraries.
    *
    * @param node the export directive to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#EXPORT_DUPLICATED_LIBRARY_NAME
    */
   bool checkForExportDuplicateLibraryName(ExportDirective node) {
+    // prepare import element
     Element nodeElement = node.element;
     if (nodeElement is! ExportElement) {
       return false;
     }
     ExportElement nodeExportElement = nodeElement as ExportElement;
+    // prepare exported library
     LibraryElement nodeLibrary = nodeExportElement.exportedLibrary;
     if (nodeLibrary == null) {
       return false;
     }
     String name = nodeLibrary.name;
+    // check if there is other exported library with the same name
     LibraryElement prevLibrary = _nameToExportElement[name];
     if (prevLibrary != null) {
       if (prevLibrary != nodeLibrary) {
         _errorReporter.reportError3(StaticWarningCode.EXPORT_DUPLICATED_LIBRARY_NAME, node, [
             prevLibrary.definingCompilationUnit.displayName,
             nodeLibrary.definingCompilationUnit.displayName,
             name]);
         return true;
       }
     } else {
       _nameToExportElement[name] = nodeLibrary;
     }
+    // OK
     return false;
   }
 
   /**
    * Check that if the visiting library is not system, then any passed library should not be SDK
    * internal library.
    *
    * @param node the export directive to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#EXPORT_INTERNAL_LIBRARY
    */
   bool checkForExportInternalLibrary(ExportDirective node) {
     if (_isInSystemLibrary) {
       return false;
     }
+    // prepare export element
     Element element = node.element;
     if (element is! ExportElement) {
       return false;
     }
     ExportElement exportElement = element as ExportElement;
+    // should be private
     DartSdk sdk = _currentLibrary.context.sourceFactory.dartSdk;
     String uri = exportElement.uri;
     SdkLibrary sdkLibrary = sdk.getSdkLibrary(uri);
     if (sdkLibrary == null) {
       return false;
     }
     if (!sdkLibrary.isInternal) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.EXPORT_INTERNAL_LIBRARY, node, [node.uri]);
     return true;
   }
 
   /**
    * This verifies that the passed extends clause does not extend classes such as num or String.
    *
    * @param node the extends clause to test
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#EXTENDS_DISALLOWED_CLASS
@@ skipping 16 matching lines @@
    * @see CompileTimeErrorCode#EXTENDS_DISALLOWED_CLASS
    * @see CompileTimeErrorCode#IMPLEMENTS_DISALLOWED_CLASS
    */
   bool checkForExtendsOrImplementsDisallowedClass(TypeName typeName, ErrorCode errorCode) {
     if (typeName.isSynthetic) {
       return false;
     }
     Type2 superType = typeName.type;
     for (InterfaceType disallowedType in _DISALLOWED_TYPES_TO_EXTEND_OR_IMPLEMENT) {
       if (superType != null && superType == disallowedType) {
+        // if the violating type happens to be 'num', we need to rule out the case where the
+        // enclosing class is 'int' or 'double'
         if (superType == _typeProvider.numType) {
           ASTNode grandParent = typeName.parent.parent;
+          // Note: this is a corner case that won't happen often, so adding a field currentClass
+          // (see currentFunction) to ErrorVerifier isn't worth if for this case, but if the field
+          // currentClass is added, then this message should become a todo to not lookup the
+          // grandparent node
           if (grandParent is ClassDeclaration) {
             ClassElement classElement = grandParent.element;
             Type2 classType = classElement.type;
             if (classType != null && (classType == _typeProvider.intType || classType == _typeProvider.doubleType)) {
               return false;
             }
           }
         }
+        // otherwise, report the error
         _errorReporter.reportError3(errorCode, typeName, [disallowedType.displayName]);
         return true;
       }
     }
     return false;
   }
 
   /**
    * This verifies that the passed constructor field initializer has compatible field and
    * initializer expression types.
    *
    * @param node the constructor field initializer to test
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#CONST_FIELD_INITIALIZER_NOT_ASSIGNABLE
    * @see StaticWarningCode#FIELD_INITIALIZER_NOT_ASSIGNABLE
    */
   bool checkForFieldInitializerNotAssignable(ConstructorFieldInitializer node) {
+    // prepare field element
     Element fieldNameElement = node.fieldName.staticElement;
     if (fieldNameElement is! FieldElement) {
       return false;
     }
     FieldElement fieldElement = fieldNameElement as FieldElement;
+    // prepare field type
     Type2 fieldType = fieldElement.type;
+    // prepare expression type
     Expression expression = node.expression;
     if (expression == null) {
       return false;
     }
+    // test the static type of the expression
     Type2 staticType = getStaticType(expression);
     if (staticType == null) {
       return false;
     }
     if (staticType.isAssignableTo(fieldType)) {
       return false;
     }
+    // report problem
     if (_isEnclosingConstructorConst) {
       _errorReporter.reportError3(CompileTimeErrorCode.CONST_FIELD_INITIALIZER_NOT_ASSIGNABLE, expression, [staticType.displayName, fieldType.displayName]);
     } else {
       _errorReporter.reportError3(StaticWarningCode.FIELD_INITIALIZER_NOT_ASSIGNABLE, expression, [staticType.displayName, fieldType.displayName]);
     }
     return true;
   }
 
   /**
    * This verifies that the passed field formal parameter is in a constructor declaration.
    *
    * @param node the field formal parameter to test
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#FIELD_INITIALIZER_OUTSIDE_CONSTRUCTOR
    */
   bool checkForFieldInitializingFormalRedirectingConstructor(FieldFormalParameter node) {
     ConstructorDeclaration constructor = node.getAncestor(ConstructorDeclaration);
     if (constructor == null) {
       _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZER_OUTSIDE_CONSTRUCTOR, node, []);
       return true;
     }
+    // constructor cannot be a factory
     if (constructor.factoryKeyword != null) {
       _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZER_FACTORY_CONSTRUCTOR, node, []);
       return true;
     }
+    // constructor cannot have a redirection
     for (ConstructorInitializer initializer in constructor.initializers) {
       if (initializer is RedirectingConstructorInvocation) {
         _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZER_REDIRECTING_CONSTRUCTOR, node, []);
         return true;
       }
     }
+    // OK
     return false;
   }
 
   /**
    * This verifies that final fields that are declared, without any constructors in the enclosing
    * class, are initialized. Cases in which there is at least one constructor are handled at the end
    * of [checkForAllFinalInitializedErrorCodes].
    *
    * @param node the class declaration to test
    * @return `true` if and only if an error code is generated on the passed node
@@ skipping 75 matching lines @@
    *
    * @param node the simple identifier to test
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#IMPLICIT_THIS_REFERENCE_IN_INITIALIZER
    * @see CompileTimeErrorCode#INSTANCE_MEMBER_ACCESS_FROM_STATIC TODO(scheglov) rename thid method
    */
   bool checkForImplicitThisReferenceInInitializer(SimpleIdentifier node) {
     if (!_isInConstructorInitializer && !_isInStaticMethod && !_isInInstanceVariableInitializer && !_isInStaticVariableDeclaration) {
       return false;
     }
+    // prepare element
     Element element = node.staticElement;
     if (!(element is MethodElement || element is PropertyAccessorElement)) {
       return false;
     }
+    // static element
     ExecutableElement executableElement = element as ExecutableElement;
     if (executableElement.isStatic) {
       return false;
     }
+    // not a class member
     Element enclosingElement = element.enclosingElement;
     if (enclosingElement is! ClassElement) {
       return false;
     }
+    // comment
     ASTNode parent = node.parent;
     if (parent is CommentReference) {
       return false;
     }
+    // qualified method invocation
     if (parent is MethodInvocation) {
       MethodInvocation invocation = parent;
       if (identical(invocation.methodName, node) && invocation.realTarget != null) {
         return false;
       }
     }
+    // qualified property access
     if (parent is PropertyAccess) {
       PropertyAccess access = parent;
       if (identical(access.propertyName, node) && access.realTarget != null) {
         return false;
       }
     }
     if (parent is PrefixedIdentifier) {
       PrefixedIdentifier prefixed = parent;
       if (identical(prefixed.identifier, node)) {
         return false;
       }
     }
+    // report problem
     if (_isInStaticMethod) {
       _errorReporter.reportError3(CompileTimeErrorCode.INSTANCE_MEMBER_ACCESS_FROM_STATIC, node, []);
     } else {
       _errorReporter.reportError3(CompileTimeErrorCode.IMPLICIT_THIS_REFERENCE_IN_INITIALIZER, node, []);
     }
     return true;
   }
 
   /**
    * This verifies the passed import has unique name among other imported libraries.
    *
    * @param node the import directive to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#IMPORT_DUPLICATED_LIBRARY_NAME
    */
   bool checkForImportDuplicateLibraryName(ImportDirective node) {
+    // prepare import element
     ImportElement nodeImportElement = node.element;
     if (nodeImportElement == null) {
       return false;
     }
+    // prepare imported library
     LibraryElement nodeLibrary = nodeImportElement.importedLibrary;
     if (nodeLibrary == null) {
       return false;
     }
     String name = nodeLibrary.name;
+    // check if there is other imported library with the same name
     LibraryElement prevLibrary = _nameToImportElement[name];
     if (prevLibrary != null) {
       if (prevLibrary != nodeLibrary) {
         _errorReporter.reportError3(StaticWarningCode.IMPORT_DUPLICATED_LIBRARY_NAME, node, [
             prevLibrary.definingCompilationUnit.displayName,
             nodeLibrary.definingCompilationUnit.displayName,
             name]);
         return true;
       }
     } else {
       _nameToImportElement[name] = nodeLibrary;
     }
+    // OK
     return false;
   }
 
   /**
    * Check that if the visiting library is not system, then any passed library should not be SDK
    * internal library.
    *
    * @param node the import directive to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#IMPORT_INTERNAL_LIBRARY
    */
   bool checkForImportInternalLibrary(ImportDirective node) {
     if (_isInSystemLibrary) {
       return false;
     }
+    // prepare import element
     ImportElement importElement = node.element;
     if (importElement == null) {
       return false;
     }
+    // should be private
     DartSdk sdk = _currentLibrary.context.sourceFactory.dartSdk;
     String uri = importElement.uri;
     SdkLibrary sdkLibrary = sdk.getSdkLibrary(uri);
     if (sdkLibrary == null) {
       return false;
     }
     if (!sdkLibrary.isInternal) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.IMPORT_INTERNAL_LIBRARY, node, [node.uri]);
     return true;
   }
 
   /**
    * This verifies that the passed switch statement case expressions all have the same type.
    *
    * @param node the switch statement to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#INCONSISTENT_CASE_EXPRESSION_TYPES
    */
   bool checkForInconsistentCaseExpressionTypes(SwitchStatement node) {
+    // TODO(jwren) Revisit this algorithm, should there up to n-1 errors?
     NodeList<SwitchMember> switchMembers = node.members;
     bool foundError = false;
     Type2 firstType = null;
     for (SwitchMember switchMember in switchMembers) {
       if (switchMember is SwitchCase) {
         SwitchCase switchCase = switchMember;
         Expression expression = switchCase.expression;
         if (firstType == null) {
+          // TODO(brianwilkerson) This is failing with const variables whose declared type is
+          // dynamic. The problem is that we don't have any way to propagate type information for
+          // the variable.
           firstType = expression.bestType;
         } else {
           Type2 nType = expression.bestType;
           if (firstType != nType) {
             _errorReporter.reportError3(CompileTimeErrorCode.INCONSISTENT_CASE_EXPRESSION_TYPES, expression, [expression.toSource(), firstType.displayName]);
             foundError = true;
           }
         }
       }
     }
     if (!foundError) {
       checkForCaseExpressionTypeImplementsEquals(node, firstType);
     }
     return foundError;
   }
 
   /**
    * For each class declaration, this method is called which verifies that all inherited members are
    * inherited consistently.
    *
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#INCONSISTENT_METHOD_INHERITANCE
    */
   bool checkForInconsistentMethodInheritance() {
+    // Ensure that the inheritance manager has a chance to generate all errors we may care about,
+    // note that we ensure that the interfaces data since there are no errors.
     _inheritanceManager.getMapOfMembersInheritedFromInterfaces(_enclosingClass);
     Set<AnalysisError> errors = _inheritanceManager.getErrors(_enclosingClass);
     if (errors == null || errors.isEmpty) {
       return false;
     }
     for (AnalysisError error in errors) {
       _errorReporter.reportError(error);
     }
     return true;
   }
 
   /**
    * This checks the given "typeReference" is not a type reference and that then the "name" is
    * reference to an instance member.
    *
    * @param typeReference the resolved [ClassElement] of the left hand side of the expression,
    *          or `null`, aka, the class element of 'C' in 'C.x', see
    *          [getTypeReference]
    * @param name the accessed name to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#INSTANCE_ACCESS_TO_STATIC_MEMBER
    */
   bool checkForInstanceAccessToStaticMember(ClassElement typeReference, SimpleIdentifier name) {
+    // OK, in comment
     if (_isInComment) {
       return false;
     }
+    // OK, target is a type
     if (typeReference != null) {
       return false;
     }
+    // prepare member Element
     Element element = name.staticElement;
     if (element is! ExecutableElement) {
       return false;
     }
     ExecutableElement executableElement = element as ExecutableElement;
+    // OK, top-level element
     if (executableElement.enclosingElement is! ClassElement) {
       return false;
     }
+    // OK, instance member
     if (!executableElement.isStatic) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticTypeWarningCode.INSTANCE_ACCESS_TO_STATIC_MEMBER, name, [name.name]);
     return true;
   }
 
   /**
    * This verifies that an 'int' can be assigned to the parameter corresponding to the given
    * expression. This is used for prefix and postfix expressions where the argument value is
    * implicit.
    *
    * @param argument the expression to which the operator is being applied
@@ skipping 54 matching lines @@
       return false;
     }
     VariableElement leftElement = getVariableElement(lhs);
     Type2 leftType = (leftElement == null) ? getStaticType(lhs) : leftElement.type;
     Type2 staticRightType = getStaticType(rhs);
     bool isStaticAssignable = staticRightType.isAssignableTo(leftType);
     if (!isStaticAssignable) {
       _errorReporter.reportError3(StaticTypeWarningCode.INVALID_ASSIGNMENT, rhs, [staticRightType.displayName, leftType.displayName]);
       return true;
     }
+    // TODO(brianwilkerson) Define a hint corresponding to the warning and report it if appropriate.
+    //    Type propagatedRightType = rhs.getPropagatedType();
+    //    boolean isPropagatedAssignable = propagatedRightType.isAssignableTo(leftType);
+    //    if (!isStaticAssignable && !isPropagatedAssignable) {
+    //      errorReporter.reportError(
+    //          StaticTypeWarningCode.INVALID_ASSIGNMENT,
+    //          rhs,
+    //          staticRightType.getDisplayName(),
+    //          leftType.getDisplayName());
+    //      return true;
+    //    }
     return false;
   }
 
   /**
    * This verifies that the usage of the passed 'this' is valid.
    *
    * @param node the 'this' expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#INVALID_REFERENCE_TO_THIS
    */
@@ skipping 29 matching lines @@
   /**
    * This verifies that the elements given [ListLiteral] are subtypes of the specified element
    * type.
    *
    * @param node the list literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#LIST_ELEMENT_TYPE_NOT_ASSIGNABLE
    * @see StaticWarningCode#LIST_ELEMENT_TYPE_NOT_ASSIGNABLE
    */
   bool checkForListElementTypeNotAssignable(ListLiteral node) {
+    // Prepare list element type.
     TypeArgumentList typeArgumentList = node.typeArguments;
     if (typeArgumentList == null) {
       return false;
     }
     NodeList<TypeName> typeArguments = typeArgumentList.arguments;
     if (typeArguments.length < 1) {
       return false;
     }
     Type2 listElementType = typeArguments[0].type;
+    // Prepare problem to report.
     ErrorCode errorCode;
     if (node.constKeyword != null) {
       errorCode = CompileTimeErrorCode.LIST_ELEMENT_TYPE_NOT_ASSIGNABLE;
     } else {
       errorCode = StaticWarningCode.LIST_ELEMENT_TYPE_NOT_ASSIGNABLE;
     }
+    // Check every list element.
     bool hasProblems = false;
     for (Expression element in node.elements) {
       hasProblems = javaBooleanOr(hasProblems, checkForArgumentTypeNotAssignable3(element, listElementType, null, errorCode));
     }
     return hasProblems;
   }
 
   /**
    * This verifies that the key/value of entries of the given [MapLiteral] are subtypes of the
    * key/value types specified in the type arguments.
    *
    * @param node the map literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#MAP_KEY_TYPE_NOT_ASSIGNABLE
    * @see CompileTimeErrorCode#MAP_VALUE_TYPE_NOT_ASSIGNABLE
    * @see StaticWarningCode#MAP_KEY_TYPE_NOT_ASSIGNABLE
    * @see StaticWarningCode#MAP_VALUE_TYPE_NOT_ASSIGNABLE
    */
   bool checkForMapTypeNotAssignable(MapLiteral node) {
+    // Prepare maps key/value types.
     TypeArgumentList typeArgumentList = node.typeArguments;
     if (typeArgumentList == null) {
       return false;
     }
     NodeList<TypeName> typeArguments = typeArgumentList.arguments;
     if (typeArguments.length < 2) {
       return false;
     }
     Type2 keyType = typeArguments[0].type;
     Type2 valueType = typeArguments[1].type;
+    // Prepare problem to report.
     ErrorCode keyErrorCode;
     ErrorCode valueErrorCode;
     if (node.constKeyword != null) {
       keyErrorCode = CompileTimeErrorCode.MAP_KEY_TYPE_NOT_ASSIGNABLE;
       valueErrorCode = CompileTimeErrorCode.MAP_VALUE_TYPE_NOT_ASSIGNABLE;
     } else {
       keyErrorCode = StaticWarningCode.MAP_KEY_TYPE_NOT_ASSIGNABLE;
       valueErrorCode = StaticWarningCode.MAP_VALUE_TYPE_NOT_ASSIGNABLE;
     }
+    // Check every map entry.
     bool hasProblems = false;
     NodeList<MapLiteralEntry> entries = node.entries;
     for (MapLiteralEntry entry in entries) {
       Expression key = entry.key;
       Expression value = entry.value;
       hasProblems = javaBooleanOr(hasProblems, checkForArgumentTypeNotAssignable3(key, keyType, null, keyErrorCode));
       hasProblems = javaBooleanOr(hasProblems, checkForArgumentTypeNotAssignable3(value, valueType, null, valueErrorCode));
     }
     return hasProblems;
   }
 
   /**
    * This verifies that the [enclosingClass] does not define members with the same name as
    * the enclosing class.
    *
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#MEMBER_WITH_CLASS_NAME
    */
   bool checkForMemberWithClassName() {
     if (_enclosingClass == null) {
       return false;
     }
     String className = _enclosingClass.name;
     if (className == null) {
       return false;
     }
     bool problemReported = false;
+    // check accessors
     for (PropertyAccessorElement accessor in _enclosingClass.accessors) {
       if (className == accessor.name) {
         _errorReporter.reportError5(CompileTimeErrorCode.MEMBER_WITH_CLASS_NAME, accessor.nameOffset, className.length, []);
         problemReported = true;
       }
     }
+    // don't check methods, they would be constructors
+    // done
     return problemReported;
   }
 
   /**
    * Check to make sure that all similarly typed accessors are of the same type (including inherited
    * accessors).
    *
    * @param node the accessor currently being visited
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode.MISMATCHED_GETTER_AND_SETTER_TYPES
    * @see StaticWarningCode.MISMATCHED_GETTER_AND_SETTER_TYPES_FROM_SUPERTYPE
    */
   bool checkForMismatchedAccessorTypes(Declaration accessorDeclaration, String accessorTextName) {
     ExecutableElement accessorElement = accessorDeclaration.element as ExecutableElement;
     if (accessorElement is! PropertyAccessorElement) {
       return false;
     }
     PropertyAccessorElement propertyAccessorElement = accessorElement as PropertyAccessorElement;
     PropertyAccessorElement counterpartAccessor = null;
     ClassElement enclosingClassForCounterpart = null;
     if (propertyAccessorElement.isGetter) {
       counterpartAccessor = propertyAccessorElement.correspondingSetter;
     } else {
       counterpartAccessor = propertyAccessorElement.correspondingGetter;
+      // If the setter and getter are in the same enclosing element, return, this prevents having
+      // MISMATCHED_GETTER_AND_SETTER_TYPES reported twice.
       if (counterpartAccessor != null && identical(counterpartAccessor.enclosingElement, propertyAccessorElement.enclosingElement)) {
         return false;
       }
     }
     if (counterpartAccessor == null) {
+      // If the accessor is declared in a class, check the superclasses.
       if (_enclosingClass != null) {
+        // Figure out the correct identifier to lookup in the inheritance graph, if 'x', then 'x=',
+        // or if 'x=', then 'x'.
         String lookupIdentifier = propertyAccessorElement.name;
         if (lookupIdentifier.endsWith("=")) {
           lookupIdentifier = lookupIdentifier.substring(0, lookupIdentifier.length - 1);
         } else {
           lookupIdentifier += "=";
         }
+        // lookup with the identifier.
         ExecutableElement elementFromInheritance = _inheritanceManager.lookupInheritance(_enclosingClass, lookupIdentifier);
+        // Verify that we found something, and that it is an accessor
         if (elementFromInheritance != null && elementFromInheritance is PropertyAccessorElement) {
           enclosingClassForCounterpart = elementFromInheritance.enclosingElement as ClassElement;
           counterpartAccessor = elementFromInheritance;
         }
       }
       if (counterpartAccessor == null) {
         return false;
       }
     }
+    // Default of null == no accessor or no type (dynamic)
     Type2 getterType = null;
     Type2 setterType = null;
+    // Get an existing counterpart accessor if any.
     if (propertyAccessorElement.isGetter) {
       getterType = getGetterType(propertyAccessorElement);
       setterType = getSetterType(counterpartAccessor);
     } else if (propertyAccessorElement.isSetter) {
       setterType = getSetterType(propertyAccessorElement);
       getterType = getGetterType(counterpartAccessor);
     }
+    // If either types are not assignable to each other, report an error (if the getter is null,
+    // it is dynamic which is assignable to everything).
     if (setterType != null && getterType != null && !getterType.isAssignableTo(setterType)) {
       if (enclosingClassForCounterpart == null) {
         _errorReporter.reportError3(StaticWarningCode.MISMATCHED_GETTER_AND_SETTER_TYPES, accessorDeclaration, [
             accessorTextName,
             setterType.displayName,
             getterType.displayName]);
         return true;
       } else {
         _errorReporter.reportError3(StaticWarningCode.MISMATCHED_GETTER_AND_SETTER_TYPES_FROM_SUPERTYPE, accessorDeclaration, [
             accessorTextName,
@@ skipping 94 matching lines @@
   }
 
   /**
    * Checks to ensure that native function bodies can only in SDK code.
    *
    * @param node the native function body to test
    * @return `true` if and only if an error code is generated on the passed node
    * @see ParserErrorCode#NATIVE_FUNCTION_BODY_IN_NON_SDK_CODE
    */
   bool checkForNativeFunctionBodyInNonSDKCode(NativeFunctionBody node) {
+    // TODO(brianwilkerson) Figure out the right rule for when 'native' is allowed.
     if (!_isInSystemLibrary) {
       _errorReporter.reportError3(ParserErrorCode.NATIVE_FUNCTION_BODY_IN_NON_SDK_CODE, node, []);
       return true;
     }
     return false;
   }
 
   /**
    * This verifies that the passed 'new' instance creation expression invokes existing constructor.
    *
    * This method assumes that the instance creation was tested to be 'new' before being called.
    *
    * @param node the instance creation expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#NEW_WITH_UNDEFINED_CONSTRUCTOR
    */
   bool checkForNewWithUndefinedConstructor(InstanceCreationExpression node) {
+    // OK if resolved
     if (node.staticElement != null) {
       return false;
     }
+    // prepare constructor name
     ConstructorName constructorName = node.constructorName;
     if (constructorName == null) {
       return false;
     }
+    // prepare class name
     TypeName type = constructorName.type;
     if (type == null) {
       return false;
     }
     Identifier className = type.name;
+    // report as named or default constructor absence
     SimpleIdentifier name = constructorName.name;
     if (name != null) {
       _errorReporter.reportError3(StaticWarningCode.NEW_WITH_UNDEFINED_CONSTRUCTOR, name, [className, name]);
     } else {
       _errorReporter.reportError3(StaticWarningCode.NEW_WITH_UNDEFINED_CONSTRUCTOR_DEFAULT, constructorName, [className]);
     }
     return true;
   }
 
   /**
    * This checks that if the passed class declaration implicitly calls default constructor of its
    * superclass, there should be such default constructor - implicit or explicit.
    *
    * @param node the [ClassDeclaration] to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#NO_DEFAULT_SUPER_CONSTRUCTOR_IMPLICIT
    */
   bool checkForNoDefaultSuperConstructorImplicit(ClassDeclaration node) {
+    // do nothing if there is explicit constructor
     List<ConstructorElement> constructors = _enclosingClass.constructors;
     if (!constructors[0].isSynthetic) {
       return false;
     }
+    // prepare super
     InterfaceType superType = _enclosingClass.supertype;
     if (superType == null) {
       return false;
     }
     ClassElement superElement = superType.element;
+    // try to find default generative super constructor
     ConstructorElement superUnnamedConstructor = superElement.unnamedConstructor;
     if (superUnnamedConstructor != null) {
       if (superUnnamedConstructor.isFactory) {
         _errorReporter.reportError3(CompileTimeErrorCode.NON_GENERATIVE_CONSTRUCTOR, node.name, [superUnnamedConstructor]);
         return true;
       }
       if (superUnnamedConstructor.isDefaultConstructor) {
         return true;
       }
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.NO_DEFAULT_SUPER_CONSTRUCTOR_IMPLICIT, node.name, [superType.displayName]);
     return true;
   }
 
   /**
    * This checks that passed class declaration overrides all members required by its superclasses
    * and interfaces.
    *
    * @param node the [ClassDeclaration] to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#NON_ABSTRACT_CLASS_INHERITS_ABSTRACT_MEMBER_ONE
    * @see StaticWarningCode#NON_ABSTRACT_CLASS_INHERITS_ABSTRACT_MEMBER_TWO
    * @see StaticWarningCode#NON_ABSTRACT_CLASS_INHERITS_ABSTRACT_MEMBER_THREE
    * @see StaticWarningCode#NON_ABSTRACT_CLASS_INHERITS_ABSTRACT_MEMBER_FOUR
    * @see StaticWarningCode#NON_ABSTRACT_CLASS_INHERITS_ABSTRACT_MEMBER_FIVE_PLUS
    */
   bool checkForNonAbstractClassInheritsAbstractMember(ClassDeclaration node) {
     if (_enclosingClass.isAbstract) {
       return false;
     }
+    //
+    // Store in local sets the set of all method and accessor names
+    //
     List<MethodElement> methods = _enclosingClass.methods;
     List<PropertyAccessorElement> accessors = _enclosingClass.accessors;
     Set<String> methodsInEnclosingClass = new Set<String>();
     for (MethodElement method in methods) {
       String methodName = method.name;
+      // If the enclosing class declares the method noSuchMethod(), then return.
+      // From Spec:  It is a static warning if a concrete class does not have an implementation for
+      // a method in any of its superinterfaces unless it declares its own noSuchMethod
+      // method (7.10).
       if (methodName == ElementResolver.NO_SUCH_METHOD_METHOD_NAME) {
         return false;
       }
       methodsInEnclosingClass.add(methodName);
     }
     Set<String> accessorsInEnclosingClass = new Set<String>();
     for (PropertyAccessorElement accessor in accessors) {
       accessorsInEnclosingClass.add(accessor.name);
     }
     Set<ExecutableElement> missingOverrides = new Set<ExecutableElement>();
+    //
+    // Loop through the set of all executable elements declared in the implicit interface.
+    //
     MemberMap membersInheritedFromInterfaces = _inheritanceManager.getMapOfMembersInheritedFromInterfaces(_enclosingClass);
     MemberMap membersInheritedFromSuperclasses = _inheritanceManager.getMapOfMembersInheritedFromClasses(_enclosingClass);
     for (int i = 0; i < membersInheritedFromInterfaces.size; i++) {
       String memberName = membersInheritedFromInterfaces.getKey(i);
       ExecutableElement executableElt = membersInheritedFromInterfaces.getValue(i);
       if (memberName == null) {
         break;
       }
+      // If the element is defined in Object, skip it.
       if ((executableElt.enclosingElement as ClassElement).type.isObject) {
         continue;
       }
+      // Reference the type of the enclosing class
       InterfaceType enclosingType = _enclosingClass.type;
+      // Check to see if some element is in local enclosing class that matches the name of the
+      // required member.
       if (isMemberInClassOrMixin(executableElt, _enclosingClass)) {
+        // We do not have to verify that this implementation of the found method matches the
+        // required function type: the set of StaticWarningCode.INVALID_METHOD_OVERRIDE_* warnings
+        // break out the different specific situations.
         continue;
       }
+      // First check to see if this element was declared in the superclass chain, in which case
+      // there is already a concrete implementation.
       ExecutableElement elt = membersInheritedFromSuperclasses.get(executableElt.name);
+      // Check to see if an element was found in the superclass chain with the correct name.
       if (elt != null) {
+        // Some element was found in the superclass chain that matches the name of the required
+        // member.
+        // If it is not abstract and it is the correct one (types match- the version of this method
+        // that we have has the correct number of parameters, etc), then this class has a valid
+        // implementation of this method, so skip it.
         if ((elt is MethodElement && !elt.isAbstract) || (elt is PropertyAccessorElement && !elt.isAbstract)) {
+          // Since we are comparing two function types, we need to do the appropriate type
+          // substitutions first ().
           FunctionType foundConcreteFT = _inheritanceManager.substituteTypeArgumentsInMemberFromInheritance(elt.type, executableElt.name, enclosingType);
           FunctionType requiredMemberFT = _inheritanceManager.substituteTypeArgumentsInMemberFromInheritance(executableElt.type, executableElt.name, enclosingType);
           if (foundConcreteFT.isSubtypeOf(requiredMemberFT)) {
             continue;
           }
         }
       }
+      // The not qualifying concrete executable element was found, add it to the list.
       missingOverrides.add(executableElt);
     }
+    // Now that we have the set of missing overrides, generate a warning on this class
     int missingOverridesSize = missingOverrides.length;
     if (missingOverridesSize == 0) {
       return false;
     }
     List<ExecutableElement> missingOverridesArray = new List.from(missingOverrides);
     List<String> stringMembersArrayListSet = new List<String>();
     for (int i = 0; i < missingOverridesArray.length; i++) {
       String newStrMember = "${missingOverridesArray[i].enclosingElement.displayName}.${missingOverridesArray[i].displayName}";
       if (!stringMembersArrayListSet.contains(newStrMember)) {
         stringMembersArrayListSet.add(newStrMember);
@@ skipping 93 matching lines @@
    * * has `const modifier`
    * * has explicit type arguments
    * * is not start of the statement
    *
    *
    * @param node the map literal to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#NON_CONST_MAP_AS_EXPRESSION_STATEMENT
    */
   bool checkForNonConstMapAsExpressionStatement(MapLiteral node) {
+    // "const"
     if (node.constKeyword != null) {
       return false;
     }
+    // has type arguments
     if (node.typeArguments != null) {
       return false;
     }
+    // prepare statement
     Statement statement = node.getAncestor(ExpressionStatement);
     if (statement == null) {
       return false;
     }
+    // OK, statement does not start with map
     if (statement.beginToken != node.beginToken) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.NON_CONST_MAP_AS_EXPRESSION_STATEMENT, node, []);
     return true;
   }
 
   /**
    * This verifies the passed method declaration of operator `[]=`, has `void` return
    * type.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#NON_VOID_RETURN_FOR_OPERATOR
    */
   bool checkForNonVoidReturnTypeForOperator(MethodDeclaration node) {
+    // check that []= operator
     SimpleIdentifier name = node.name;
     if (name.name != "[]=") {
       return false;
     }
+    // check return type
     TypeName typeName = node.returnType;
     if (typeName != null) {
       Type2 type = typeName.type;
       if (type != null && !type.isVoid) {
         _errorReporter.reportError3(StaticWarningCode.NON_VOID_RETURN_FOR_OPERATOR, typeName, []);
       }
     }
+    // no warning
     return false;
   }
 
   /**
    * This verifies the passed setter has no return type or the `void` return type.
    *
    * @param typeName the type name to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#NON_VOID_RETURN_FOR_SETTER
    */
@@ skipping 34 matching lines @@
   }
 
   /**
    * This checks for named optional parameters that begin with '_'.
    *
    * @param node the default formal parameter to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#PRIVATE_OPTIONAL_PARAMETER
    */
   bool checkForPrivateOptionalParameter(FormalParameter node) {
+    // should be named parameter
     if (node.kind != ParameterKind.NAMED) {
       return false;
     }
+    // name should start with '_'
     SimpleIdentifier name = node.identifier;
     if (name.isSynthetic || !name.name.startsWith("_")) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(CompileTimeErrorCode.PRIVATE_OPTIONAL_PARAMETER, node, []);
     return true;
   }
 
   /**
    * This checks if the passed constructor declaration is the redirecting generative constructor and
    * references itself directly or indirectly.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#RECURSIVE_CONSTRUCTOR_REDIRECT
    */
   bool checkForRecursiveConstructorRedirect(ConstructorDeclaration node) {
+    // we check generative constructor here
     if (node.factoryKeyword != null) {
       return false;
     }
+    // try to find redirecting constructor invocation and analyzer it for recursion
     for (ConstructorInitializer initializer in node.initializers) {
       if (initializer is RedirectingConstructorInvocation) {
+        // OK if no cycle
         ConstructorElement element = node.element;
         if (!hasRedirectingFactoryConstructorCycle(element)) {
           return false;
         }
+        // report error
         _errorReporter.reportError3(CompileTimeErrorCode.RECURSIVE_CONSTRUCTOR_REDIRECT, initializer, []);
         return true;
       }
     }
+    // OK, no redirecting constructor invocation
     return false;
   }
 
   /**
    * This checks if the passed constructor declaration has redirected constructor and references
    * itself directly or indirectly.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#RECURSIVE_FACTORY_REDIRECT
    */
   bool checkForRecursiveFactoryRedirect(ConstructorDeclaration node) {
+    // prepare redirected constructor
     ConstructorName redirectedConstructorNode = node.redirectedConstructor;
     if (redirectedConstructorNode == null) {
       return false;
     }
+    // OK if no cycle
     ConstructorElement element = node.element;
     if (!hasRedirectingFactoryConstructorCycle(element)) {
       return false;
     }
+    // report error
     _errorReporter.reportError3(CompileTimeErrorCode.RECURSIVE_FACTORY_REDIRECT, redirectedConstructorNode, []);
     return true;
   }
 
   /**
    * This checks the class declaration is not a superinterface to itself.
    *
    * @param classElt the class element to test
    * @return `true` if and only if an error code is generated on the passed element
    * @see CompileTimeErrorCode#RECURSIVE_INTERFACE_INHERITANCE
@@ skipping 11 matching lines @@
    * This checks the class declaration is not a superinterface to itself.
    *
    * @param classElt the class element to test
    * @param path a list containing the potentially cyclic implements path
    * @return `true` if and only if an error code is generated on the passed element
    * @see CompileTimeErrorCode#RECURSIVE_INTERFACE_INHERITANCE
    * @see CompileTimeErrorCode#RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_EXTENDS
    * @see CompileTimeErrorCode#RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_IMPLEMENTS
    */
   bool checkForRecursiveInterfaceInheritance2(ClassElement classElt, List<ClassElement> path) {
+    // Detect error condition.
     int size = path.length;
+    // If this is not the base case (size > 0), and the enclosing class is the passed class
+    // element then an error an error.
     if (size > 0 && _enclosingClass == classElt) {
       String enclosingClassName = _enclosingClass.displayName;
       if (size > 1) {
+        // Construct a string showing the cyclic implements path: "A, B, C, D, A"
         String separator = ", ";
         JavaStringBuilder builder = new JavaStringBuilder();
         for (int i = 0; i < size; i++) {
           builder.append(path[i].displayName);
           builder.append(separator);
         }
         builder.append(classElt.displayName);
         _errorReporter.reportError5(CompileTimeErrorCode.RECURSIVE_INTERFACE_INHERITANCE, _enclosingClass.nameOffset, enclosingClassName.length, [enclosingClassName, builder.toString()]);
         return true;
       } else {
+        // RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_IMPLEMENTS or RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_EXTENDS
         InterfaceType supertype = classElt.supertype;
         ErrorCode errorCode = (supertype != null && _enclosingClass == supertype.element ? CompileTimeErrorCode.RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_EXTENDS : CompileTimeErrorCode.RECURSIVE_INTERFACE_INHERITANCE_BASE_CASE_IMPLEMENTS);
         _errorReporter.reportError5(errorCode, _enclosingClass.nameOffset, enclosingClassName.length, [enclosingClassName]);
         return true;
       }
     }
     if (path.indexOf(classElt) > 0) {
       return false;
     }
     path.add(classElt);
+    // n-case
     InterfaceType supertype = classElt.supertype;
     if (supertype != null && checkForRecursiveInterfaceInheritance2(supertype.element, path)) {
       return true;
     }
     List<InterfaceType> interfaceTypes = classElt.interfaces;
     for (InterfaceType interfaceType in interfaceTypes) {
       if (checkForRecursiveInterfaceInheritance2(interfaceType.element, path)) {
         return true;
       }
     }
     path.removeAt(path.length - 1);
     return false;
   }
 
   /**
    * This checks the passed constructor declaration has a valid combination of redirected
    * constructor invocation(s), super constructor invocations and field initializers.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#DEFAULT_VALUE_IN_REDIRECTING_FACTORY_CONSTRUCTOR
    * @see CompileTimeErrorCode#FIELD_INITIALIZER_REDIRECTING_CONSTRUCTOR
    * @see CompileTimeErrorCode#MULTIPLE_REDIRECTING_CONSTRUCTOR_INVOCATIONS
    * @see CompileTimeErrorCode#SUPER_IN_REDIRECTING_CONSTRUCTOR
    */
   bool checkForRedirectingConstructorErrorCodes(ConstructorDeclaration node) {
     bool errorReported = false;
+    //
+    // Check for default values in the parameters
+    //
     ConstructorName redirectedConstructor = node.redirectedConstructor;
     if (redirectedConstructor != null) {
       for (FormalParameter parameter in node.parameters.parameters) {
         if (parameter is DefaultFormalParameter && parameter.defaultValue != null) {
           _errorReporter.reportError3(CompileTimeErrorCode.DEFAULT_VALUE_IN_REDIRECTING_FACTORY_CONSTRUCTOR, parameter.identifier, []);
           errorReported = true;
         }
       }
     }
+    // check if there are redirected invocations
     int numRedirections = 0;
     for (ConstructorInitializer initializer in node.initializers) {
       if (initializer is RedirectingConstructorInvocation) {
         if (numRedirections > 0) {
           _errorReporter.reportError3(CompileTimeErrorCode.MULTIPLE_REDIRECTING_CONSTRUCTOR_INVOCATIONS, initializer, []);
           errorReported = true;
         }
         numRedirections++;
       }
     }
+    // check for other initializers
     if (numRedirections > 0) {
       for (ConstructorInitializer initializer in node.initializers) {
         if (initializer is SuperConstructorInvocation) {
           _errorReporter.reportError3(CompileTimeErrorCode.SUPER_IN_REDIRECTING_CONSTRUCTOR, initializer, []);
           errorReported = true;
         }
         if (initializer is ConstructorFieldInitializer) {
           _errorReporter.reportError3(CompileTimeErrorCode.FIELD_INITIALIZER_REDIRECTING_CONSTRUCTOR, initializer, []);
           errorReported = true;
         }
       }
     }
+    // done
     return errorReported;
   }
 
   /**
    * This checks if the passed constructor declaration has redirected constructor and references
    * itself directly or indirectly.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#REDIRECT_TO_NON_CONST_CONSTRUCTOR
    */
   bool checkForRedirectToNonConstConstructor(ConstructorDeclaration node) {
+    // prepare redirected constructor
     ConstructorName redirectedConstructorNode = node.redirectedConstructor;
     if (redirectedConstructorNode == null) {
       return false;
     }
+    // prepare element
     ConstructorElement element = node.element;
     if (element == null) {
       return false;
     }
+    // OK, it is not 'const'
     if (!element.isConst) {
       return false;
     }
+    // prepare redirected constructor
     ConstructorElement redirectedConstructor = element.redirectedConstructor;
     if (redirectedConstructor == null) {
       return false;
     }
+    // OK, it is also 'const'
     if (redirectedConstructor.isConst) {
       return false;
     }
+    // report error
     _errorReporter.reportError3(CompileTimeErrorCode.REDIRECT_TO_NON_CONST_CONSTRUCTOR, redirectedConstructorNode, []);
     return true;
   }
 
   /**
    * This checks that the rethrow is inside of a catch clause.
    *
    * @param node the rethrow expression to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#RETHROW_OUTSIDE_CATCH
    */
   bool checkForRethrowOutsideCatch(RethrowExpression node) {
     if (!_isInCatchClause) {
       _errorReporter.reportError3(CompileTimeErrorCode.RETHROW_OUTSIDE_CATCH, node, []);
       return true;
     }
     return false;
   }
 
   /**
    * This checks that if the the given constructor declaration is generative, then it does not have
    * an expression function body.
    *
    * @param node the constructor to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#RETURN_IN_GENERATIVE_CONSTRUCTOR
    */
   bool checkForReturnInGenerativeConstructor(ConstructorDeclaration node) {
+    // ignore factory
     if (node.factoryKeyword != null) {
       return false;
     }
+    // block body (with possible return statement) is checked elsewhere
     FunctionBody body = node.body;
     if (body is! ExpressionFunctionBody) {
       return false;
     }
+    // report error
     _errorReporter.reportError3(CompileTimeErrorCode.RETURN_IN_GENERATIVE_CONSTRUCTOR, body, []);
     return true;
   }
 
   /**
    * This checks that a type mis-match between the return type and the expressed return type by the
    * enclosing method or function.
    *
    * This method is called both by [checkForAllReturnStatementErrorCodes]
    * and [visitExpressionFunctionBody].
@@ skipping 31 matching lines @@
    * member.
    *
    * @param typeReference the resolved [ClassElement] of the left hand side of the expression,
    *          or `null`, aka, the class element of 'C' in 'C.x', see
    *          [getTypeReference]
    * @param name the accessed name to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#STATIC_ACCESS_TO_INSTANCE_MEMBER
    */
   bool checkForStaticAccessToInstanceMember(ClassElement typeReference, SimpleIdentifier name) {
+    // OK, target is not a type
     if (typeReference == null) {
       return false;
     }
+    // prepare member Element
     Element element = name.staticElement;
     if (element is! ExecutableElement) {
       return false;
     }
     ExecutableElement memberElement = element as ExecutableElement;
+    // OK, static
     if (memberElement.isStatic) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticWarningCode.STATIC_ACCESS_TO_INSTANCE_MEMBER, name, [name.name]);
     return true;
   }
 
   /**
    * This checks that the type of the passed 'switch' expression is assignable to the type of the
    * 'case' members.
    *
    * @param node the 'switch' statement to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticWarningCode#SWITCH_EXPRESSION_NOT_ASSIGNABLE
    */
   bool checkForSwitchExpressionNotAssignable(SwitchStatement node) {
+    // prepare 'switch' expression type
     Expression expression = node.expression;
     Type2 expressionType = getStaticType(expression);
     if (expressionType == null) {
       return false;
     }
+    // compare with type of the first 'case'
     NodeList<SwitchMember> members = node.members;
     for (SwitchMember switchMember in members) {
       if (switchMember is! SwitchCase) {
         continue;
       }
       SwitchCase switchCase = switchMember as SwitchCase;
+      // prepare 'case' type
       Expression caseExpression = switchCase.expression;
       Type2 caseType = getStaticType(caseExpression);
+      // check types
       if (expressionType.isAssignableTo(caseType)) {
         return false;
       }
+      // report problem
       _errorReporter.reportError3(StaticWarningCode.SWITCH_EXPRESSION_NOT_ASSIGNABLE, expression, [expressionType, caseType]);
       return true;
     }
     return false;
   }
 
   /**
    * This verifies that the passed function type alias does not reference itself directly.
    *
    * @param node the function type alias to evaluate
@@ skipping 28 matching lines @@
    * This verifies that the type arguments in the passed type name are all within their bounds.
    *
    * @param node the [TypeName] to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#TYPE_ARGUMENT_NOT_MATCHING_BOUNDS
    */
   bool checkForTypeArgumentNotMatchingBounds(TypeName node) {
     if (node.typeArguments == null) {
       return false;
     }
+    // prepare Type
     Type2 type = node.type;
     if (type == null) {
       return false;
     }
+    // prepare ClassElement
     Element element = type.element;
     if (element is! ClassElement) {
       return false;
     }
     ClassElement classElement = element as ClassElement;
+    // prepare type parameters
     List<Type2> typeParameters = classElement.type.typeArguments;
     List<TypeParameterElement> boundingElts = classElement.typeParameters;
+    // iterate over each bounded type parameter and corresponding argument
     NodeList<TypeName> typeNameArgList = node.typeArguments.arguments;
     List<Type2> typeArguments = (type as InterfaceType).typeArguments;
     int loopThroughIndex = Math.min(typeNameArgList.length, boundingElts.length);
     bool foundError = false;
     for (int i = 0; i < loopThroughIndex; i++) {
       TypeName argTypeName = typeNameArgList[i];
       Type2 argType = argTypeName.type;
       Type2 boundType = boundingElts[i].bound;
       if (argType != null && boundType != null) {
         boundType = boundType.substitute2(typeArguments, typeParameters);
@@ skipping 33 matching lines @@
 
   /**
    * This checks that if the passed type parameter is a supertype of its bound.
    *
    * @param node the type parameter to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see StaticTypeWarningCode#TYPE_PARAMETER_SUPERTYPE_OF_ITS_BOUND
    */
   bool checkForTypeParameterSupertypeOfItsBound(TypeParameter node) {
     TypeParameterElement element = node.element;
+    // prepare bound
     Type2 bound = element.bound;
     if (bound == null) {
       return false;
     }
+    // OK, type parameter is not supertype of its bound
     if (!bound.isMoreSpecificThan(element.type)) {
       return false;
     }
+    // report problem
     _errorReporter.reportError3(StaticTypeWarningCode.TYPE_PARAMETER_SUPERTYPE_OF_ITS_BOUND, node, [element.displayName]);
     return true;
   }
 
   /**
    * This checks that if the passed generative constructor has neither an explicit super constructor
    * invocation nor a redirecting constructor invocation, that the superclass has a default
    * generative constructor.
    *
    * @param node the constructor declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#UNDEFINED_CONSTRUCTOR_IN_INITIALIZER_DEFAULT
    * @see CompileTimeErrorCode#NON_GENERATIVE_CONSTRUCTOR
    * @see StaticWarningCode#NO_DEFAULT_SUPER_CONSTRUCTOR_EXPLICIT
    */
   bool checkForUndefinedConstructorInInitializerImplicit(ConstructorDeclaration node) {
+    //
+    // Ignore if the constructor is not generative.
+    //
     if (node.factoryKeyword != null) {
       return false;
     }
+    //
+    // Ignore if the constructor has either an implicit super constructor invocation or a
+    // redirecting constructor invocation.
+    //
     for (ConstructorInitializer constructorInitializer in node.initializers) {
       if (constructorInitializer is SuperConstructorInvocation || constructorInitializer is RedirectingConstructorInvocation) {
         return false;
       }
     }
+    //
+    // Check to see whether the superclass has a non-factory unnamed constructor.
+    //
     if (_enclosingClass == null) {
       return false;
     }
     InterfaceType superType = _enclosingClass.supertype;
     if (superType == null) {
       return false;
     }
     ClassElement superElement = superType.element;
     ConstructorElement superUnnamedConstructor = superElement.unnamedConstructor;
     if (superUnnamedConstructor != null) {
@@ skipping 49 matching lines @@
    * This verifies the passed operator-method declaration, has correct number of parameters.
    *
    * This method assumes that the method declaration was tested to be an operator declaration before
    * being called.
    *
    * @param node the method declaration to evaluate
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#WRONG_NUMBER_OF_PARAMETERS_FOR_OPERATOR
    */
   bool checkForWrongNumberOfParametersForOperator(MethodDeclaration node) {
+    // prepare number of parameters
     FormalParameterList parameterList = node.parameters;
     if (parameterList == null) {
       return false;
     }
     int numParameters = parameterList.parameters.length;
+    // prepare operator name
     SimpleIdentifier nameNode = node.name;
     if (nameNode == null) {
       return false;
     }
     String name = nameNode.name;
+    // check for exact number of parameters
     int expected = -1;
     if ("[]=" == name) {
       expected = 2;
     } else if ("<" == name || ">" == name || "<=" == name || ">=" == name || "==" == name || "+" == name || "/" == name || "~/" == name || "*" == name || "%" == name || "|" == name || "^" == name || "&" == name || "<<" == name || ">>" == name || "[]" == name) {
       expected = 1;
     } else if ("~" == name) {
       expected = 0;
     }
     if (expected != -1 && numParameters != expected) {
       _errorReporter.reportError3(CompileTimeErrorCode.WRONG_NUMBER_OF_PARAMETERS_FOR_OPERATOR, nameNode, [name, expected, numParameters]);
       return true;
     }
+    // check for operator "-"
     if ("-" == name && numParameters > 1) {
       _errorReporter.reportError3(CompileTimeErrorCode.WRONG_NUMBER_OF_PARAMETERS_FOR_OPERATOR_MINUS, nameNode, [numParameters]);
       return true;
     }
+    // OK
     return false;
   }
 
   /**
    * This verifies if the passed setter parameter list have only one required parameter.
    *
    * This method assumes that the method declaration was tested to be a setter before being called.
    *
    * @param setterName the name of the setter to report problems on
    * @param parameterList the parameter list to evaluate
@@ skipping 42 matching lines @@
   }
 
   /**
    * This verifies that the given class declaration does not have the same class in the 'extends'
    * and 'implements' clauses.
    *
    * @return `true` if and only if an error code is generated on the passed node
    * @see CompileTimeErrorCode#IMPLEMENTS_SUPER_CLASS
    */
   bool checkImplementsSuperClass(ClassDeclaration node) {
+    // prepare super type
     InterfaceType superType = _enclosingClass.supertype;
     if (superType == null) {
       return false;
     }
+    // prepare interfaces
     ImplementsClause implementsClause = node.implementsClause;
     if (implementsClause == null) {
       return false;
     }
+    // check interfaces
     bool hasProblem = false;
     for (TypeName interfaceNode in implementsClause.interfaces) {
       if (interfaceNode.type == superType) {
         hasProblem = true;
         _errorReporter.reportError3(CompileTimeErrorCode.IMPLEMENTS_SUPER_CLASS, interfaceNode, [superType.displayName]);
       }
     }
+    // done
     return hasProblem;
   }
 
   /**
    * Returns the Type (return type) for a given getter.
    *
    * @param propertyAccessorElement
    * @return The type of the given getter.
    */
   Type2 getGetterType(PropertyAccessorElement propertyAccessorElement) {
     FunctionType functionType = propertyAccessorElement.type;
     if (functionType != null) {
       return functionType.returnType;
     } else {
       return null;
     }
   }
 
   /**
    * Returns the Type (first and only parameter) for a given setter.
    *
    * @param propertyAccessorElement
    * @return The type of the given setter.
    */
   Type2 getSetterType(PropertyAccessorElement propertyAccessorElement) {
+    // Get the parameters for MethodDeclaration or FunctionDeclaration
     List<ParameterElement> setterParameters = propertyAccessorElement.parameters;
+    // If there are no setter parameters, return no type.
     if (setterParameters.length == 0) {
       return null;
     }
     return setterParameters[0].type;
   }
 
   /**
    * Return the static type of the given expression that is to be used for type analysis.
    *
    * @param expression the expression whose type is to be returned
    * @return the static type of the given expression
    */
   Type2 getStaticType(Expression expression) {
     Type2 type = expression.staticType;
     if (type == null) {
+      // TODO(brianwilkerson) This should never happen.
       return _dynamicType;
     }
     return type;
   }
 
   /**
    * Return the variable element represented by the given expression, or `null` if there is no
    * such element.
    *
    * @param expression the expression whose element is to be returned
@@ skipping 32 matching lines @@
    * @return <code>true</code> if given [Element] has direct or indirect reference to itself
    *         from anywhere except [ClassElement] or type parameter bounds.
    */
   bool hasTypedefSelfReference(Element target) {
     Set<Element> checked = new Set<Element>();
     List<Element> toCheck = new List<Element>();
     toCheck.add(target);
     bool firstIteration = true;
     while (true) {
       Element current;
+      // get next element
       while (true) {
+        // may be no more elements to check
         if (toCheck.isEmpty) {
           return false;
         }
+        // try to get next element
         current = toCheck.removeAt(toCheck.length - 1);
         if (target == current) {
           if (firstIteration) {
             firstIteration = false;
             break;
           } else {
             return true;
           }
         }
         if (current != null && !checked.contains(current)) {
           break;
         }
       }
+      // check current element
       current.accept(new GeneralizingElementVisitor_ErrorVerifier_hasTypedefSelfReference(target, toCheck));
       checked.add(current);
     }
   }
 
   /**
    * @return `true` if given [Type] implements operator <i>==</i>, and it is not
    *         <i>int</i> or <i>String</i>.
    */
   bool implementsEqualsWhenNotAllowed(Type2 type) {
+    // ignore int or String
     if (type == null || type == _typeProvider.intType || type == _typeProvider.stringType) {
       return false;
     }
+    // prepare ClassElement
     Element element = type.element;
     if (element is! ClassElement) {
       return false;
     }
     ClassElement classElement = element as ClassElement;
+    // lookup for ==
     MethodElement method = classElement.lookUpMethod("==", _currentLibrary);
     if (method == null || method.enclosingElement.type.isObject) {
       return false;
     }
+    // there is == that we don't like
     return true;
   }
 
   bool isFunctionType(Type2 type) {
     if (type.isDynamic || type.isBottom) {
       return true;
     } else if (type is FunctionType || type.isDartCoreFunction) {
       return true;
     } else if (type is InterfaceType) {
       MethodElement callMethod = type.lookUpMethod(ElementResolver.CALL_METHOD_NAME, _currentLibrary);
@@ skipping 275 matching lines @@
   Object visitVariableElement(VariableElement element) {
     addTypeToCheck(element.type);
     return super.visitVariableElement(element);
   }
 
   void addTypeToCheck(Type2 type) {
     if (type == null) {
       return;
     }
     Element element = type.element;
+    // it is OK to reference target from class
     if (_inClass && target == element) {
       return;
     }
+    // schedule for checking
     toCheck.add(element);
+    // type arguments
     if (type is InterfaceType) {
       InterfaceType interfaceType = type;
       for (Type2 typeArgument in interfaceType.typeArguments) {
         addTypeToCheck(typeArgument);
       }
     }
   }
 }
 
 /**
@@ skipping 48 matching lines @@
    * @param correction the template used to create the correction to be displayed for the error
    */
   ResolverErrorCode.con2(String name, int ordinal, this.type, this.message, String correction) : super(name, ordinal) {
     this.correction10 = correction;
   }
 
   String get correction => correction10;
 
   ErrorSeverity get errorSeverity => type.severity;
 }