Clean up comments in element_resolver

pkg/analyzer/lib/src/generated/element_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.
 
 library engine.resolver.element_resolver;
 
 import 'dart:collection';
 
 import 'ast.dart';
 import 'element.dart';
 import 'engine.dart';
 import 'error.dart';
 import 'resolver.dart';
 import 'scanner.dart' as sc;
 import 'utilities_dart.dart';
 
 /**
- * Instances of the class `ElementResolver` are used by instances of [ResolverVisitor]
- * to resolve references within the AST structure to the elements being referenced. The requirements
- * for the element resolver are:
- * <ol>
- * * Every [SimpleIdentifier] should be resolved to the element to which it refers.
- * Specifically:
- * * An identifier within the declaration of that name should resolve to the element being
- * declared.
- * * An identifier denoting a prefix should resolve to the element representing the import that
- * defines the prefix (an [ImportElement]).
- * * An identifier denoting a variable should resolve to the element representing the variable (a
- * [VariableElement]).
- * * An identifier denoting a parameter should resolve to the element representing the parameter
- * (a [ParameterElement]).
- * * An identifier denoting a field should resolve to the element representing the getter or
- * setter being invoked (a [PropertyAccessorElement]).
- * * An identifier denoting the name of a method or function being invoked should resolve to the
- * element representing the method or function (a [ExecutableElement]).
- * * An identifier denoting a label should resolve to the element representing the label (a
- * [LabelElement]).
- * The identifiers within directives are exceptions to this rule and are covered below.
- * * Every node containing a token representing an operator that can be overridden (
- * [BinaryExpression], [PrefixExpression], [PostfixExpression]) should resolve to
- * the element representing the method invoked by that operator (a [MethodElement]).
- * * Every [FunctionExpressionInvocation] should resolve to the element representing the
- * function being invoked (a [FunctionElement]). This will be the same element as that to
- * which the name is resolved if the function has a name, but is provided for those cases where an
- * unnamed function is being invoked.
- * * Every [LibraryDirective] and [PartOfDirective] should resolve to the element
- * representing the library being specified by the directive (a [LibraryElement]) unless, in
- * the case of a part-of directive, the specified library does not exist.
- * * Every [ImportDirective] and [ExportDirective] should resolve to the element
- * representing the library being specified by the directive unless the specified library does not
- * exist (an [ImportElement] or [ExportElement]).
- * * The identifier representing the prefix in an [ImportDirective] should resolve to the
- * element representing the prefix (a [PrefixElement]).
- * * The identifiers in the hide and show combinators in [ImportDirective]s and
- * [ExportDirective]s should resolve to the elements that are being hidden or shown,
- * respectively, unless those names are not defined in the specified library (or the specified
- * library does not exist).
- * * Every [PartDirective] should resolve to the element representing the compilation unit
- * being specified by the string unless the specified compilation unit does not exist (a
- * [CompilationUnitElement]).
- * </ol>
- * Note that AST nodes that would represent elements that are not defined are not resolved to
- * anything. This includes such things as references to undeclared variables (which is an error) and
- * names in hide and show combinators that are not defined in the imported library (which is not an
+ * An object used by instances of [ResolverVisitor] to resolve references within
+ * the AST structure to the elements being referenced. The requirements for the
+ * element resolver are:
+ *
+ * 1. Every [SimpleIdentifier] should be resolved to the element to which it
+ *    refers. Specifically:
+ *    * An identifier within the declaration of that name should resolve to the
+ *      element being declared.
+ *    * An identifier denoting a prefix should resolve to the element
+ *      representing the import that defines the prefix (an [ImportElement]).
+ *    * An identifier denoting a variable should resolve to the element
+ *      representing the variable (a [VariableElement]).
+ *    * An identifier denoting a parameter should resolve to the element
+ *      representing the parameter (a [ParameterElement]).
+ *    * An identifier denoting a field should resolve to the element
+ *      representing the getter or setter being invoked (a
+ *      [PropertyAccessorElement]).
+ *    * An identifier denoting the name of a method or function being invoked
+ *      should resolve to the element representing the method or function (an
+ *      [ExecutableElement]).
+ *    * An identifier denoting a label should resolve to the element
+ *      representing the label (a [LabelElement]).
+ *    The identifiers within directives are exceptions to this rule and are
+ *    covered below.
+ * 2. Every node containing a token representing an operator that can be
+ *    overridden ( [BinaryExpression], [PrefixExpression], [PostfixExpression])
+ *    should resolve to the element representing the method invoked by that
+ *    operator (a [MethodElement]).
+ * 3. Every [FunctionExpressionInvocation] should resolve to the element
+ *    representing the function being invoked (a [FunctionElement]). This will
+ *    be the same element as that to which the name is resolved if the function
+ *    has a name, but is provided for those cases where an unnamed function is
+ *    being invoked.
+ * 4. Every [LibraryDirective] and [PartOfDirective] should resolve to the
+ *    element representing the library being specified by the directive (a
+ *    [LibraryElement]) unless, in the case of a part-of directive, the
+ *    specified library does not exist.
+ * 5. Every [ImportDirective] and [ExportDirective] should resolve to the
+ *    element representing the library being specified by the directive unless
+ *    the specified library does not exist (an [ImportElement] or
+ *    [ExportElement]).
+ * 6. The identifier representing the prefix in an [ImportDirective] should
+ *    resolve to the element representing the prefix (a [PrefixElement]).
+ * 7. The identifiers in the hide and show combinators in [ImportDirective]s
+ *    and [ExportDirective]s should resolve to the elements that are being
+ *    hidden or shown, respectively, unless those names are not defined in the
+ *    specified library (or the specified library does not exist).
+ * 8. Every [PartDirective] should resolve to the element representing the
+ *    compilation unit being specified by the string unless the specified
+ *    compilation unit does not exist (a [CompilationUnitElement]).
+ *
+ * Note that AST nodes that would represent elements that are not defined are
+ * not resolved to anything. This includes such things as references to
+ * undeclared variables (which is an error) and names in hide and show
+ * combinators that are not defined in the imported library (which is not an
  * error).
  */
 class ElementResolver extends SimpleAstVisitor<Object> {
   /**
    * The resolver driving this participant.
    */
   final ResolverVisitor _resolver;
 
   /**
    * The element for the library containing the compilation unit being visited.
@@ skipping 15 matching lines @@
    * The type representing the type 'dynamic'.
    */
   DartType _dynamicType;
 
   /**
    * The type representing the type 'type'.
    */
   DartType _typeType;
 
   /**
-   * A utility class for the resolver to answer the question of "what are my subtypes?".
+   * A utility class for the resolver to answer the question of "what are my
+   * subtypes?".
    */
   SubtypeManager _subtypeManager;
 
   /**
    * The object keeping track of which elements have had their types promoted.
    */
   TypePromotionManager _promoteManager;
 
   /**
-   * Initialize a newly created visitor to resolve the nodes in a compilation unit.
-   *
-   * @param resolver the resolver driving this participant
+   * Initialize a newly created visitor to work for the given [_resolver] to
+   * resolve the nodes in a compilation unit.
    */
   ElementResolver(this._resolver) {
     this._definingLibrary = _resolver.definingLibrary;
     AnalysisOptions options = _definingLibrary.context.analysisOptions;
     _enableHints = options.hint;
     _enableStrictCallChecks = options.enableStrictCallChecks;
     _dynamicType = _resolver.typeProvider.dynamicType;
     _typeType = _resolver.typeProvider.typeType;
     _subtypeManager = new SubtypeManager();
     _promoteManager = _resolver.promoteManager;
   }
 
   /**
-   * @return `true` iff current enclosing function is constant constructor declaration.
+   * Return `true` iff the current enclosing function is a constant constructor
+   * declaration.
    */
   bool get isInConstConstructor {
     ExecutableElement function = _resolver.enclosingFunction;
     if (function is ConstructorElement) {
       return function.isConst;
     }
     return false;
   }
 
   @override
@@ skipping 944 matching lines @@
     return null;
   }
 
   @override
   Object visitVariableDeclaration(VariableDeclaration node) {
     _setMetadata(node.element, node);
     return null;
   }
 
   /**
-   * Generate annotation elements for each of the annotations in the given node list and add them to
-   * the given list of elements.
-   *
-   * @param annotationList the list of elements to which new elements are to be added
-   * @param annotations the AST nodes used to generate new elements
+   * Generate annotation elements for each of the annotations in the
+   * [annotationList] and add them to the given list of [annotations].
    */
   void _addAnnotations(List<ElementAnnotationImpl> annotationList,
       NodeList<Annotation> annotations) {
     int annotationCount = annotations.length;
     for (int i = 0; i < annotationCount; i++) {
       Annotation annotation = annotations[i];
       Element resolvedElement = annotation.element;
       if (resolvedElement != null) {
         ElementAnnotationImpl elementAnnotation =
             new ElementAnnotationImpl(resolvedElement);
         annotation.elementAnnotation = elementAnnotation;
         annotationList.add(elementAnnotation);
       }
     }
   }
 
   /**
-   * 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
+   * 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. The [target] is the target of the invocation, or `null` if there
+   * was no target. The flag [useStaticContext] should be `true` if the
+   * invocation is in a static constant (does not have access to instance state.
    */
   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.
