Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/lib/src/generated/element.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.element;
 
 import 'dart:collection';
@@ skipping 1971 matching lines @@
    * `=>!` - Treat the DOM attribute value as an expression. Set up a one time watch on expression.
    * Once the expression turns not null it will no longer update. (cost: 1 watches until not null,
    * then 0 watches)
    */
   static final AngularPropertyKind ONE_WAY_ONE_TIME = new AngularPropertyKind('ONE_WAY_ONE_TIME', 3);
 
   /**
    * `<=>` - Treat the DOM attribute value as an expression. Set up a watch on both outside as well
    * as component scope to keep the source and destination in sync. (cost: 2 watches)
    */
-  static final AngularPropertyKind TWO_WAY = new AngularPropertyKind('TWO_WAY', 4);
+  static final AngularPropertyKind TWO_WAY = new AngularPropertyKind_TWO_WAY('TWO_WAY', 4);
 
   static final List<AngularPropertyKind> values = [ATTR, CALLBACK, ONE_WAY, ONE_WAY_ONE_TIME, TWO_WAY];
 
+  /**
+   * Returns `true` if property of this kind calls field getter.
+   */
+  bool callsGetter() => false;
+
+  /**
+   * Returns `true` if property of this kind calls field setter.
+   */
+  bool callsSetter() => true;
+
   AngularPropertyKind(String name, int ordinal) : super(name, ordinal);
 }
 