@@ skipping 64 matching lines @@
             // targetType.getElement()
             return StaticTypeWarningCode.UNDEFINED_METHOD;
           }
         }
       }
     }
     return null;
   }
 
   /**
-   * Check that the for some index expression that the method element was resolved, otherwise a
-   * [StaticTypeWarningCode.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
+   * Check that the given index [expression] was resolved, otherwise a
+   * [StaticTypeWarningCode.UNDEFINED_OPERATOR] is generated. The [target] is
+   * the target of the expression. The [methodName] is the name of the operator
+   * associated with the context of using of the given index expression.
    */
-  bool _checkForUndefinedIndexOperator(IndexExpression node, Expression target,
-      String methodName, MethodElement staticMethod,
+  bool _checkForUndefinedIndexOperator(IndexExpression expression,
+      Expression target, String methodName, MethodElement staticMethod,
       MethodElement propagatedMethod, DartType staticType,
       DartType propagatedType) {
     bool shouldReportMissingMember_static =
         _shouldReportMissingMember(staticType, staticMethod);
     bool shouldReportMissingMember_propagated =
         !shouldReportMissingMember_static &&
             _enableHints &&
             _shouldReportMissingMember(propagatedType, propagatedMethod) &&
             !_memberFoundInSubclass(
                 propagatedType.element, methodName, true, false);
     if (shouldReportMissingMember_static ||
         shouldReportMissingMember_propagated) {
-      sc.Token leftBracket = node.leftBracket;
-      sc.Token rightBracket = node.rightBracket;
+      sc.Token leftBracket = expression.leftBracket;
+      sc.Token rightBracket = expression.rightBracket;
       ErrorCode errorCode;
       if (shouldReportMissingMember_static) {
         if (target is SuperExpression) {
           errorCode = StaticTypeWarningCode.UNDEFINED_SUPER_OPERATOR;
         } else {
           errorCode = StaticTypeWarningCode.UNDEFINED_OPERATOR;
         }
       } else {
         errorCode = HintCode.UNDEFINED_OPERATOR;
       }
       DartType type =
           shouldReportMissingMember_static ? staticType : propagatedType;
       if (leftBracket == null || rightBracket == null) {
-        _recordUndefinedNode(
-            type.element, errorCode, node, [methodName, type.displayName]);
+        _recordUndefinedNode(type.element, errorCode, expression, [
+          methodName,
+          type.displayName
+        ]);
       } else {
         int offset = leftBracket.offset;
         int length = rightBracket.offset - offset + 1;
         _recordUndefinedOffset(type.element, errorCode, offset, length, [
           methodName,
           type.displayName
         ]);
       }
       return true;
     }
     return false;
   }
 
   /**
-   * 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
+   * Given an [argumentList] and the executable [element] that  will be invoked
+   * using those arguments, 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.
    */
   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) {
@@ skipping 25 matching lines @@
         if (callMethod != null) {
           List<ParameterElement> parameters = callMethod.parameters;
           return _resolveArgumentsToParameters(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
+   * If the given [element] is a setter, return the getter associated with it.
+   * Otherwise, return the element unchanged.
    */
   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;
   }
 
   /**
-   * Return `true` if the given element is not a proxy.
-   *
-   * @param element the enclosing element. If null, `true` will be returned.
-   * @return `false` iff the passed [Element] is a [ClassElement] that is a proxy
-   *         or inherits proxy
-   * See [ClassElement.isOrInheritsProxy].
+   * Return `true` if the given [element] is not a proxy. See
+   * [ClassElement.isOrInheritsProxy].
    */
   bool _doesntHaveProxy(Element element) =>
       !(element is ClassElement && element.isOrInheritsProxy);
 
   /**
-   * 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.
-   *
-   * @param identifier the identifier that might have been imported using a prefix
-   * @return the element that was found
+   * 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.
    */
   Element _findImportWithoutPrefix(SimpleIdentifier identifier) {
     Element element = null;
     Scope nameScope = _resolver.nameScope;
     for (ImportElement importElement in _definingLibrary.imports) {
       PrefixElement prefixElement = importElement.prefix;
       if (prefixElement != null) {
         Identifier prefixedIdentifier = new SyntheticIdentifier(
             "${prefixElement.name}.${identifier.name}", identifier);
         Element importedElement =
             nameScope.lookup(prefixedIdentifier, _definingLibrary);
         if (importedElement != null) {
           if (element == null) {
             element = importedElement;
           } else {
             element = MultiplyDefinedElementImpl.fromElements(
                 _definingLibrary.context, element, importedElement);
           }
         }
       }
     }
     return element;
   }
 
   /**
-   * Assuming that the given expression is a prefix for a deferred import, return the library that
-   * is being imported.
-   *
-   * @param expression the expression representing the deferred import's prefix
-   * @return the library that is being imported by the import associated with the prefix
+   * Assuming that the given [expression] is a prefix for a deferred import,
+   * return the library that is being imported.
    */
   LibraryElement _getImportedLibrary(Expression expression) {
     PrefixElement prefixElement =
         (expression as SimpleIdentifier).staticElement as PrefixElement;
     List<ImportElement> imports =
         prefixElement.enclosingElement.getImportsWithPrefix(prefixElement);
     return imports[0].importedLibrary;
   }
 
   /**
-   * Return the name of the method invoked by the given postfix expression.
-   *
-   * @param node the postfix expression being invoked
-   * @return the name of the method invoked by the expression
+   * Return the name of the method invoked by the given postfix [expression].
    */
-  String _getPostfixOperator(PostfixExpression node) =>
-      (node.operator.type == sc.TokenType.PLUS_PLUS)
+  String _getPostfixOperator(PostfixExpression expression) =>
+      (expression.operator.type == sc.TokenType.PLUS_PLUS)
           ? sc.TokenType.PLUS.lexeme
           : sc.TokenType.MINUS.lexeme;
 
   /**
-   * Return the name of the method invoked by the given postfix expression.
-   *
-   * @param node the postfix expression being invoked
-   * @return the name of the method invoked by the expression
+   * Return the name of the method invoked by the given postfix [expression].
    */
-  String _getPrefixOperator(PrefixExpression node) {
-    sc.Token operator = node.operator;
+  String _getPrefixOperator(PrefixExpression expression) {
+    sc.Token operator = expression.operator;
     sc.TokenType operatorType = operator.type;
     if (operatorType == sc.TokenType.PLUS_PLUS) {
       return sc.TokenType.PLUS.lexeme;
     } else if (operatorType == sc.TokenType.MINUS_MINUS) {
       return sc.TokenType.MINUS.lexeme;
     } else if (operatorType == sc.TokenType.MINUS) {
       return "unary-";
     } else {
       return operator.lexeme;
     }
   }
 
   /**
-   * 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
+   * Return the propagated type of the given [expression] that is to be used for
+   * type analysis.
    */
   DartType _getPropagatedType(Expression expression) {
     DartType 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
+   * Return the static type of the given [expression] that is to be used for
+   * type analysis.
    */
   DartType _getStaticType(Expression expression) {
     if (expression is NullLiteral) {
       return _resolver.typeProvider.bottomType;
     }
     DartType 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 expression is a prefix for a deferred import.
-   *
-   * @param expression the expression being tested
-   * @return `true` if the given expression is a prefix for a deferred import
+   * Return `true` if the given [expression] is a prefix for a deferred import.
    */
   bool _isDeferredPrefix(Expression expression) {
     if (expression is! SimpleIdentifier) {
       return false;
     }
     Element element = (expression as SimpleIdentifier).staticElement;
     if (element is! PrefixElement) {
       return false;
     }
     PrefixElement prefixElement = element as PrefixElement;
     List<ImportElement> imports =
         prefixElement.enclosingElement.getImportsWithPrefix(prefixElement);
     if (imports.length != 1) {
       return false;
     }
     return imports[0].isDeferred;
   }
 
   /**
-   * Return `true` if the given type represents an object that could be invoked using the call
-   * operator '()'.
-   *
-   * @param type the type being tested
-   * @return `true` if the given type represents an object that could be invoked
+   * Return `true` if the given [type] represents an object that could be
+   * invoked using the call operator '()'.
    */
   bool _isExecutableType(DartType type) {
     if (type.isDynamic || type is FunctionType) {
       return true;
     } else if (!_enableStrictCallChecks &&
         (type.isDartCoreFunction || type.isObject)) {
       return true;
     } else if (type is InterfaceType) {
       ClassElement classElement = type.element;
       // 16078 from Gilad: If the type is a Functor with the @proxy annotation,
       // treat it as an executable type.
       // example code: NonErrorResolverTest.
       // test_invocationOfNonFunction_proxyOnFunctionClass()
       if (classElement.isProxy &&
           type.isSubtypeOf(_resolver.typeProvider.functionType)) {
         return true;
       }
       MethodElement methodElement = classElement.lookUpMethod(
           FunctionElement.CALL_METHOD_NAME, _definingLibrary);
       return methodElement != null;
     }
     return false;
   }
 
   /**
-   * Return `true` if the given element is a static element.
-   *
-   * @param element the element being tested
-   * @return `true` if the given element is a static element
+   * Return `true` if the given [element] is a static element.
    */
   bool _isStatic(Element element) {
     if (element is ExecutableElement) {
       return element.isStatic;
     } else if (element is PropertyInducingElement) {
       return element.isStatic;
     }
     return false;
   }
 
   /**
-   * Return `true` if the given node can validly be resolved to a prefix:
+   * Return `true` if the given [node] can validly be resolved to a prefix:
    * * it is the prefix in an import directive, or
    * * it is the prefix in a prefixed identifier.
-   *
-   * @param node the node being tested
-   * @return `true` if the given node is the prefix in an import directive
    */
   bool _isValidAsPrefix(SimpleIdentifier node) {
     AstNode parent = node.parent;
     if (parent is ImportDirective) {
       return identical(parent.prefix, node);
     } else if (parent is PrefixedIdentifier) {
       return true;
     } else if (parent is MethodInvocation) {
       return identical(parent.target, node);
     }
     return false;
   }
 
   /**
    * Return the target of a break or continue statement, and update the static
-   * element of its label (if any).  [parentNode] is the AST node of the break
-   * or continue statement, [labelNode] is the label contained in that
-   * statement (if any), and [isContinue] is true if the node being visited is
-   * a continue statement.
+   * element of its label (if any). The [parentNode] is the AST node of the
+   * break or continue statement. The [labelNode] is the label contained in that
+   * statement (if any). The flag [isContinue] is `true` if the node being
+   * visited is a continue statement.
    */
   AstNode _lookupBreakOrContinueTarget(
       AstNode parentNode, SimpleIdentifier labelNode, bool isContinue) {
     if (labelNode == null) {
       return _resolver.implicitLabelScope.getTarget(isContinue);
     } else {
       LabelScope labelScope = _resolver.labelScope;
       if (labelScope == null) {
         // There are no labels in scope, so by definition the label is
         // undefined.
@@ skipping 15 matching lines @@
           .getAncestor((element) => element is ExecutableElement);
       if (!identical(labelContainer, _resolver.enclosingFunction)) {
         _resolver.reportErrorForNode(CompileTimeErrorCode.LABEL_IN_OUTER_SCOPE,
             labelNode, [labelNode.name]);
       }
       return definingScope.node;
     }
   }
 
   /**
-   * Look up the getter with the given name in the given type. Return the element representing the
-   * getter that was found, or `null` if there is no getter with the given name.
-   *
-   * @param target the target of the invocation, or `null` if there is no target
-   * @param type the type in which the getter is defined
-   * @param getterName the name of the getter being looked up
-   * @return the element representing the getter that was found
+   * Look up the getter with the given [getterName] in the given [type]. Return
+   * the element representing the getter that was found, or `null` if there is
+   * no getter with the given name. The [target] is the target of the
+   * invocation, or `null` if there is no target.
    */
   PropertyAccessorElement _lookUpGetter(
       Expression target, DartType type, String getterName) {
     type = _resolveTypeParameter(type);
     if (type is InterfaceType) {
       InterfaceType interfaceType = type;
       PropertyAccessorElement accessor;
       if (target is SuperExpression) {
         accessor = interfaceType.lookUpGetterInSuperclass(
             getterName, _definingLibrary);
       } else {
         accessor = interfaceType.lookUpGetter(getterName, _definingLibrary);
       }
       if (accessor != null) {
         return accessor;
       }
       return _lookUpGetterInInterfaces(
           interfaceType, false, getterName, new HashSet<ClassElement>());
     }
     return null;
   }
 
   /**
-   * Look up the getter with the given name in the interfaces implemented by the given type, either
-   * directly or indirectly. Return the element representing the getter that was found, or
-   * `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
+   * Look up the getter with the given [getterName] in the interfaces
+   * implemented by the given [targetType], either directly or indirectly.
+   * Return the element representing the getter that was found, or `null` if
+   * there is no getter with the given name. The flag [includeTargetType] should
+   * be `true` if the search should include the target type. The
+   * [visitedInterfaces] is a set containing all of the interfaces that have
+   * been examined, used to prevent infinite recursion and to optimize the
+   * search.
    */
   PropertyAccessorElement _lookUpGetterInInterfaces(InterfaceType targetType,
       bool includeTargetType, String getterName,
       HashSet<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)) {
@@ skipping 22 matching lines @@
     }
     InterfaceType superclass = targetType.superclass;
     if (superclass == null) {
       return null;
     }
     return _lookUpGetterInInterfaces(
         superclass, true, getterName, visitedInterfaces);
   }
 
   /**
-   * Look up the method or getter with the given name in the given type. Return the element
-   * representing the method or getter that was found, or `null` if there is no method or
-   * getter with the given name.
-   *
-   * @param type the type in which the method or getter is defined
-   * @param memberName the name of the method or getter being looked up
-   * @return the element representing the method or getter that was found
+   * Look up the method or getter with the given [memberName] in the given
+   * [type]. Return the element representing the method or getter that was
+   * found, or `null` if there is no method or getter with the given name.
    */
   ExecutableElement _lookupGetterOrMethod(DartType type, String memberName) {
     type = _resolveTypeParameter(type);
     if (type is InterfaceType) {
       InterfaceType interfaceType = type;
       ExecutableElement member =
           interfaceType.lookUpMethod(memberName, _definingLibrary);
       if (member != null) {
         return member;
       }
       member = interfaceType.lookUpGetter(memberName, _definingLibrary);
       if (member != null) {
         return member;
       }
       return _lookUpGetterOrMethodInInterfaces(
           interfaceType, false, memberName, new HashSet<ClassElement>());
     }
     return null;
   }
 
   /**
-   * Look up the method or getter with the given name in the interfaces implemented by the given
-   * type, either directly or indirectly. Return the element representing the method or getter that
-   * 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
+   * Look up the method or getter with the given [memberName] in the interfaces
+   * implemented by the given [targetType], either directly or indirectly.
+   * Return the element representing the method or getter that was found, or
+   * `null` if there is no method or getter with the given name. The flag
+   * [includeTargetType] should be `true` if the search should include the
+   * target type. The [visitedInterfaces] is a set containing all of the
+   * interfaces that have been examined, used to prevent infinite recursion and
+   * to optimize the search.
    */
   ExecutableElement _lookUpGetterOrMethodInInterfaces(InterfaceType targetType,
       bool includeTargetType, String memberName,
       HashSet<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)) {
@@ skipping 26 matching lines @@
     }
     InterfaceType superclass = targetType.superclass;
     if (superclass == null) {
       return null;
     }
     return _lookUpGetterOrMethodInInterfaces(
         superclass, true, memberName, visitedInterfaces);
   }
 
   /**
-   * Look up the method with the given name in the given type. Return the element representing the
-   * method that was found, or `null` if there is no method with the given name.
-   *
-   * @param target the target of the invocation, or `null` if there is no target
-   * @param type the type in which the method is defined
-   * @param methodName the name of the method being looked up
-   * @return the element representing the method that was found
+   * Look up the method with the given [methodName] in the given [type]. Return
+   * the element representing the method that was found, or `null` if there is
+   * no method with the given name. The [target] is the target of the
+   * invocation, or `null` if there is no target.
    */
   MethodElement _lookUpMethod(
       Expression target, DartType type, String methodName) {
     type = _resolveTypeParameter(type);
     if (type is InterfaceType) {
       InterfaceType interfaceType = type;
       MethodElement method;
       if (target is SuperExpression) {
         method = interfaceType.lookUpMethodInSuperclass(
             methodName, _definingLibrary);
@@ skipping 10 matching lines @@
       // and work with functions, methods, constructors, and property accessors.
       // However, I won't be able to assume it returns [MethodElement] here
       // then.
       return _maybeMergeExecutableElements(
           _lookupMethods(target, type, methodName)) as MethodElement;
     }
     return null;
   }
 
   /**
-   * Look up the method with the given name in the interfaces implemented by the given type, either
-   * directly or indirectly. Return the element representing the method that was found, or
-   * `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
+   * Look up the method with the given [methodName] in the interfaces
+   * implemented by the given [targetType], either directly or indirectly.
+   * Return the element representing the method that was found, or `null` if
+   * there is no method with the given name. The flag [includeTargetType] should
+   * be `true` if the search should include the target type. The
+   * [visitedInterfaces] is a set containing all of the interfaces that have
+   * been examined, used to prevent infinite recursion and to optimize the
+   * search.
    */
   MethodElement _lookUpMethodInInterfaces(InterfaceType targetType,
       bool includeTargetType, String methodName,
       HashSet<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)) {
@@ skipping 22 matching lines @@
     }
     InterfaceType superclass = targetType.superclass;
     if (superclass == null) {
       return null;
     }
     return _lookUpMethodInInterfaces(
         superclass, true, methodName, visitedInterfaces);
   }
 
   /**
-   * Look up all methods of a given name defined on a union type.
-   *
-   * @param target
-   * @param type
-   * @param methodName
-   * @return all methods named `methodName` defined on the union type `type`.
+   * Look up all methods with the given [methodName] that are defined on the
+   * given union [type].
    */
   Set<ExecutableElement> _lookupMethods(
       Expression target, UnionType type, String methodName) {
     Set<ExecutableElement> methods = new HashSet<ExecutableElement>();
     bool allElementsHaveMethod = true;
     for (DartType t in type.elements) {
       MethodElement m = _lookUpMethod(target, t, methodName);
       if (m != null) {
         methods.add(m);
       } else {
         allElementsHaveMethod = false;
       }
     }
     // For strict union types we require that all types in the union define the
     // method.
     if (AnalysisEngine.instance.strictUnionTypes) {
       if (allElementsHaveMethod) {
         return methods;
       } else {
         return new Set<ExecutableElement>();
       }
     } else {
       return methods;
     }
   }
 
   /**
-   * Look up the setter with the given name in the given type. Return the element representing the
-   * setter that was found, or `null` if there is no setter with the given name.
-   *
-   * @param target the target of the invocation, or `null` if there is no target
-   * @param type the type in which the setter is defined
-   * @param setterName the name of the setter being looked up
-   * @return the element representing the setter that was found
+   * Look up the setter with the given [setterName] in the given [type]. Return
+   * the element representing the setter that was found, or `null` if there is
+   * no setter with the given name. The [target] is the target of the
+   * invocation, or `null` if there is no target.
    */
   PropertyAccessorElement _lookUpSetter(
       Expression target, DartType type, String setterName) {
     type = _resolveTypeParameter(type);
     if (type is InterfaceType) {
       InterfaceType interfaceType = type;
       PropertyAccessorElement accessor;
       if (target is SuperExpression) {
         accessor = interfaceType.lookUpSetterInSuperclass(
             setterName, _definingLibrary);
       } else {
         accessor = interfaceType.lookUpSetter(setterName, _definingLibrary);
       }
       if (accessor != null) {
         return accessor;
       }
       return _lookUpSetterInInterfaces(
           interfaceType, false, setterName, new HashSet<ClassElement>());
     }
     return null;
   }
 
   /**
-   * Look up the setter with the given name in the interfaces implemented by the given type, either
-   * directly or indirectly. Return the element representing the setter that was found, or
-   * `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
+   * Look up the setter with the given [setterName] in the interfaces
+   * implemented by the given [targetType], either directly or indirectly.
+   * Return the element representing the setter that was found, or `null` if
+   * there is no setter with the given name. The [targetType] is the type in
+   * which the setter might be defined. The flag [includeTargetType] should be
+   * `true` if the search should include the target type. The
+   * [visitedInterfaces] is a set containing all of the interfaces that have
+   * been examined, used to prevent infinite recursion and to optimize the
+   * search.
    */
   PropertyAccessorElement _lookUpSetterInInterfaces(InterfaceType targetType,
       bool includeTargetType, String setterName,
       HashSet<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)) {
@@ skipping 22 matching lines @@
     }
     InterfaceType superclass = targetType.superclass;
     if (superclass == null) {
       return null;
     }
     return _lookUpSetterInInterfaces(
         superclass, true, setterName, visitedInterfaces);
   }
 
   /**
-   * Given some class element, this method uses [subtypeManager] to find the set of all
-   * subtypes; the subtypes are then searched for a member (method, getter, or setter), that matches
-   * a passed
-   *
-   * @param element the class element to search the subtypes of, if a non-ClassElement element is
-   *          passed, then `false` is returned
-   * @param memberName the member name to search for
-   * @param asMethod `true` if the methods should be searched for in the subtypes
-   * @param asAccessor `true` if the accessors (getters and setters) should be searched for in
-   *          the subtypes
-   * @return `true` if and only if the passed memberName was found in a subtype
+   * Given some class [element], this method uses [_subtypeManager] to find the
+   * set of all subtypes; the subtypes are then searched for a member (method,
+   * getter, or setter), that has the given [memberName]. The flag [asMethod]
+   * should be `true` if the methods should be searched for in the subtypes. The
+   * flag [asAccessor] should be `true` if the accessors (getters and setters)
+   * should be searched for in the subtypes.
    */
   bool _memberFoundInSubclass(
       Element element, String memberName, bool asMethod, bool asAccessor) {
     if (element is ClassElement) {
       _subtypeManager.ensureLibraryVisited(_definingLibrary);
       HashSet<ClassElement> subtypeElements =
           _subtypeManager.computeAllSubtypes(element);
       for (ClassElement subtypeElement in subtypeElements) {
         if (asMethod && subtypeElement.getMethod(memberName) != null) {
           return true;
         } else if (asAccessor &&
             (subtypeElement.getGetter(memberName) != null ||
                 subtypeElement.getSetter(memberName) != null)) {
           return true;
         }
       }
     }
     return false;
   }
 
   /**
-   * Return the binary operator that is invoked by the given compound assignment operator.
-   *
-   * @param operator the assignment operator being mapped
-   * @return the binary operator that invoked by the given assignment operator
+   * Return the binary operator that is invoked by the given compound assignment
+   * [operator].
    */
   sc.TokenType _operatorFromCompoundAssignment(sc.TokenType operator) {
     while (true) {
       if (operator == sc.TokenType.AMPERSAND_EQ) {
         return sc.TokenType.AMPERSAND;
       } else if (operator == sc.TokenType.BAR_EQ) {
         return sc.TokenType.BAR;
       } else if (operator == sc.TokenType.CARET_EQ) {
         return sc.TokenType.CARET;
       } else if (operator == sc.TokenType.GT_GT_EQ) {
@@ skipping 16 matching lines @@
         // Internal error: Unmapped assignment operator.
         AnalysisEngine.instance.logger.logError(
             "Failed to map ${operator.lexeme} to it's corresponding operator");
         return operator;
       }
       break;
     }
   }
 
   /**
-   * Record that the given node is undefined, causing an error to be reported if appropriate.
-   *
-   * @param declaringElement the element inside which no declaration was found. If this element is a
-   *          proxy, no error will be reported. If null, then an error will always be reported.
-   * @param errorCode the error code to report.
-   * @param node the node which is undefined.
-   * @param arguments arguments to the error message.
+   * Record that the given [node] is undefined, causing an error to be reported
+   * if appropriate. The [declaringElement] is the element inside which no
+   * declaration was found. If this element is a proxy, no error will be
+   * reported. If null, then an error will always be reported. The [errorCode]
+   * is the error code to report. The [arguments] are the arguments to the error
+   * message.
    */
   void _recordUndefinedNode(Element declaringElement, ErrorCode errorCode,
       AstNode node, List<Object> arguments) {
     if (_doesntHaveProxy(declaringElement)) {
       _resolver.reportErrorForNode(errorCode, node, arguments);
     }
   }
 
   /**
-   * Record that the given offset/length is undefined, causing an error to be reported if
-   * appropriate.
-   *
-   * @param declaringElement the element inside which no declaration was found. If this element is a
-   *          proxy, no error will be reported. If null, then an error will always be reported.
-   * @param errorCode the error code to report.
-   * @param offset the offset to the text which is undefined.
-   * @param length the length of the text which is undefined.
-   * @param arguments arguments to the error message.
+   * Record that the given [offset]/[length] is undefined, causing an error to
+   * be reported if appropriate. The [declaringElement] is the element inside
+   * which no declaration was found. If this element is a proxy, no error will
+   * be reported. If null, then an error will always be reported. The
+   * [errorCode] is the error code to report. The [arguments] are arguments to
+   * the error message.
    */
   void _recordUndefinedOffset(Element declaringElement, ErrorCode errorCode,
       int offset, int length, List<Object> arguments) {
     if (_doesntHaveProxy(declaringElement)) {
       _resolver.reportErrorForOffset(errorCode, offset, length, arguments);
     }
   }
 
   /**
-   * Record that the given token is undefined, causing an error to be reported if appropriate.
-   *
-   * @param declaringElement the element inside which no declaration was found. If this element is a
-   *          proxy, no error will be reported. If null, then an error will always be reported.
-   * @param errorCode the error code to report.
-   * @param token the token which is undefined.
-   * @param arguments arguments to the error message.
+   * Record that the given [token] is undefined, causing an error to be reported
+   * if appropriate. The [declaringElement] is the element inside which no
+   * declaration was found. If this element is a proxy, no error will be
+   * reported. If null, then an error will always be reported. The [errorCode]
+   * is the error code to report. The [arguments] are arguments to the error
+   * message.
    */
   void _recordUndefinedToken(Element declaringElement, ErrorCode errorCode,
       sc.Token token, List<Object> arguments) {
     if (_doesntHaveProxy(declaringElement)) {
       _resolver.reportErrorForToken(errorCode, token, arguments);
     }
   }
 
   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 =
         _resolveArgumentsToFunction(true, argumentList, constructor);
     if (parameters != null) {
       argumentList.correspondingStaticParameters = parameters;
     }
   }
 
   /**
-   * Continues resolution of the given [Annotation].
-   *
-   * @param annotation the [Annotation] to resolve
+   * Continues resolution of the given [annotation].
    */
   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;
@@ skipping 99 matching lines @@
     VariableElement variableElement = accessorElement.variable;
     if (!variableElement.isConst) {
       _resolver.reportErrorForNode(
           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
-   * @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
+   * Given an [argumentList] and the [executableElement] that will be invoked
+   * using those argument, compute the list of parameters that correspond to the
+   * list of arguments. An error will be reported if any of the arguments cannot
+   * be matched to a parameter. The flag [reportError] should be `true` if a
+   * compile-time error should be reported; or `false` if a compile-time warning
+   * should be reported. Return the parameters that correspond to the arguments,
+   * or `null` if no correspondence could be computed.
    */
   List<ParameterElement> _resolveArgumentsToFunction(bool reportError,
       ArgumentList argumentList, ExecutableElement executableElement) {
     if (executableElement == null) {
       return null;
     }
     List<ParameterElement> parameters = executableElement.parameters;
     return _resolveArgumentsToParameters(reportError, argumentList, parameters);
   }
 
   /**
-   * Given a list of arguments and the parameters related to 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.
-   *
-   * @param reportError if `true` then compile-time error should be reported; if `false`
-   *          then compile-time warning
-   * @param argumentList the list of arguments being passed to the element
-   * @param parameters the of the function that will be invoked with the arguments
-   * @return the parameters that correspond to the arguments
+   * Given an [argumentList] and the [parameters] related to the element that
+   * will be invoked using those arguments, compute the list of parameters that
+   * correspond to the list of arguments. An error will be reported if any of
+   * the arguments cannot be matched to a parameter. The flag [reportError]
+   * should be `true` if a compile-time error should be reported; or `false` if
+   * a compile-time warning should be reported. Return the parameters that
+   * correspond to the arguments.
    */
   List<ParameterElement> _resolveArgumentsToParameters(bool reportError,
       ArgumentList argumentList, List<ParameterElement> parameters) {
     List<ParameterElement> requiredParameters = new List<ParameterElement>();
     List<ParameterElement> positionalParameters = new List<ParameterElement>();
     HashMap<String, ParameterElement> namedParameters =
         new HashMap<String, ParameterElement>();
     for (ParameterElement parameter in parameters) {
       ParameterKind kind = parameter.parameterKind;
       if (kind == ParameterKind.REQUIRED) {
@@ skipping 99 matching lines @@
         _recordUndefinedToken(propagatedType.element,
             HintCode.UNDEFINED_OPERATOR, node.operator, [
           methodName,
           propagatedType.displayName
         ]);
       }
     }
   }
 
   /**
-   * 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
+   * Resolve the names in the given [combinators] in the scope of the given
+   * [library].
    */
   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;
     }
@@ skipping 18 matching lines @@
           if (element is PropertyAccessorElement) {
             element = (element as PropertyAccessorElement).variable;
           }
           name.staticElement = element;
         }
       }
     }
   }
 
   /**
-   * Given that we are accessing a property of the given [classElement] with
-   * the given [propertyName], return the element that represents the property.
+   * Given that we are accessing a property of the given [classElement] with the
+   * given [propertyName], return the element that represents the property.
    */
   Element _resolveElement(
       ClassElementImpl classElement, SimpleIdentifier propertyName) {
     String name = propertyName.name;
     Element element = null;
     if (propertyName.inSetterContext()) {
       element = classElement.getSetter(name);
     }
     if (element == null) {
       element = classElement.getGetter(name);
     }
     if (element == null) {
       element = classElement.getMethod(name);
     }
     if (element != null && element.isAccessibleIn(_definingLibrary)) {
       return element;
     }
     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
+   * 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. The [methodName] is the name of the method
+   * being invoked ('m').
    */
   Element _resolveInvokedElement(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 an invocation of the form 'e.m(a1, ..., an)', resolve 'e.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 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
+   * Given an invocation of the form 'e.m(a1, ..., an)', resolve 'e.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. The [target] is the target of the invocation
+   * ('e'). The [targetType] is the type of the target. The [methodName] is th
+   *  name of the method being invoked ('m').
    */
   Element _resolveInvokedElementWithTarget(
       Expression target, DartType targetType, SimpleIdentifier methodName) {
     if (targetType is InterfaceType || targetType is UnionType) {
       Element element = _lookUpMethod(target, targetType, methodName.name);
       if (element == null) {
         //
         // If there's no method, then it's possible that 'm' is a getter that
         // returns a function.
         //
@@ skipping 20 matching lines @@
           // identifier. Consider re-writing the AST.
           return element;
         }
       }
     }
     // TODO(brianwilkerson) Report this error.
     return null;
   }
 
   /**
-   * 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
-   * @return the element that represents the property
+   * Given that we are accessing a property of the given [targetType] with the
+   * given [propertyName], return the element that represents the property. The
+   * [target] is the target of the invocation ('e').
    */
   ExecutableElement _resolveProperty(
       Expression target, DartType targetType, SimpleIdentifier propertyName) {
     ExecutableElement memberElement = null;
     if (propertyName.inSetterContext()) {
       memberElement = _lookUpSetter(target, targetType, propertyName.name);
     }
     if (memberElement == null) {
       memberElement = _lookUpGetter(target, targetType, propertyName.name);
     }
@@ skipping 130 matching lines @@
         ]);
       } else {
         _recordUndefinedNode(declaringElement,
             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
+   * 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.
    */
-  Element _resolveSimpleIdentifier(SimpleIdentifier node) {
-    Element element = _resolver.nameScope.lookup(node, _definingLibrary);
-    if (element is PropertyAccessorElement && node.inSetterContext()) {
+  Element _resolveSimpleIdentifier(SimpleIdentifier identifier) {
+    Element element = _resolver.nameScope.lookup(identifier, _definingLibrary);
+    if (element is PropertyAccessorElement && identifier.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);
+            setter = _lookUpSetter(null, enclosingClass.type, identifier.name);
           }
         }
         if (setter != null) {
           element = setter;
         }
       }
     } else if (element == null &&
-        (node.inSetterContext() || node.parent is CommentReference)) {
+        (identifier.inSetterContext() ||
+            identifier.parent is CommentReference)) {
       element = _resolver.nameScope.lookup(
-          new SyntheticIdentifier("${node.name}=", node), _definingLibrary);
+          new SyntheticIdentifier("${identifier.name}=", identifier),
+          _definingLibrary);
     }
     ClassElement enclosingClass = _resolver.enclosingClass;
     if (element == null && enclosingClass != null) {
       InterfaceType enclosingType = enclosingClass.type;
       if (element == null &&
-          (node.inSetterContext() || node.parent is CommentReference)) {
-        element = _lookUpSetter(null, enclosingType, node.name);
+          (identifier.inSetterContext() ||
+              identifier.parent is CommentReference)) {
+        element = _lookUpSetter(null, enclosingType, identifier.name);
       }
-      if (element == null && node.inGetterContext()) {
-        element = _lookUpGetter(null, enclosingType, node.name);
+      if (element == null && identifier.inGetterContext()) {
+        element = _lookUpGetter(null, enclosingType, identifier.name);
       }
       if (element == null) {
-        element = _lookUpMethod(null, enclosingType, node.name);
+        element = _lookUpMethod(null, enclosingType, identifier.name);
       }
     }
     return element;
   }
 
   /**
-   * If the given type is a type parameter, resolve it to the type that should be used when looking
-   * up members. Otherwise, return the original type.
-   *
-   * @param type the type that is to be resolved if it is a type parameter
-   * @return the type that should be used in place of the argument if it is a type parameter, or the
-   *         original argument if it isn't a type parameter
+   * If the given [type] is a type parameter, resolve it to the type that should
+   * be used when looking up members. Otherwise, return the original type.
    */
   DartType _resolveTypeParameter(DartType type) {
     if (type is TypeParameterType) {
       DartType bound = type.element.bound;
       if (bound == null) {
         return _resolver.typeProvider.objectType;
       }
       return bound;
     }
     return type;
   }
 
   /**
-   * Given a node that can have annotations associated with it and the element to which that node
-   * has been resolved, create the annotations in the element model representing the annotations on
-   * the node.
-   *
-   * @param element the element to which the node has been resolved
-   * @param node the node that can have annotations associated with it
+   * Given a [node] that can have annotations associated with it and the
+   * [element] to which that node has been resolved, create the annotations in
+   * the element model representing the annotations on the node.
    */
   void _setMetadata(Element element, AnnotatedNode node) {
     if (element is! ElementImpl) {
       return;
     }
     List<ElementAnnotationImpl> annotationList =
         new List<ElementAnnotationImpl>();
     _addAnnotations(annotationList, node.metadata);
     if (node is VariableDeclaration && node.parent is VariableDeclarationList) {
       VariableDeclarationList list = node.parent as VariableDeclarationList;
       _addAnnotations(annotationList, list.metadata);
       if (list.parent is FieldDeclaration) {
         FieldDeclaration fieldDeclaration = list.parent as FieldDeclaration;
         _addAnnotations(annotationList, fieldDeclaration.metadata);
       } else if (list.parent is TopLevelVariableDeclaration) {
         TopLevelVariableDeclaration variableDeclaration =
             list.parent as TopLevelVariableDeclaration;
         _addAnnotations(annotationList, variableDeclaration.metadata);
       }
     }
     if (!annotationList.isEmpty) {
       (element as ElementImpl).metadata = annotationList;
     }
   }
 
   /**
-   * Given a node that can have annotations associated with it and the element to which that node
-   * has been resolved, create the annotations in the element model representing the annotations on
-   * the node.
-   *
-   * @param element the element to which the node has been resolved
-   * @param node the node that can have annotations associated with it
+   * Given a [node] that can have annotations associated with it and the
+   * [element] to which that node has been resolved, create the annotations in
+   * the element model representing the annotations on the node.
    */
   void _setMetadataForParameter(Element element, NormalFormalParameter node) {
     if (element is! ElementImpl) {
       return;
     }
     List<ElementAnnotationImpl> annotationList =
         new List<ElementAnnotationImpl>();
     _addAnnotations(annotationList, node.metadata);
     if (!annotationList.isEmpty) {
       (element as ElementImpl).metadata = annotationList;
     }
   }
 
   /**
-   * Return `true` if we should report an error as a result of looking up a member in the
-   * given type and not finding any member.
-   *
-   * @param type the type in which we attempted to perform the look-up
-   * @param member the result of the look-up
-   * @return `true` if we should report an error
+   * Return `true` if we should report an error as a result of looking up a
+   * [member] in the given [type] and not finding any member.
    */
   bool _shouldReportMissingMember(DartType type, Element member) {
     if (member != null || type == null || type.isDynamic || type.isBottom) {
       return false;
     }
     return true;
   }
 
   /**
-   * Checks whether the given expression is a reference to a class. If it is then the
-   * [ClassElement] is returned, otherwise `null` is returned.
-   *
-   * @param expression the expression to evaluate
-   * @return the element representing the class
+   * Checks whether the given [expression] is a reference to a class. If it is
+   * then the element representing the class is returned, otherwise `null` is
+   * returned.
    */
   static ClassElementImpl getTypeReference(Expression expression) {
     if (expression is Identifier) {
       Element staticElement = expression.staticElement;
       if (staticElement is ClassElementImpl) {
         return staticElement;
       }
     }
     return null;
   }
 
   /**
-   * Helper function for `maybeMergeExecutableElements` that does the actual merging.
-   *
-   * @param elementArrayToMerge non-empty array of elements to merge.
-   * @return
+   * Helper function for `maybeMergeExecutableElements` that does the actual
+   * merging. The [elementArrayToMerge] is the non-empty list of elements to
+   * merge.
    */
   static ExecutableElement _computeMergedExecutableElement(
       List<ExecutableElement> elementArrayToMerge) {
     // Flatten methods structurally. Based on
     // [InheritanceManager.computeMergedExecutableElement] and
     // [InheritanceManager.createSyntheticExecutableElement].
     //
     // However, the approach we take here is much simpler, but expected to work
     // well in the common case. It degrades gracefully in the uncommon case,
     // by computing the type [dynamic] for the method, preventing any
@@ skipping 51 matching lines @@
     e_out.synthetic = true;
     e_out.returnType = r_out;
     e_out.parameters = ps_out;
     e_out.type = new FunctionTypeImpl.con1(e_out);
     // Get NPE in [toString()] w/o this.
     e_out.enclosingElement = e_0.enclosingElement;
     return e_out;
   }
 
   /**
-   * Return `true` if the given identifier is the return type of a constructor declaration.
-   *
-   * @return `true` if the given identifier is the return type of a constructor declaration.
+   * Return `true` if the given [identifier] is the return type of a constructor
+   * declaration.
    */
   static bool _isConstructorReturnType(SimpleIdentifier identifier) {
     AstNode parent = identifier.parent;
     if (parent is ConstructorDeclaration) {
       return identical(parent.returnType, identifier);
     }
     return false;
   }
 
   /**
-   * Return `true` if the given identifier is the return type of a factory constructor.
-   *
-   * @return `true` if the given identifier is the return type of a factory constructor
-   *         declaration.
+   * Return `true` if the given [identifier] is the return type of a factory
+   * constructor.
    */