+class AngularPropertyKind_TWO_WAY extends AngularPropertyKind {
+  AngularPropertyKind_TWO_WAY(String name, int ordinal) : super(name, ordinal);
+
+  bool callsGetter() => true;
+}
+
 /**
  * [AngularSelectorElement] is used to decide when Angular object should be applied.
  *
  * This class is an [Element] to support renaming component tag names, which are identifiers
  * in selectors.
  */
 abstract class AngularSelectorElement implements AngularElement {
   /**
    * Checks if the given [XmlTagNode] matches this selector.
    *
@@ skipping 479 matching lines @@
 
   List<PropertyAccessorElement> get accessors => _accessors;
 
   List<InterfaceType> get allSupertypes {
     List<InterfaceType> list = new List<InterfaceType>();
     collectAllSupertypes(list);
     return new List.from(list);
   }
 
   ElementImpl getChild(String identifier) {
+    //
+    // The casts in this method are safe because the set methods would have thrown a CCE if any of
+    // the elements in the arrays were not of the expected types.
+    //
     for (PropertyAccessorElement accessor in _accessors) {
       if ((accessor as PropertyAccessorElementImpl).identifier == identifier) {
         return accessor as PropertyAccessorElementImpl;
       }
     }
     for (ConstructorElement constructor in _constructors) {
       if ((constructor as ConstructorElementImpl).identifier == identifier) {
         return constructor as ConstructorElementImpl;
       }
     }
@@ skipping 56 matching lines @@
       if (elementName != null && elementName == name) {
         return element;
       }
     }
     return null;
   }
 
   ClassDeclaration get node => getNode2(ClassDeclaration);
 
   PropertyAccessorElement getSetter(String setterName) {
+    // TODO (jwren) revisit- should we append '=' here or require clients to include it?
+    // Do we need the check for isSetter below?
     if (!setterName.endsWith("=")) {
       setterName += '=';
     }
     for (PropertyAccessorElement accessor in _accessors) {
       if (accessor.isSetter && accessor.name == setterName) {
         return accessor;
       }
     }
     return null;
   }
@@ skipping 12 matching lines @@
     return null;
   }
 
   bool hasNonFinalField() {
     List<ClassElement> classesToVisit = new List<ClassElement>();
     Set<ClassElement> visitedClasses = new Set<ClassElement>();
     classesToVisit.add(this);
     while (!classesToVisit.isEmpty) {
       ClassElement currentElement = classesToVisit.removeAt(0);
       if (visitedClasses.add(currentElement)) {
+        // check fields
         for (FieldElement field in currentElement.fields) {
           if (!field.isFinal && !field.isConst && !field.isStatic && !field.isSynthetic) {
             return true;
           }
         }
+        // check mixins
         for (InterfaceType mixinType in currentElement.mixins) {
           ClassElement mixinElement = mixinType.element;
           classesToVisit.add(mixinElement);
         }
+        // check super
         InterfaceType supertype = currentElement.supertype;
         if (supertype != null) {
           ClassElement superElement = supertype.element;
           if (superElement != null) {
             classesToVisit.add(superElement);
           }
         }
       }
     }
+    // not found
     return false;
   }
 
   bool hasReferenceToSuper() => hasModifier(Modifier.REFERENCES_SUPER);
 
   bool get isAbstract => hasModifier(Modifier.ABSTRACT);
 
   bool get isProxy {
     for (ElementAnnotation annotation in metadata) {
       if (annotation.isProxy) {
@@ skipping 317 matching lines @@
    */
   CompilationUnitElementImpl(String name) : super.con2(name, -1);
 
   accept(ElementVisitor visitor) => visitor.visitCompilationUnitElement(this);
 
   bool operator ==(Object object) => object != null && runtimeType == object.runtimeType && source == (object as CompilationUnitElementImpl).source;
 
   List<PropertyAccessorElement> get accessors => _accessors;
 
   ElementImpl getChild(String identifier) {
+    //
+    // The casts in this method are safe because the set methods would have thrown a CCE if any of
+    // the elements in the arrays were not of the expected types.
+    //
     for (PropertyAccessorElement accessor in _accessors) {
       if ((accessor as PropertyAccessorElementImpl).identifier == identifier) {
         return accessor as PropertyAccessorElementImpl;
       }
     }
     for (VariableElement variable in _variables) {
       if ((variable as VariableElementImpl).identifier == identifier) {
         return variable as VariableElementImpl;
       }
     }
@@ skipping 249 matching lines @@
 
   ClassElement get enclosingElement => super.enclosingElement as ClassElement;
 
   ElementKind get kind => ElementKind.CONSTRUCTOR;
 
   ConstructorDeclaration get node => getNode2(ConstructorDeclaration);
 
   bool get isConst => hasModifier(Modifier.CONST);
 
   bool get isDefaultConstructor {
+    // unnamed
     String name = this.name;
     if (name != null && name.length != 0) {
       return false;
     }
+    // no required parameters
     for (ParameterElement parameter in parameters) {
       if (identical(parameter.parameterKind, ParameterKind.REQUIRED)) {
         return false;
       }
     }
+    // OK, can be used as default constructor
     return true;
   }
 
   bool get isFactory => hasModifier(Modifier.FACTORY);
 
   bool get isStatic => false;
 
   /**
    * Set whether this constructor represents a 'const' constructor to the given value.
    *
@@ skipping 311 matching lines @@
   Source get source {
     if (_enclosingElement == null) {
       return null;
     }
     return _enclosingElement.source;
   }
 
   CompilationUnit get unit => context.resolveCompilationUnit(source, library);
 
   int get hashCode {
+    // TODO: We might want to re-visit this optimization in the future.
+    // We cache the hash code value as this is a very frequently called method.
     if (_cachedHashCode == 0) {
       _cachedHashCode = location.hashCode;
     }
     return _cachedHashCode;
   }
 
   bool isAccessibleIn(LibraryElement library) {
     if (Identifier.isPrivateName(_name)) {
       return library == this.library;
     }
@@ skipping 297 matching lines @@
 
   /**
    * Return `true` if the given components, when interpreted to be encoded sources with a
    * leading source type indicator, are equal when the source type's are ignored.
    *
    * @param left the left component being compared
    * @param right the right component being compared
    * @return `true` if the given components are equal when the source type's are ignored
    */
   bool equalSourceComponents(String left, String right) {
+    // TODO(brianwilkerson) This method can go away when sources no longer have a URI kind.
     if (left == null) {
       return right == null;
     } else if (right == null) {
       return false;
     }
     int leftLength = left.length;
     int rightLength = right.length;
     if (leftLength != rightLength) {
       return false;
     } else if (leftLength <= 1 || rightLength <= 1) {
       return left == right;
     }
     return javaStringRegionMatches(left, 1, right, 1, leftLength - 1);
   }
 
   /**
    * Return the hash code of the given encoded source component, ignoring the source type indicator.
    *
    * @param sourceComponent the component to compute a hash code
    * @return the hash code of the given encoded source component
    */
   int hashSourceComponent(String sourceComponent) {
+    // TODO(brianwilkerson) This method can go away when sources no longer have a URI kind.
     if (sourceComponent.length <= 1) {
       return sourceComponent.hashCode;
     }
     return sourceComponent.substring(1).hashCode;
   }
 }
 
 /**
  * The class `ElementPair` is a pair of [Element]s. [Object#equals] and
  * [Object#hashCode] so this class can be used in hashed data structures.
@@ skipping 886 matching lines @@
   /**
    * Determine if the given library is up to date with respect to the given time stamp.
    *
    * @param library the library to process
    * @param timeStamp the time stamp to check against
    * @param visitedLibraries the set of visited libraries
    */
   static bool isUpToDate(LibraryElement library, int timeStamp, Set<LibraryElement> visitedLibraries) {
     if (!visitedLibraries.contains(library)) {
       visitedLibraries.add(library);
+      // Check the defining compilation unit.
       if (timeStamp < library.definingCompilationUnit.source.modificationStamp) {
         return false;
       }
+      // Check the parted compilation units.
       for (CompilationUnitElement element in library.parts) {
         if (timeStamp < element.source.modificationStamp) {
           return false;
         }
       }
+      // Check the imported libraries.
       for (LibraryElement importedLibrary in library.importedLibraries) {
         if (!isUpToDate(importedLibrary, timeStamp, visitedLibraries)) {
           return false;
         }
       }
+      // Check the exported libraries.
       for (LibraryElement exportedLibrary in library.exportedLibraries) {
         if (!isUpToDate(exportedLibrary, timeStamp, visitedLibraries)) {
           return false;
         }
       }
     }
     return true;
   }
 
   /**
@@ skipping 204 matching lines @@
     safelyVisitChildren(_imports, visitor);
     safelyVisitChildren(_parts, visitor);
   }
 
   String get identifier => _definingCompilationUnit.source.encoding;
 
   /**
    * Recursively fills set of visible libraries for [getVisibleElementsLibraries].
    */
   void addVisibleLibraries(Set<LibraryElement> visibleLibraries, bool includeExports) {
+    // maybe already processed
     if (!visibleLibraries.add(this)) {
       return;
     }
+    // add imported libraries
     for (ImportElement importElement in _imports) {
       LibraryElement importedLibrary = importElement.importedLibrary;
       if (importedLibrary != null) {
         (importedLibrary as LibraryElementImpl).addVisibleLibraries(visibleLibraries, true);
       }
     }
+    // add exported libraries
     if (includeExports) {
       for (ExportElement exportElement in _exports) {
         LibraryElement exportedLibrary = exportElement.exportedLibrary;
         if (exportedLibrary != null) {
           (exportedLibrary as LibraryElementImpl).addVisibleLibraries(visibleLibraries, true);
         }
       }
     }
   }
 
@@ skipping 1409 matching lines @@
    * @param definingType the type defining the parameters and arguments to be used in the
    *          substitution
    * @return the constructor element that will return the correctly substituted types
    */
   static ConstructorElement from(ConstructorElement baseConstructor, InterfaceType definingType) {
     if (baseConstructor == null || definingType.typeArguments.length == 0) {
       return baseConstructor;
     }
     FunctionType baseType = baseConstructor.type;
     if (baseType == null) {
+      // TODO(brianwilkerson) We need to understand when this can happen.
       return baseConstructor;
     }
     List<Type2> argumentTypes = definingType.typeArguments;
     List<Type2> parameterTypes = definingType.element.type.typeArguments;
     FunctionType substitutedType = baseType.substitute2(argumentTypes, parameterTypes);
     if (baseType == substitutedType) {
       return baseConstructor;
     }
+    // TODO(brianwilkerson) Consider caching the substituted type in the instance. It would use more
+    // memory but speed up some operations. We need to see how often the type is being re-computed.
     return new ConstructorMember(baseConstructor, definingType);
   }
 
   /**
    * Initialize a newly created element to represent a constructor of the given parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
   ConstructorMember(ConstructorElement baseElement, InterfaceType definingType) : super(baseElement, definingType);
@@ skipping 55 matching lines @@
    * parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
   ExecutableMember(ExecutableElement baseElement, InterfaceType definingType) : super(baseElement, definingType);
 
   ExecutableElement get baseElement => super.baseElement as ExecutableElement;
 
   List<FunctionElement> get functions {
+    //
+    // Elements within this element should have type parameters substituted, just like this element.
+    //
     throw new UnsupportedOperationException();
   }
 
   List<LabelElement> get labels => baseElement.labels;
 
   List<LocalVariableElement> get localVariables {
+    //
+    // Elements within this element should have type parameters substituted, just like this element.
+    //
     throw new UnsupportedOperationException();
   }
 
   List<ParameterElement> get parameters {
     List<ParameterElement> baseParameters = baseElement.parameters;
     int parameterCount = baseParameters.length;
     if (parameterCount == 0) {
       return baseParameters;
     }
     List<ParameterElement> parameterizedParameters = new List<ParameterElement>(parameterCount);
     for (int i = 0; i < parameterCount; i++) {
       parameterizedParameters[i] = ParameterMember.from(baseParameters[i], definingType);
     }
     return parameterizedParameters;
   }
 
   Type2 get returnType => substituteFor(baseElement.returnType);
 
   FunctionType get type => substituteFor(baseElement.type);
 
   bool get isOperator => baseElement.isOperator;
 
   bool get isStatic => baseElement.isStatic;
 
   void visitChildren(ElementVisitor visitor) {
+    // TODO(brianwilkerson) We need to finish implementing the accessors used below so that we can
+    // safely invoke them.
     super.visitChildren(visitor);
     safelyVisitChildren(baseElement.functions, visitor);
     safelyVisitChildren(labels, visitor);
     safelyVisitChildren(baseElement.localVariables, visitor);
     safelyVisitChildren(parameters, visitor);
   }
 }
 
 /**
  * Instances of the class `FieldFormalParameterMember` represent a parameter element defined
@@ skipping 36 matching lines @@
     Type2 baseType = baseField.type;
     if (baseType == null) {
       return baseField;
     }
     List<Type2> argumentTypes = definingType.typeArguments;
     List<Type2> parameterTypes = definingType.element.type.typeArguments;
     Type2 substitutedType = baseType.substitute2(argumentTypes, parameterTypes);
     if (baseType == substitutedType) {
       return baseField;
     }
+    // TODO(brianwilkerson) Consider caching the substituted type in the instance. It would use more
+    // memory but speed up some operations. We need to see how often the type is being re-computed.
     return new FieldMember(baseField, definingType);
   }
 
   /**
    * Initialize a newly created element to represent a field of the given parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
   FieldMember(FieldElement baseElement, InterfaceType definingType) : super(baseElement, definingType);
@@ skipping 168 matching lines @@
     if (baseMethod == null || definingType.typeArguments.length == 0) {
       return baseMethod;
     }
     FunctionType baseType = baseMethod.type;
     List<Type2> argumentTypes = definingType.typeArguments;
     List<Type2> parameterTypes = definingType.element.type.typeArguments;
     FunctionType substitutedType = baseType.substitute2(argumentTypes, parameterTypes);
     if (baseType == substitutedType) {
       return baseMethod;
     }
+    // TODO(brianwilkerson) Consider caching the substituted type in the instance. It would use more
+    // memory but speed up some operations. We need to see how often the type is being re-computed.
     return new MethodMember(baseMethod, definingType);
   }
 
   /**
    * Initialize a newly created element to represent a method of the given parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
   MethodMember(MethodElement baseElement, InterfaceType definingType) : super(baseElement, definingType);
@@ skipping 46 matching lines @@
    *
    * @param baseParameter the base parameter for which a member might be created
    * @param definingType the type defining the parameters and arguments to be used in the
    *          substitution
    * @return the parameter element that will return the correctly substituted types
    */
   static ParameterElement from(ParameterElement baseParameter, ParameterizedType definingType) {
     if (baseParameter == null || definingType.typeArguments.length == 0) {
       return baseParameter;
     }
+    // Check if parameter type depends on defining type type arguments.
+    // It is possible that we did not resolve field formal parameter yet, so skip this check for it.
     bool isFieldFormal = baseParameter is FieldFormalParameterElement;
     if (!isFieldFormal) {
       Type2 baseType = baseParameter.type;
       List<Type2> argumentTypes = definingType.typeArguments;
       List<Type2> parameterTypes = TypeParameterTypeImpl.getTypes(definingType.typeParameters);
       Type2 substitutedType = baseType.substitute2(argumentTypes, parameterTypes);
       if (baseType == substitutedType) {
         return baseParameter;
       }
     }
+    // TODO(brianwilkerson) Consider caching the substituted type in the instance. It would use more
+    // memory but speed up some operations. We need to see how often the type is being re-computed.
     if (isFieldFormal) {
       return new FieldFormalParameterMember(baseParameter as FieldFormalParameterElement, definingType);
     }
     return new ParameterMember(baseParameter, definingType);
   }
 
   /**
    * Initialize a newly created element to represent a parameter of the given parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
@@ skipping 93 matching lines @@
     if (baseAccessor == null || definingType.typeArguments.length == 0) {
       return baseAccessor;
     }
     FunctionType baseType = baseAccessor.type;
     List<Type2> argumentTypes = definingType.typeArguments;
     List<Type2> parameterTypes = definingType.element.type.typeArguments;
     FunctionType substitutedType = baseType.substitute2(argumentTypes, parameterTypes);
     if (baseType == substitutedType) {
       return baseAccessor;
     }
+    // TODO(brianwilkerson) Consider caching the substituted type in the instance. It would use more
+    // memory but speed up some operations. We need to see how often the type is being re-computed.
     return new PropertyAccessorMember(baseAccessor, definingType);
   }
 
   /**
    * Initialize a newly created element to represent a property accessor of the given parameterized
    * type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
@@ skipping 66 matching lines @@
    * parameterized type.
    *
    * @param baseElement the element on which the parameterized element was created
    * @param definingType the type in which the element is defined
    */
   VariableMember(VariableElement baseElement, ParameterizedType definingType) : super(baseElement, definingType);
 
   VariableElement get baseElement => super.baseElement as VariableElement;
 
   FunctionElement get initializer {
+    //
+    // Elements within this element should have type parameters substituted, just like this element.
+    //
     throw new UnsupportedOperationException();
   }
 
   VariableDeclaration get node => baseElement.node;
 
   Type2 get type => substituteFor(baseElement.type);
 
   bool get isConst => baseElement.isConst;
 
   bool get isFinal => baseElement.isFinal;
 
   void visitChildren(ElementVisitor visitor) {
+    // TODO(brianwilkerson) We need to finish implementing the accessors used below so that we can
+    // safely invoke them.
     super.visitChildren(visitor);
     safelyVisitChild(baseElement.initializer, visitor);
   }
 }
 
 /**
  * The unique instance of the class `BottomTypeImpl` implements the type `bottom`.
  *
  * @coverage dart.engine.type
  */