-  static bool _isFactoryConstructorReturnType(SimpleIdentifier node) {
-    AstNode parent = node.parent;
+  static bool _isFactoryConstructorReturnType(SimpleIdentifier identifier) {
+    AstNode parent = identifier.parent;
     if (parent is ConstructorDeclaration) {
       ConstructorDeclaration constructor = parent;
-      return identical(constructor.returnType, node) &&
+      return identical(constructor.returnType, identifier) &&
           constructor.factoryKeyword != null;
     }
     return false;
   }
 
   /**
-   * Return `true` if the given 'super' expression is used in a valid context.
-   *
-   * @param node the 'super' expression to analyze
-   * @return `true` if the 'super' expression is in a valid context
+   * Return `true` if the given 'super' [expression] is used in a valid context.
    */
-  static bool _isSuperInValidContext(SuperExpression node) {
-    for (AstNode n = node; n != null; n = n.parent) {
-      if (n is CompilationUnit) {
+  static bool _isSuperInValidContext(SuperExpression expression) {
+    for (AstNode node = expression; node != null; node = node.parent) {
+      if (node is CompilationUnit) {
         return false;
       }
-      if (n is ConstructorDeclaration) {
-        return n.factoryKeyword == null;
+      if (node is ConstructorDeclaration) {
+        return node.factoryKeyword == null;
       }
-      if (n is ConstructorFieldInitializer) {
+      if (node is ConstructorFieldInitializer) {
         return false;
       }
-      if (n is MethodDeclaration) {
-        return !n.isStatic;
+      if (node is MethodDeclaration) {
+        return !node.isStatic;
       }
     }
     return false;
   }
 
   /**
-   * Return a method representing the merge of the given elements. The type of the merged element is
-   * the component-wise union of the types of the given elements. If not all input elements have the
-   * same shape then [null] is returned.
-   *
-   * @param elements the `ExecutableElement`s to merge
-   * @return an `ExecutableElement` representing the merge of `elements`
+   * Return a method representing the merge of the given [elements]. The type of
+   * the merged element is the component-wise union of the types of the given
+   * elements. If not all input elements have the same shape then `null` is
+   * returned.
    */
   static ExecutableElement _maybeMergeExecutableElements(
       Set<ExecutableElement> elements) {
     List<ExecutableElement> elementArrayToMerge = new List.from(elements);
     if (elementArrayToMerge.length == 0) {
       return null;
     } else if (elementArrayToMerge.length == 1) {
       // If all methods are equal, don't bother building a new one.
       return elementArrayToMerge[0];
     } else {
       return _computeMergedExecutableElement(elementArrayToMerge);
     }
   }
 }
 
 /**
- * A `SyntheticIdentifier` is an identifier that can be used to look up names in
- * the lexical scope when there is no identifier in the AST structure. There is
- * no identifier in the AST when the parser could not distinguish between a
- * method invocation and an invocation of a top-level function imported with a
- * prefix.
+ * An identifier that can be used to look up names in the lexical scope when
+ * there is no identifier in the AST structure. There is no identifier in the
+ * AST when the parser could not distinguish between a method invocation and an
+ * invocation of a top-level function imported with a prefix.
  */
 class SyntheticIdentifier extends Identifier {
   /**
    * The name of the synthetic identifier.
    */
   final String name;
 
   /**
    * The identifier to be highlighted in case of an error
    */
@@ skipping 36 matching lines @@
 
   @override
   Element get staticElement => null;
 
   @override
   accept(AstVisitor visitor) => null;
 
   @override
   void visitChildren(AstVisitor visitor) {}
 }