@@ skipping 71 matching lines @@
       if (parameterTypes[i] == this) {
         return argumentTypes[i];
       }
     }
     return this;
   }
 
   bool internalEquals(Object object, Set<ElementPair> visitedElementPairs) => identical(object, this);
 
   bool internalIsMoreSpecificThan(Type2 type, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // T is S
     if (identical(this, type)) {
       return true;
     }
+    // else
     return withDynamic;
   }
 
   bool internalIsSubtypeOf(Type2 type, Set<TypeImpl_TypePair> visitedTypePairs) => true;
 }
 
 /**
  * Instances of the class `FunctionTypeImpl` defines the behavior common to objects
  * representing the type of a function, method, constructor, getter, or setter.
  *
@@ skipping 46 matching lines @@
    *
    * @param element the element representing the declaration of the function type
    */
   FunctionTypeImpl.con2(FunctionTypeAliasElement element) : super(element, element == null ? null : element.name);
 
   bool operator ==(Object object) => internalEquals(object, new Set<ElementPair>());
 
   String get displayName {
     String name = this.name;
     if (name == null || name.length == 0) {
+      // TODO(brianwilkerson) Determine whether function types should ever have an empty name.
       List<Type2> normalParameterTypes = this.normalParameterTypes;
       List<Type2> optionalParameterTypes = this.optionalParameterTypes;
       Map<String, Type2> namedParameterTypes = this.namedParameterTypes;
       Type2 returnType = this.returnType;
       JavaStringBuilder builder = new JavaStringBuilder();
       builder.append("(");
       bool needsComma = false;
       if (normalParameterTypes.length > 0) {
         for (Type2 type in normalParameterTypes) {
           if (needsComma) {
@@ skipping 92 matching lines @@
     for (ParameterElement parameter in parameters) {
       if (identical(parameter.parameterKind, ParameterKind.POSITIONAL)) {
         types.add(parameter.type.substitute2(typeArguments, typeParameters));
       }
     }
     return new List.from(types);
   }
 
   List<ParameterElement> get parameters {
     List<ParameterElement> baseParameters = this.baseParameters;
+    // no parameters, quick return
     int parameterCount = baseParameters.length;
     if (parameterCount == 0) {
       return baseParameters;
     }
+    // create specialized parameters
     List<ParameterElement> specializedParameters = new List<ParameterElement>(parameterCount);
     for (int i = 0; i < parameterCount; i++) {
       specializedParameters[i] = ParameterMember.from(baseParameters[i], this);
     }
     return specializedParameters;
   }
 
   Type2 get returnType {
     Type2 baseReturnType = this.baseReturnType;
     if (baseReturnType == null) {
+      // TODO(brianwilkerson) This is a patch. The return type should never be null and we need to
+      // understand why it is and fix it.
       return DynamicTypeImpl.instance;
     }
     return baseReturnType.substitute2(typeArguments, TypeParameterTypeImpl.getTypes(typeParameters));
   }
 
   List<TypeParameterElement> get typeParameters {
     Element element = this.element;
     if (element is FunctionTypeAliasElement) {
       return element.typeParameters;
     }
     ClassElement definingClass = element.getAncestor(ClassElement);
     if (definingClass != null) {
       return definingClass.typeParameters;
     }
     return TypeParameterElementImpl.EMPTY_ARRAY;
   }
 
   int get hashCode {
     if (element == null) {
       return 0;
     }
+    // Reference the arrays of parameters
     List<Type2> normalParameterTypes = this.normalParameterTypes;
     List<Type2> optionalParameterTypes = this.optionalParameterTypes;
     Iterable<Type2> namedParameterTypes = this.namedParameterTypes.values;
+    // Generate the hashCode
     int hashCode = returnType.hashCode;
     for (int i = 0; i < normalParameterTypes.length; i++) {
       hashCode = (hashCode << 1) + normalParameterTypes[i].hashCode;
     }
     for (int i = 0; i < optionalParameterTypes.length; i++) {
       hashCode = (hashCode << 1) + optionalParameterTypes[i].hashCode;
     }
     for (Type2 type in namedParameterTypes) {
       hashCode = (hashCode << 1) + type.hashCode;
     }
     return hashCode;
   }
 
   bool internalIsMoreSpecificThan(Type2 type, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // trivial base cases
     if (type == null) {
       return false;
     } else if (identical(this, type) || type.isDynamic || type.isDartCoreFunction || type.isObject) {
       return true;
     } else if (type is! FunctionType) {
       return false;
     } else if (this == type) {
       return true;
     }
     FunctionType t = this;
     FunctionType s = type as FunctionType;
     List<Type2> tTypes = t.normalParameterTypes;
     List<Type2> tOpTypes = t.optionalParameterTypes;
     List<Type2> sTypes = s.normalParameterTypes;
     List<Type2> sOpTypes = s.optionalParameterTypes;
+    // If one function has positional and the other has named parameters, return false.
     if ((sOpTypes.length > 0 && t.namedParameterTypes.length > 0) || (tOpTypes.length > 0 && s.namedParameterTypes.length > 0)) {
       return false;
     }
+    // named parameters case
     if (t.namedParameterTypes.length > 0) {
+      // check that the number of required parameters are equal, and check that every t_i is
+      // more specific than every s_i
       if (t.normalParameterTypes.length != s.normalParameterTypes.length) {
         return false;
       } else if (t.normalParameterTypes.length > 0) {
         for (int i = 0; i < tTypes.length; i++) {
           if (!(tTypes[i] as TypeImpl).isMoreSpecificThan3(sTypes[i], withDynamic, visitedTypePairs)) {
             return false;
           }
         }
       }
       Map<String, Type2> namedTypesT = t.namedParameterTypes;
       Map<String, Type2> namedTypesS = s.namedParameterTypes;
+      // if k >= m is false, return false: the passed function type has more named parameter types than this
       if (namedTypesT.length < namedTypesS.length) {
         return false;
       }
+      // Loop through each element in S verifying that T has a matching parameter name and that the
+      // corresponding type is more specific then the type in S.
       JavaIterator<MapEntry<String, Type2>> iteratorS = new JavaIterator(getMapEntrySet(namedTypesS));
       while (iteratorS.hasNext) {
         MapEntry<String, Type2> entryS = iteratorS.next();
         Type2 typeT = namedTypesT[entryS.getKey()];
         if (typeT == null) {
           return false;
         }
         if (!(typeT as TypeImpl).isMoreSpecificThan3(entryS.getValue(), withDynamic, visitedTypePairs)) {
           return false;
         }
       }
     } else if (s.namedParameterTypes.length > 0) {
       return false;
     } else {
+      // positional parameter case
       int tArgLength = tTypes.length + tOpTypes.length;
       int sArgLength = sTypes.length + sOpTypes.length;
+      // Check that the total number of parameters in t is greater than or equal to the number of
+      // parameters in s and that the number of required parameters in s is greater than or equal to
+      // the number of required parameters in t.
       if (tArgLength < sArgLength || sTypes.length < tTypes.length) {
         return false;
       }
       if (tOpTypes.length == 0 && sOpTypes.length == 0) {
+        // No positional arguments, don't copy contents to new array
         for (int i = 0; i < sTypes.length; i++) {
           if (!(tTypes[i] as TypeImpl).isMoreSpecificThan3(sTypes[i], withDynamic, visitedTypePairs)) {
             return false;
           }
         }
       } else {
+        // Else, we do have positional parameters, copy required and positional parameter types into
+        // arrays to do the compare (for loop below).
         List<Type2> tAllTypes = new List<Type2>(sArgLength);
         for (int i = 0; i < tTypes.length; i++) {
           tAllTypes[i] = tTypes[i];
         }
         for (int i = tTypes.length, j = 0; i < sArgLength; i++, j++) {
           tAllTypes[i] = tOpTypes[j];
         }
         List<Type2> sAllTypes = new List<Type2>(sArgLength);
         for (int i = 0; i < sTypes.length; i++) {
           sAllTypes[i] = sTypes[i];
@@ skipping 102 matching lines @@
     } else {
       return (element as FunctionTypeAliasElement).parameters;
     }
   }
 
   bool internalEquals(Object object, Set<ElementPair> visitedElementPairs) {
     if (object is! FunctionTypeImpl) {
       return false;
     }
     FunctionTypeImpl otherType = object as FunctionTypeImpl;
+    // If the visitedTypePairs already has the pair (this, type), use the elements to determine equality
     ElementPair elementPair = new ElementPair(element, otherType.element);
     if (!visitedElementPairs.add(elementPair)) {
       return elementPair.firstElt == elementPair.secondElt;
     }
+    // Compute the result
     bool result = TypeImpl.equalArrays(normalParameterTypes, otherType.normalParameterTypes, visitedElementPairs) && TypeImpl.equalArrays(optionalParameterTypes, otherType.optionalParameterTypes, visitedElementPairs) && equals2(namedParameterTypes, otherType.namedParameterTypes, visitedElementPairs) && (returnType as TypeImpl).internalEquals(otherType.returnType, visitedElementPairs);
+    // Remove the pair from our visited pairs list
     visitedElementPairs.remove(elementPair);
+    // Return the result
     return result;
   }
 
   bool internalIsSubtypeOf(Type2 type, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // trivial base cases
     if (type == null) {
       return false;
     } else if (identical(this, type) || type.isDynamic || type.isDartCoreFunction || type.isObject) {
       return true;
     } else if (type is! FunctionType) {
       return false;
     } else if (this == type) {
       return true;
     }
     FunctionType t = this;
     FunctionType s = type as FunctionType;
     List<Type2> tTypes = t.normalParameterTypes;
     List<Type2> tOpTypes = t.optionalParameterTypes;
     List<Type2> sTypes = s.normalParameterTypes;
     List<Type2> sOpTypes = s.optionalParameterTypes;
+    // If one function has positional and the other has named parameters, return false.
     if ((sOpTypes.length > 0 && t.namedParameterTypes.length > 0) || (tOpTypes.length > 0 && s.namedParameterTypes.length > 0)) {
       return false;
     }
+    // named parameters case
     if (t.namedParameterTypes.length > 0) {
+      // check that the number of required parameters are equal, and check that every t_i is
+      // assignable to every s_i
       if (t.normalParameterTypes.length != s.normalParameterTypes.length) {
         return false;
       } else if (t.normalParameterTypes.length > 0) {
         for (int i = 0; i < tTypes.length; i++) {
           if (!(tTypes[i] as TypeImpl).isAssignableTo2(sTypes[i], visitedTypePairs)) {
             return false;
           }
         }
       }
       Map<String, Type2> namedTypesT = t.namedParameterTypes;
       Map<String, Type2> namedTypesS = s.namedParameterTypes;
+      // if k >= m is false, return false: the passed function type has more named parameter types than this
       if (namedTypesT.length < namedTypesS.length) {
         return false;
       }
+      // Loop through each element in S verifying that T has a matching parameter name and that the
+      // corresponding type is assignable to the type in S.
       JavaIterator<MapEntry<String, Type2>> iteratorS = new JavaIterator(getMapEntrySet(namedTypesS));
       while (iteratorS.hasNext) {
         MapEntry<String, Type2> entryS = iteratorS.next();
         Type2 typeT = namedTypesT[entryS.getKey()];
         if (typeT == null) {
           return false;
         }
         if (!(typeT as TypeImpl).isAssignableTo2(entryS.getValue(), visitedTypePairs)) {
           return false;
         }
       }
     } else if (s.namedParameterTypes.length > 0) {
       return false;
     } else {
+      // positional parameter case
       int tArgLength = tTypes.length + tOpTypes.length;
       int sArgLength = sTypes.length + sOpTypes.length;
+      // Check that the total number of parameters in t is greater than or equal to the number of
+      // parameters in s and that the number of required parameters in s is greater than or equal to
+      // the number of required parameters in t.
       if (tArgLength < sArgLength || sTypes.length < tTypes.length) {
         return false;
       }
       if (tOpTypes.length == 0 && sOpTypes.length == 0) {
+        // No positional arguments, don't copy contents to new array
         for (int i = 0; i < sTypes.length; i++) {
           if (!(tTypes[i] as TypeImpl).isAssignableTo2(sTypes[i], visitedTypePairs)) {
             return false;
           }
         }
       } else {
+        // Else, we do have positional parameters, copy required and positional parameter types into
+        // arrays to do the compare (for loop below).
         List<Type2> tAllTypes = new List<Type2>(sArgLength);
         for (int i = 0; i < tTypes.length; i++) {
           tAllTypes[i] = tTypes[i];
         }
         for (int i = tTypes.length, j = 0; i < sArgLength; i++, j++) {
           tAllTypes[i] = tOpTypes[j];
         }
         List<Type2> sAllTypes = new List<Type2>(sArgLength);
         for (int i = 0; i < sTypes.length; i++) {
           sAllTypes[i] = sTypes[i];
@@ skipping 68 matching lines @@
    * @param type the [Type] to compute the longest inheritance path of from the passed
    *          [Type] to Object
    * @param depth a field used recursively
    * @param visitedClasses the classes that have already been visited
    * @return the computed longest inheritance path to Object
    * @see #computeLongestInheritancePathToObject(Type)
    * @see #getLeastUpperBound(Type)
    */
   static int computeLongestInheritancePathToObject2(InterfaceType type, int depth, Set<ClassElement> visitedClasses) {
     ClassElement classElement = type.element;
+    // Object case
     if (classElement.supertype == null || visitedClasses.contains(classElement)) {
       return depth;
     }
     int longestPath = 1;
     try {
       visitedClasses.add(classElement);
       List<InterfaceType> superinterfaces = classElement.interfaces;
       int pathLength;
       if (superinterfaces.length > 0) {
+        // loop through each of the superinterfaces recursively calling this method and keeping track
+        // of the longest path to return
         for (InterfaceType superinterface in superinterfaces) {
           pathLength = computeLongestInheritancePathToObject2(superinterface, depth + 1, visitedClasses);
           if (pathLength > longestPath) {
             longestPath = pathLength;
           }
         }
       }
+      // finally, perform this same check on the super type
+      // TODO(brianwilkerson) Does this also need to add in the number of mixin classes?
       InterfaceType supertype = classElement.supertype;
       pathLength = computeLongestInheritancePathToObject2(supertype, depth + 1, visitedClasses);
       if (pathLength > longestPath) {
         longestPath = pathLength;
       }
     } finally {
       visitedClasses.remove(classElement);
     }
     return longestPath;
   }
@@ skipping 69 matching lines @@
       return firstType;
     }
     List<Type2> firstArguments = firstType.typeArguments;
     List<Type2> secondArguments = secondType.typeArguments;
     int argumentCount = firstArguments.length;
     if (argumentCount == 0) {
       return firstType;
     }
     List<Type2> lubArguments = new List<Type2>(argumentCount);
     for (int i = 0; i < argumentCount; i++) {
+      //
+      // Ideally we would take the least upper bound of the two argument types, but this can cause
+      // an infinite recursion (such as when finding the least upper bound of String and num).
+      //
       if (firstArguments[i] == secondArguments[i]) {
         lubArguments[i] = firstArguments[i];
       }
       if (lubArguments[i] == null) {
         lubArguments[i] = DynamicTypeImpl.instance;
       }
     }
     InterfaceTypeImpl lub = new InterfaceTypeImpl.con1(firstType.element);
     lub.typeArguments = lubArguments;
     return lub;
@@ skipping 33 matching lines @@
   String get displayName {
     String name = this.name;
     List<Type2> typeArguments = this.typeArguments;
     bool allDynamic = true;
     for (Type2 type in typeArguments) {
       if (type != null && !type.isDynamic) {
         allDynamic = false;
         break;
       }
     }
+    // If there is at least one non-dynamic type, then list them out
     if (!allDynamic) {
       JavaStringBuilder builder = new JavaStringBuilder();
       builder.append(name);
       builder.append("<");
       for (int i = 0; i < typeArguments.length; i++) {
         if (i != 0) {
           builder.append(", ");
         }
         Type2 typeArg = typeArguments[i];
         builder.append(typeArg.displayName);
@@ skipping 18 matching lines @@
     }
     int count = interfaces.length;
     List<InterfaceType> typedInterfaces = new List<InterfaceType>(count);
     for (int i = 0; i < count; i++) {
       typedInterfaces[i] = interfaces[i].substitute2(typeArguments, parameterTypes);
     }
     return typedInterfaces;
   }
 
   Type2 getLeastUpperBound(Type2 type) {
+    // quick check for self
     if (identical(type, this)) {
       return this;
     }
+    // dynamic
     Type2 dynamicType = DynamicTypeImpl.instance;
     if (identical(this, dynamicType) || identical(type, dynamicType)) {
       return dynamicType;
     }
+    // TODO (jwren) opportunity here for a better, faster algorithm if this turns out to be a bottle-neck
     if (type is! InterfaceType) {
       return null;
     }
+    // new names to match up with the spec
     InterfaceType i = this;
     InterfaceType j = type as InterfaceType;
+    // compute set of supertypes
     Set<InterfaceType> si = computeSuperinterfaceSet(i);
     Set<InterfaceType> sj = computeSuperinterfaceSet(j);
+    // union si with i and sj with j
     si.add(i);
     sj.add(j);
+    // compute intersection, reference as set 's'
     List<InterfaceType> s = intersection(si, sj);
+    // for each element in Set s, compute the largest inheritance path to Object
     List<int> depths = new List<int>.filled(s.length, 0);
     int maxDepth = 0;
     for (int n = 0; n < s.length; n++) {
       depths[n] = computeLongestInheritancePathToObject(s[n]);
       if (depths[n] > maxDepth) {
         maxDepth = depths[n];
       }
     }
+    // ensure that the currently computed maxDepth is unique,
+    // otherwise, decrement and test for uniqueness again
     for (; maxDepth >= 0; maxDepth--) {
       int indexOfLeastUpperBound = -1;
       int numberOfTypesAtMaxDepth = 0;
       for (int m = 0; m < depths.length; m++) {
         if (depths[m] == maxDepth) {
           numberOfTypesAtMaxDepth++;
           indexOfLeastUpperBound = m;
         }
       }
       if (numberOfTypesAtMaxDepth == 1) {
         return s[indexOfLeastUpperBound];
       }
     }
+    // illegal state, log and return null- Object at maxDepth == 0 should always return itself as
+    // the least upper bound.
+    // TODO (jwren) log the error state
     return null;
   }
 
   MethodElement getMethod(String methodName) => MethodMember.from((element as ClassElementImpl).getMethod(methodName), this);
 
   List<MethodElement> get methods {
     List<MethodElement> methods = element.methods;
     List<MethodElement> members = new List<MethodElement>(methods.length);
     for (int i = 0; i < methods.length; i++) {
       members[i] = MethodMember.from(methods[i], this);
@@ skipping 44 matching lines @@
       return false;
     }
     return element.name == "Function" && element.library.isDartCore;
   }
 
   bool isDirectSupertypeOf(InterfaceType type) {
     InterfaceType i = this;
     InterfaceType j = type;
     ClassElement jElement = j.element;
     InterfaceType supertype = jElement.supertype;
+    //
+    // If J has no direct supertype then it is Object, and Object has no direct supertypes.
+    //
     if (supertype == null) {
       return false;
     }
+    //
+    // I is listed in the extends clause of J.
+    //
     List<Type2> jArgs = j.typeArguments;
     List<Type2> jVars = jElement.type.typeArguments;
     supertype = supertype.substitute2(jArgs, jVars);
     if (supertype == i) {
       return true;
     }
+    //
+    // I is listed in the implements clause of J.
+    //
     for (InterfaceType interfaceType in jElement.interfaces) {
       interfaceType = interfaceType.substitute2(jArgs, jVars);
       if (interfaceType == i) {
         return true;
       }
     }
+    //
+    // I is listed in the with clause of J.
+    //
     for (InterfaceType mixinType in jElement.mixins) {
       mixinType = mixinType.substitute2(jArgs, jVars);
       if (mixinType == i) {
         return true;
       }
     }
+    //
+    // J is a mixin application of the mixin of I.
+    //
+    // TODO(brianwilkerson) Determine whether this needs to be implemented or whether it is covered
+    // by the case above.
     return false;
   }
 
   bool get isObject => element.supertype == null;
 
   ConstructorElement lookUpConstructor(String constructorName, LibraryElement library) {
+    // prepare base ConstructorElement
     ConstructorElement constructorElement;
     if (constructorName == null) {
       constructorElement = element.unnamedConstructor;
     } else {
       constructorElement = element.getNamedConstructor(constructorName);
     }
+    // not found or not accessible
     if (constructorElement == null || !constructorElement.isAccessibleIn(library)) {
       return null;
     }
+    // return member
     return ConstructorMember.from(constructorElement, this);
   }
 
   PropertyAccessorElement lookUpGetter(String getterName, LibraryElement library) {
     PropertyAccessorElement element = getGetter(getterName);
     if (element != null && element.isAccessibleIn(library)) {
       return element;
     }
     return lookUpGetterInSuperclass(getterName, library);
   }
@@ skipping 133 matching lines @@
 
   bool internalEquals(Object object, Set<ElementPair> visitedElementPairs) {
     if (object is! InterfaceTypeImpl) {
       return false;
     }
     InterfaceTypeImpl otherType = object as InterfaceTypeImpl;
     return (element == otherType.element) && TypeImpl.equalArrays(typeArguments, otherType.typeArguments, visitedElementPairs);
   }
 
   bool internalIsMoreSpecificThan(Type2 type, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    //
+    // S is dynamic.
+    // The test to determine whether S is dynamic is done here because dynamic is not an instance of
+    // InterfaceType.
+    //
     if (identical(type, DynamicTypeImpl.instance)) {
       return true;
     } else if (type is! InterfaceType) {
       return false;
     }
     return isMoreSpecificThan2(type as InterfaceType, new Set<ClassElement>(), withDynamic, visitedTypePairs);
   }
 
   bool internalIsSubtypeOf(Type2 type, Set<TypeImpl_TypePair> visitedTypePairs) {
+    //
+    // T is a subtype of S, written T <: S, iff [bottom/dynamic]T << S
+    //
     if (identical(type, DynamicTypeImpl.instance)) {
       return true;
     } else if (type is TypeParameterType) {
       return true;
     } else if (type is FunctionType) {
       ClassElement element = this.element;
       MethodElement callMethod = element.lookUpMethod("call", element.library);
       if (callMethod != null) {
         return callMethod.type.isSubtypeOf(type);
       }
       return false;
     } else if (type is! InterfaceType) {
       return false;
     } else if (this == type) {
       return true;
     }
     return isSubtypeOf2(type as InterfaceType, new Set<ClassElement>(), visitedTypePairs);
   }
 
   bool isMoreSpecificThan2(InterfaceType s, Set<ClassElement> visitedClasses, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    //
+    // A type T is more specific than a type S, written T << S,  if one of the following conditions
+    // is met:
+    //
+    // Reflexivity: T is S.
+    //
     if (this == s) {
       return true;
     }
+    //
+    // T is bottom. (This case is handled by the class BottomTypeImpl.)
+    //
+    // Direct supertype: S is a direct supertype of T.
+    //
     if (s.isDirectSupertypeOf(this)) {
       return true;
     }
+    //
+    // Covariance: T is of the form I<T1, ..., Tn> and S is of the form I<S1, ..., Sn> and Ti << Si, 1 <= i <= n.
+    //
     ClassElement tElement = this.element;
     ClassElement sElement = s.element;
     if (tElement == sElement) {
       List<Type2> tArguments = typeArguments;
       List<Type2> sArguments = s.typeArguments;
       if (tArguments.length != sArguments.length) {
         return false;
       }
       for (int i = 0; i < tArguments.length; i++) {
         if (!(tArguments[i] as TypeImpl).isMoreSpecificThan3(sArguments[i], withDynamic, visitedTypePairs)) {
           return false;
         }
       }
       return true;
     }
+    //
+    // Transitivity: T << U and U << S.
+    //
+    // First check for infinite loops
     ClassElement element = this.element;
     if (element == null || visitedClasses.contains(element)) {
       return false;
     }
     visitedClasses.add(element);
+    // Iterate over all of the types U that are more specific than T because they are direct
+    // supertypes of T and return true if any of them are more specific than S.
     InterfaceType supertype = superclass;
     if (supertype != null && (supertype as InterfaceTypeImpl).isMoreSpecificThan2(s, visitedClasses, withDynamic, visitedTypePairs)) {
       return true;
     }
     for (InterfaceType interfaceType in interfaces) {
       if ((interfaceType as InterfaceTypeImpl).isMoreSpecificThan2(s, visitedClasses, withDynamic, visitedTypePairs)) {
         return true;
       }
     }
     for (InterfaceType mixinType in mixins) {
       if ((mixinType as InterfaceTypeImpl).isMoreSpecificThan2(s, visitedClasses, withDynamic, visitedTypePairs)) {
         return true;
       }
     }
     return false;
   }
 
   bool isSubtypeOf2(InterfaceType type, Set<ClassElement> visitedClasses, Set<TypeImpl_TypePair> visitedTypePairs) {
     InterfaceType typeT = this;
     InterfaceType typeS = type;
     ClassElement elementT = element;
     if (elementT == null || visitedClasses.contains(elementT)) {
       return false;
     }
     visitedClasses.add(elementT);
     if (typeT == typeS) {
       return true;
     } else if (elementT == typeS.element) {
+      // For each of the type arguments return true if all type args from T is a subtype of all
+      // types from S.
       List<Type2> typeTArgs = typeT.typeArguments;
       List<Type2> typeSArgs = typeS.typeArguments;
       if (typeTArgs.length != typeSArgs.length) {
+        // This case covers the case where two objects are being compared that have a different
+        // number of parameterized types.
         return false;
       }
       for (int i = 0; i < typeTArgs.length; i++) {
+        // Recursively call isSubtypeOf the type arguments and return false if the T argument is not
+        // a subtype of the S argument.
         if (!(typeTArgs[i] as TypeImpl).isSubtypeOf3(typeSArgs[i], visitedTypePairs)) {
           return false;
         }
       }
       return true;
     } else if (typeS.isDartCoreFunction && elementT.getMethod("call") != null) {
       return true;
     }
     InterfaceType supertype = superclass;
+    // The type is Object, return false.
     if (supertype != null && (supertype as InterfaceTypeImpl).isSubtypeOf2(typeS, visitedClasses, visitedTypePairs)) {
       return true;
     }
     List<InterfaceType> interfaceTypes = interfaces;
     for (InterfaceType interfaceType in interfaceTypes) {
       if ((interfaceType as InterfaceTypeImpl).isSubtypeOf2(typeS, visitedClasses, visitedTypePairs)) {
         return true;
       }
     }
     List<InterfaceType> mixinTypes = mixins;
@@ skipping 109 matching lines @@
    * The given set of pairs of types (T1, T2), where each pair indicates that we invoked this method
    * because we are in the process of answering the question of whether T1 is a subtype of T2, is
    * used to prevent infinite loops.
    *
    * @param type the type being compared with this type
    * @param withDynamic `true` if "dynamic" should be considered as a subtype of any type
    * @param visitedPairs the set of pairs of types used to prevent infinite loops
    * @return `true` if this type is more specific than the given type
    */
   bool isMoreSpecificThan3(Type2 type, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // If the visitedTypePairs already has the pair (this, type), return false
     TypeImpl_TypePair typePair = new TypeImpl_TypePair(this, type);
     if (!visitedTypePairs.add(typePair)) {
       return false;
     }
     bool result = internalIsMoreSpecificThan(type, withDynamic, visitedTypePairs);
     visitedTypePairs.remove(typePair);
     return result;
   }
 
   bool get isObject => false;
 
   bool isSubtypeOf(Type2 type) => isSubtypeOf3(type, new Set<TypeImpl_TypePair>());
 
   /**
    * Return `true` if this type is a subtype of the given type.
    *
    * The given set of pairs of types (T1, T2), where each pair indicates that we invoked this method
    * because we are in the process of answering the question of whether T1 is a subtype of T2, is
    * used to prevent infinite loops.
    *
    * @param type the type being compared with this type
    * @param visitedPairs the set of pairs of types used to prevent infinite loops
    * @return `true` if this type is a subtype of the given type
    */
   bool isSubtypeOf3(Type2 type, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // If the visitedTypePairs already has the pair (this, type), return false
     TypeImpl_TypePair typePair = new TypeImpl_TypePair(this, type);
     if (!visitedTypePairs.add(typePair)) {
       return false;
     }
     bool result = internalIsSubtypeOf(type, visitedTypePairs);
     visitedTypePairs.remove(typePair);
     return result;
   }
 
   bool isSupertypeOf(Type2 type) => type.isSubtypeOf(this);
@@ skipping 112 matching lines @@
       if (parameterTypes[i] == this) {
         return argumentTypes[i];
       }
     }
     return this;
   }
 
   bool internalEquals(Object object, Set<ElementPair> visitedElementPairs) => this == object;
 
   bool internalIsMoreSpecificThan(Type2 s, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    //
+    // A type T is more specific than a type S, written T << S,  if one of the following conditions
+    // is met:
+    //
+    // Reflexivity: T is S.
+    //
     if (this == s) {
       return true;
     }
+    // S is bottom.
+    //
     if (s.isBottom) {
       return true;
     }
+    // S is dynamic.
+    //
     if (s.isDynamic) {
       return true;
     }
     return isMoreSpecificThan4(s, new Set<Type2>(), withDynamic, visitedTypePairs);
   }
 
   bool internalIsSubtypeOf(Type2 type, Set<TypeImpl_TypePair> visitedTypePairs) => isMoreSpecificThan3(type, true, new Set<TypeImpl_TypePair>());
 
   bool isMoreSpecificThan4(Type2 s, Set<Type2> visitedTypes, bool withDynamic, Set<TypeImpl_TypePair> visitedTypePairs) {
+    // T is a type parameter and S is the upper bound of T.
+    //
     Type2 bound = element.bound;
     if (s == bound) {
       return true;
     }
+    // T is a type parameter and S is Object.
+    //
     if (s.isObject) {
       return true;
     }
+    // We need upper bound to continue.
     if (bound == null) {
       return false;
     }
+    //
+    // Transitivity: T << U and U << S.
+    //
     if (bound is TypeParameterTypeImpl) {
       TypeParameterTypeImpl boundTypeParameter = bound;
+      // First check for infinite loops
       if (visitedTypes.contains(bound)) {
         return false;
       }
       visitedTypes.add(bound);
+      // Then check upper bound.
       return boundTypeParameter.isMoreSpecificThan4(s, visitedTypes, withDynamic, visitedTypePairs);
     }
+    // Check interface type.
     return (bound as TypeImpl).isMoreSpecificThan3(s, withDynamic, visitedTypePairs);
   }
 }
 
 /**
  * The unique instance of the class `VoidTypeImpl` implements the type `void`.
  *
  * @coverage dart.engine.type
  */
 class VoidTypeImpl extends TypeImpl implements VoidType {
@@ skipping 638 matching lines @@
 
 /**
  * The interface `VoidType` defines the behavior of the unique object representing the type
  * `void`.
  *
  * @coverage dart.engine.type
  */
 abstract class VoidType implements Type2 {
   VoidType substitute2(List<Type2> argumentTypes, List<Type2> parameterTypes);
 }