Clean up comments in constants.dart

pkg/analyzer/lib/src/generated/constant.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.constant;
 
 import 'dart:collection';
 
 import 'package:analyzer/src/generated/utilities_general.dart';
 
 import 'ast.dart';
 import 'element.dart';
 import 'engine.dart' show AnalysisEngine, RecordingErrorListener;
 import 'error.dart';
 import 'java_core.dart';
 import 'resolver.dart' show TypeProvider;
 import 'scanner.dart' show Token, TokenType;
 import 'source.dart' show Source;
 import 'utilities_collection.dart';
 import 'utilities_dart.dart' show ParameterKind;
 
 /**
- * Instances of the class `BoolState` represent the state of an object representing a boolean
- * value.
+ * The state of an object representing a boolean value.
  */
 class BoolState extends InstanceState {
   /**
    * An instance representing the boolean value 'false'.
    */
   static BoolState FALSE_STATE = new BoolState(false);
 
   /**
    * An instance representing the boolean value 'true'.
    */
   static BoolState TRUE_STATE = new BoolState(true);
 
   /**
    * A state that can be used to represent a boolean whose value is not known.
    */
   static BoolState UNKNOWN_VALUE = new BoolState(null);
 
   /**
    * The value of this instance.
    */
   final bool value;
 
   /**
-   * Initialize a newly created state to represent the given value.
-   *
-   * @param value the value of this instance
+   * Initialize a newly created state to represent the given [value].
    */
   BoolState(this.value);
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => value == null ? 0 : (value ? 2 : 3);
 
-  /**
-   * Return `true` if this object represents an object whose type is 'bool'.
-   *
-   * @return `true` if this object represents a boolean value
-   */
   @override
   bool get isBool => true;
 
   @override
   bool get isBoolNumStringOrNull => true;
 
   @override
   bool get isUnknown => value == null;
 
   @override
@@ skipping 60 matching lines @@
     if (value == null) {
       return UNKNOWN_VALUE;
     }
     return value ? TRUE_STATE : rightOperand.convertToBool();
   }
 
   @override
   String toString() => value == null ? "-unknown-" : (value ? "true" : "false");
 
   /**
-   * Return the boolean state representing the given boolean value.
-   *
-   * @param value the value to be represented
-   * @return the boolean state representing the given boolean value
+   * Return the boolean state representing the given boolean [value].
    */
   static BoolState from(bool value) =>
       value ? BoolState.TRUE_STATE : BoolState.FALSE_STATE;
 }
 
 /**
- * Instances of the class `ConstantEvaluator` evaluate constant expressions to produce their
- * compile-time value. According to the Dart Language Specification: <blockquote> A constant
- * expression is one of the following:
+ * Instances of the class `ConstantEvaluator` evaluate constant expressions to
+ * produce their compile-time value. According to the Dart Language
+ * Specification:
+ * <blockquote>
+ * A constant expression is one of the following:
  * * A literal number.
  * * A literal boolean.
- * * A literal string where any interpolated expression is a compile-time constant that evaluates
- * to a numeric, string or boolean value or to <b>null</b>.
+ * * A literal string where any interpolated expression is a compile-time
+ *   constant that evaluates to a numeric, string or boolean value or to
+ *   <b>null</b>.
  * * A literal symbol.
  * * <b>null</b>.
  * * A qualified reference to a static constant variable.
- * * An identifier expression that denotes a constant variable, class or type alias.
+ * * An identifier expression that denotes a constant variable, class or type
+ *   alias.
  * * A constant constructor invocation.
  * * A constant list literal.
  * * A constant map literal.
- * * A simple or qualified identifier denoting a top-level function or a static method.
- * * A parenthesized expression <i>(e)</i> where <i>e</i> is a constant expression.
- * * An expression of the form <i>identical(e<sub>1</sub>, e<sub>2</sub>)</i> where
- * <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions and <i>identical()</i> is
- * statically bound to the predefined dart function <i>identical()</i> discussed above.
- * * An expression of one of the forms <i>e<sub>1</sub> == e<sub>2</sub></i> or <i>e<sub>1</sub>
- * != e<sub>2</sub></i> where <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions
- * that evaluate to a numeric, string or boolean value.
- * * An expression of one of the forms <i>!e</i>, <i>e<sub>1</sub> &amp;&amp; e<sub>2</sub></i> or
- * <i>e<sub>1</sub> || e<sub>2</sub></i>, where <i>e</i>, <i>e1</sub></i> and <i>e2</sub></i> are
- * constant expressions that evaluate to a boolean value.
- * * An expression of one of the forms <i>~e</i>, <i>e<sub>1</sub> ^ e<sub>2</sub></i>,
- * <i>e<sub>1</sub> &amp; e<sub>2</sub></i>, <i>e<sub>1</sub> | e<sub>2</sub></i>, <i>e<sub>1</sub>
- * &gt;&gt; e<sub>2</sub></i> or <i>e<sub>1</sub> &lt;&lt; e<sub>2</sub></i>, where <i>e</i>,
- * <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions that evaluate to an
- * integer value or to <b>null</b>.
- * * An expression of one of the forms <i>-e</i>, <i>e<sub>1</sub> + e<sub>2</sub></i>,
- * <i>e<sub>1</sub> -e<sub>2</sub></i>, <i>e<sub>1</sub> * e<sub>2</sub></i>, <i>e<sub>1</sub> /
- * e<sub>2</sub></i>, <i>e<sub>1</sub> ~/ e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;
- * e<sub>2</sub></i>, <i>e<sub>1</sub> &lt; e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;=
- * e<sub>2</sub></i>, <i>e<sub>1</sub> &lt;= e<sub>2</sub></i> or <i>e<sub>1</sub> %
- * e<sub>2</sub></i>, where <i>e</i>, <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
- * expressions that evaluate to a numeric value or to <b>null</b>.
- * * An expression of the form <i>e<sub>1</sub> ? e<sub>2</sub> : e<sub>3</sub></i> where
- * <i>e<sub>1</sub></i>, <i>e<sub>2</sub></i> and <i>e<sub>3</sub></i> are constant expressions, and
- * <i>e<sub>1</sub></i> evaluates to a boolean value.
+ * * A simple or qualified identifier denoting a top-level function or a static
+ *   method.
+ * * A parenthesized expression <i>(e)</i> where <i>e</i> is a constant
+ *   expression.
+ * * An expression of the form <i>identical(e<sub>1</sub>, e<sub>2</sub>)</i>
+ *   where <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
+ *   expressions and <i>identical()</i> is statically bound to the predefined
+ *   dart function <i>identical()</i> discussed above.
+ * * An expression of one of the forms <i>e<sub>1</sub> == e<sub>2</sub></i> or
+ *   <i>e<sub>1</sub> != e<sub>2</sub></i> where <i>e<sub>1</sub></i> and
+ *   <i>e<sub>2</sub></i> are constant expressions that evaluate to a numeric,
+ *   string or boolean value.
+ * * An expression of one of the forms <i>!e</i>, <i>e<sub>1</sub> &amp;&amp;
+ *   e<sub>2</sub></i> or <i>e<sub>1</sub> || e<sub>2</sub></i>, where <i>e</i>,
+ *   <i>e1</sub></i> and <i>e2</sub></i> are constant expressions that evaluate
+ *   to a boolean value.
+ * * An expression of one of the forms <i>~e</i>, <i>e<sub>1</sub> ^
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> &amp; e<sub>2</sub></i>,
+ *   <i>e<sub>1</sub> | e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;&gt;
+ *   e<sub>2</sub></i> or <i>e<sub>1</sub> &lt;&lt; e<sub>2</sub></i>, where
+ *   <i>e</i>, <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
+ *   expressions that evaluate to an integer value or to <b>null</b>.
+ * * An expression of one of the forms <i>-e</i>, <i>e<sub>1</sub> +
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> -e<sub>2</sub></i>, <i>e<sub>1</sub> *
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> / e<sub>2</sub></i>, <i>e<sub>1</sub>
+ *   ~/ e<sub>2</sub></i>, <i>e<sub>1</sub> &gt; e<sub>2</sub></i>,
+ *   <i>e<sub>1</sub> &lt; e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;=
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> &lt;= e<sub>2</sub></i> or
+ *   <i>e<sub>1</sub> % e<sub>2</sub></i>, where <i>e</i>, <i>e<sub>1</sub></i>
+ *   and <i>e<sub>2</sub></i> are constant expressions that evaluate to a
+ *   numeric value or to <b>null</b>.
+ * * An expression of the form <i>e<sub>1</sub> ? e<sub>2</sub> :
+ *   e<sub>3</sub></i> where <i>e<sub>1</sub></i>, <i>e<sub>2</sub></i> and
+ *   <i>e<sub>3</sub></i> are constant expressions, and <i>e<sub>1</sub></i>
+ *   evaluates to a boolean value.
  * </blockquote>
  */
 class ConstantEvaluator {
   /**
    * The source containing the expression(s) that will be evaluated.
    */
   final Source _source;
 
   /**
    * The type provider used to access the known types.
    */
   final TypeProvider _typeProvider;
 
   /**
-   * Initialize a newly created evaluator to evaluate expressions in the given source.
-   *
-   * @param source the source containing the expression(s) that will be evaluated
-   * @param typeProvider the type provider used to access known types
+   * Initialize a newly created evaluator to evaluate expressions in the given
+   * [source]. The [typeProvider] is the type provider used to access known
+   * types.
    */
   ConstantEvaluator(this._source, this._typeProvider);
 
   EvaluationResult evaluate(Expression expression) {
     RecordingErrorListener errorListener = new RecordingErrorListener();
     ErrorReporter errorReporter = new ErrorReporter(errorListener, _source);
     DartObjectImpl result = expression
         .accept(new ConstantVisitor.con1(_typeProvider, errorReporter));
     if (result != null) {
       return EvaluationResult.forValue(result);
     }
     return EvaluationResult.forErrors(errorListener.errors);
   }
 }
 
 /**
- * Instances of the class `ConstantFinder` are used to traverse the AST
- * structures of all of the compilation units being resolved and build tables
- * of the constant variables, constant constructors, constant constructor
- * invocations, and annotations found in those compilation units.
+ * A visitor used to traverse the AST structures of all of the compilation units
+ * being resolved and build tables of the constant variables, constant
+ * constructors, constant constructor invocations, and annotations found in
+ * those compilation units.
  */
 class ConstantFinder extends RecursiveAstVisitor<Object> {
   /**
-   * A table mapping constant variable elements to the declarations of those variables.
+   * A table mapping constant variable elements to the declarations of those
+   * variables.
    */
   final HashMap<VariableElement, VariableDeclaration> variableMap =
       new HashMap<VariableElement, VariableDeclaration>();
 
   /**
-   * A table mapping constant constructors to the declarations of those constructors.
+   * A table mapping constant constructors to the declarations of those
+   * constructors.
    */
   final HashMap<ConstructorElement, ConstructorDeclaration> constructorMap =
       new HashMap<ConstructorElement, ConstructorDeclaration>();
 
   /**
    * A collection of constant constructor invocations.
    */
   final List<InstanceCreationExpression> constructorInvocations =
       new List<InstanceCreationExpression>();
 
@@ skipping 38 matching lines @@
       VariableElement element = node.element;
       if (element != null) {
         variableMap[element] = node;
       }
     }
     return null;
   }
 }
 
 /**
- * Instances of the class `ConstantValueComputer` compute the values of constant variables and
- * constant constructor invocations in one or more compilation units. The expected usage pattern is
- * for the compilation units to be added to this computer using the method
- * [add] and then for the method [computeValues] to be invoked
- * exactly once. Any use of an instance after invoking the method [computeValues] will
+ * An object used to compute the values of constant variables and constant
+ * constructor invocations in one or more compilation units. The expected usage
+ * pattern is for the compilation units to be added to this computer using the
+ * method [add] and then for the method [computeValues] to be invoked exactly
+ * once. Any use of an instance after invoking the method [computeValues] will
  * result in unpredictable behavior.
  */
 class ConstantValueComputer {
   /**
    * Parameter to "fromEnvironment" methods that denotes the default value.
    */
   static String _DEFAULT_VALUE_PARAM = "defaultValue";
 
   /**
-   * Source of RegExp matching declarable operator names. From sdk/lib/internal/symbol.dart.
+   * Source of RegExp matching declarable operator names.
+   * From sdk/lib/internal/symbol.dart.
    */
   static String _OPERATOR_RE =
       "(?:[\\-+*/%&|^]|\\[\\]=?|==|~/?|<[<=]?|>[>=]?|unary-)";
 
   /**
-   * Source of RegExp matching any public identifier. From sdk/lib/internal/symbol.dart.
+   * Source of RegExp matching any public identifier.
+   * From sdk/lib/internal/symbol.dart.
    */
   static String _PUBLIC_IDENTIFIER_RE =
       "(?!${ConstantValueComputer._RESERVED_WORD_RE}\\b(?!\\\$))[a-zA-Z\$][\\w\$]*";
 
   /**
-   * Source of RegExp matching Dart reserved words. From sdk/lib/internal/symbol.dart.
+   * Source of RegExp matching Dart reserved words.
+   * From sdk/lib/internal/symbol.dart.
    */
   static String _RESERVED_WORD_RE =
       "(?:assert|break|c(?:a(?:se|tch)|lass|on(?:st|tinue))|d(?:efault|o)|e(?:lse|num|xtends)|f(?:alse|inal(?:ly)?|or)|i[fns]|n(?:ew|ull)|ret(?:hrow|urn)|s(?:uper|witch)|t(?:h(?:is|row)|r(?:ue|y))|v(?:ar|oid)|w(?:hile|ith))";
 
   /**
-   * RegExp that validates a non-empty non-private symbol. From sdk/lib/internal/symbol.dart.
+   * RegExp that validates a non-empty non-private symbol.
+   * From sdk/lib/internal/symbol.dart.
    */
   static RegExp _PUBLIC_SYMBOL_PATTERN = new RegExp(
       "^(?:${ConstantValueComputer._OPERATOR_RE}\$|$_PUBLIC_IDENTIFIER_RE(?:=?\$|[.](?!\$)))+?\$");
 
   /**
    * The type provider used to access the known types.
    */
   TypeProvider typeProvider;
 
   /**
-   * The object used to find constant variables and constant constructor invocations in the
-   * compilation units that were added.
+   * The object used to find constant variables and constant constructor
+   * invocations in the compilation units that were added.
    */
   ConstantFinder _constantFinder = new ConstantFinder();
 
   /**
-   * A graph in which the nodes are the constants, and the edges are from each constant to the other
-   * constants that are referenced by it.
+   * A graph in which the nodes are the constants, and the edges are from each
+   * constant to the other constants that are referenced by it.
    */
   DirectedGraph<AstNode> referenceGraph = new DirectedGraph<AstNode>();
 
   /**
    * A table mapping constant variables to the declarations of those variables.
    */
   HashMap<VariableElement, VariableDeclaration> _variableDeclarationMap;
 
   /**
-   * A table mapping constant constructors to the declarations of those constructors.
+   * A table mapping constant constructors to the declarations of those
+   * constructors.
    */
   HashMap<ConstructorElement, ConstructorDeclaration> constructorDeclarationMap;
 
   /**
    * A collection of constant constructor invocations.
    */
   List<InstanceCreationExpression> _constructorInvocations;
 
   /**
    * A collection of annotations.
    */
   List<Annotation> _annotations;
 
   /**
    * The set of variables declared on the command line using '-D'.
    */
   final DeclaredVariables _declaredVariables;
 
   /**
-   * Initialize a newly created constant value computer.
-   *
-   * @param typeProvider the type provider used to access known types
-   * @param declaredVariables the set of variables declared on the command line using '-D'
+   * Initialize a newly created constant value computer. The [typeProvider] is
+   * the type provider used to access known types. The [declaredVariables] is
+   * the set of variables declared on the command line using '-D'.
    */
   ConstantValueComputer(TypeProvider typeProvider, this._declaredVariables) {
     this.typeProvider = typeProvider;
   }
 
   /**
-   * Add the constants in the given compilation unit to the list of constants whose value needs to
-   * be computed.
-   *
-   * @param unit the compilation unit defining the constants to be added
+   * Add the constants in the given compilation [unit] to the list of constants
+   * whose value needs to be computed.
    */
   void add(CompilationUnit unit) {
     unit.accept(_constantFinder);
   }
 
   /**
-   * This method is called just before computing the constant value associated with an AST node.
-   * Unit tests will override this method to introduce additional error checking.
+   * This method is called just before computing the constant value associated
+   * with [constNode]. Unit tests will override this method to introduce
+   * additional error checking.
    */
   void beforeComputeValue(AstNode constNode) {}
 
   /**
-   * This method is called just before getting the constant initializers associated with a
-   * constructor AST node. Unit tests will override this method to introduce additional error
-   * checking.
+   * This method is called just before getting the constant initializers
+   * associated with the [constructor]. Unit tests will override this method to
+   * introduce additional error checking.
    */
   void beforeGetConstantInitializers(ConstructorElement constructor) {}
 
   /**
-   * This method is called just before getting a parameter's default value. Unit tests will override
-   * this method to introduce additional error checking.
+   * This method is called just before getting a parameter's default value. Unit
+   * tests will override this method to introduce additional error checking.
    */
   void beforeGetParameterDefault(ParameterElement parameter) {}
 
   /**
-   * Compute values for all of the constants in the compilation units that were added.
+   * Compute values for all of the constants in the compilation units that were
+   * added.
    */
   void computeValues() {
     _variableDeclarationMap = _constantFinder.variableMap;
     constructorDeclarationMap = _constantFinder.constructorMap;
     _constructorInvocations = _constantFinder.constructorInvocations;
     _annotations = _constantFinder.annotations;
     _variableDeclarationMap.values.forEach((VariableDeclaration declaration) {
       ReferenceFinder referenceFinder = new ReferenceFinder(declaration,
           referenceGraph, _variableDeclarationMap, constructorDeclarationMap);
       referenceGraph.addNode(declaration);
@@ skipping 72 matching lines @@
     }
     // Since no constant can depend on an annotation, we don't waste time
     // including them in the topological sort.  We just process all the
     // annotations after all other constants are finished.
     for (Annotation annotation in _annotations) {
       _computeValueFor(annotation);
     }
   }
 
   /**
-   * Create the ConstantVisitor used to evaluate constants. Unit tests will override this method to
-   * introduce additional error checking.
+   * Create the ConstantVisitor used to evaluate constants. Unit tests will
+   * override this method to introduce additional error checking.
    */
   ConstantVisitor createConstantVisitor(ErrorReporter errorReporter) =>
       new ConstantVisitor.con1(typeProvider, errorReporter);
 
   ConstructorDeclaration findConstructorDeclaration(
           ConstructorElement constructor) =>
       constructorDeclarationMap[_getConstructorBase(constructor)];
 
   /**
-   * Check that the arguments to a call to fromEnvironment() are correct.
-   *
-   * @param arguments the AST nodes of the arguments.
-   * @param argumentValues the values of the unnamed arguments.
-   * @param namedArgumentValues the values of the named arguments.
-   * @param expectedDefaultValueType the allowed type of the "defaultValue" parameter (if present).
-   *          Note: "defaultValue" is always allowed to be null.
-   * @return true if the arguments are correct, false if there is an error.
+   * Check that the arguments to a call to fromEnvironment() are correct. The
+   * [arguments] are the AST nodes of the arguments. The [argumentValues] are
+   * the values of the unnamed arguments. The [namedArgumentValues] are the
+   * values of the named arguments. The [expectedDefaultValueType] is the
+   * allowed type of the "defaultValue" parameter (if present). Note:
+   * "defaultValue" is always allowed to be null. Return `true` if the arguments
+   * are correct, `false` if there is an error.
    */
   bool _checkFromEnvironmentArguments(NodeList<Expression> arguments,
       List<DartObjectImpl> argumentValues,
       HashMap<String, DartObjectImpl> namedArgumentValues,
       InterfaceType expectedDefaultValueType) {
     int argumentCount = arguments.length;
     if (argumentCount < 1 || argumentCount > 2) {
       return false;
     }
     if (arguments[0] is NamedExpression) {
@@ skipping 14 matching lines @@
           namedArgumentValues[_DEFAULT_VALUE_PARAM].type;
       if (!(identical(defaultValueType, expectedDefaultValueType) ||
           identical(defaultValueType, typeProvider.nullType))) {
         return false;
       }
     }
     return true;
   }
 
   /**
-   * Check that the arguments to a call to Symbol() are correct.
-   *
-   * @param arguments the AST nodes of the arguments.
-   * @param argumentValues the values of the unnamed arguments.
-   * @param namedArgumentValues the values of the named arguments.
-   * @return true if the arguments are correct, false if there is an error.
+   * Check that the arguments to a call to Symbol() are correct. The [arguments]
+   * are the AST nodes of the arguments. The [argumentValues] are the values of
+   * the unnamed arguments. The [namedArgumentValues] are the values of the
+   * named arguments. Return `true` if the arguments are correct, `false` if
+   * there is an error.
    */
   bool _checkSymbolArguments(NodeList<Expression> arguments,
       List<DartObjectImpl> argumentValues,
       HashMap<String, DartObjectImpl> namedArgumentValues) {
     if (arguments.length != 1) {
       return false;
     }
     if (arguments[0] is NamedExpression) {
       return false;
     }
     if (!identical(argumentValues[0].type, typeProvider.stringType)) {
       return false;
     }
     String name = argumentValues[0].stringValue;
     return isValidPublicSymbol(name);
   }
 
   /**
-   * Compute a value for the given constant.
-   *
-   * @param constNode the constant for which a value is to be computed
+   * Compute a value for the given [constNode].
    */
   void _computeValueFor(AstNode constNode) {
     beforeComputeValue(constNode);
     if (constNode is VariableDeclaration) {
       VariableDeclaration declaration = constNode;
       VariableElement element = declaration.element;
       RecordingErrorListener errorListener = new RecordingErrorListener();
       ErrorReporter errorReporter =
           new ErrorReporter(errorListener, element.source);
       DartObjectImpl dartObject =
@@ skipping 88 matching lines @@
       }
     } else {
       // Should not happen.
       AnalysisEngine.instance.logger.logError(
           "Constant value computer trying to compute the value of a node which is not a VariableDeclaration, InstanceCreationExpression, FormalParameter, or ConstructorDeclaration");
       return;
     }
   }
 
   /**
-   * Evaluate a call to fromEnvironment() on the bool, int, or String class.
-   *
-   * @param environmentValue Value fetched from the environment
-   * @param builtInDefaultValue Value that should be used as the default if no "defaultValue"
-   *          argument appears in [namedArgumentValues].
-   * @param namedArgumentValues Named parameters passed to fromEnvironment()
-   * @return A [DartObjectImpl] object corresponding to the evaluated result
+   * Evaluate a call to fromEnvironment() on the bool, int, or String class. The
+   * [environmentValue] is the value fetched from the environment. The
+   * [builtInDefaultValue] is the value that should be used as the default if no
+   * "defaultValue" argument appears in [namedArgumentValues]. The
+   * [namedArgumentValues] are the values of the named parameters passed to
+   * fromEnvironment(). Return a [DartObjectImpl] object corresponding to the
+   * evaluated result.
    */
   DartObjectImpl _computeValueFromEnvironment(DartObject environmentValue,
       DartObjectImpl builtInDefaultValue,
       HashMap<String, DartObjectImpl> namedArgumentValues) {
     DartObjectImpl value = environmentValue as DartObjectImpl;
     if (value.isUnknown || value.isNull) {
       // The name either doesn't exist in the environment or we couldn't parse
       // the corresponding value.
       // If the code supplied an explicit default, use it.
       if (namedArgumentValues.containsKey(_DEFAULT_VALUE_PARAM)) {
@@ skipping 243 matching lines @@
     if (superConstructor != null && superConstructor.isConst) {
       DartObjectImpl evaluationResult = _evaluateConstructorCall(node,
           superArguments, superConstructor, initializerVisitor, errorReporter);
       if (evaluationResult != null) {
         fieldMap[GenericState.SUPERCLASS_FIELD] = evaluationResult;
       }
     }
   }
 
   /**
-   * Attempt to follow the chain of factory redirections until a constructor is reached which is not
-   * a const factory constructor.
-   *
-   * @return the constant constructor which terminates the chain of factory redirections, if the
-   *         chain terminates. If there is a problem (e.g. a redirection can't be found, or a cycle
-   *         is encountered), the chain will be followed as far as possible and then a const factory
-   *         constructor will be returned.
+   * Attempt to follow the chain of factory redirections until a constructor is
+   * reached which is not a const factory constructor. Return the constant
+   * constructor which terminates the chain of factory redirections, if the
+   * chain terminates. If there is a problem (e.g. a redirection can't be found,
+   * or a cycle is encountered), the chain will be followed as far as possible
+   * and then a const factory constructor will be returned.
    */
   ConstructorElement _followConstantRedirectionChain(
       ConstructorElement constructor) {
     HashSet<ConstructorElement> constructorsVisited =
         new HashSet<ConstructorElement>();
     while (constructor.isFactory) {
       if (identical(
           constructor.enclosingElement.type, typeProvider.symbolType)) {
         // The dart:core.Symbol has a const factory constructor that redirects
         // to dart:_internal.Symbol.  That in turn redirects to an external
@@ skipping 20 matching lines @@
         // and is checked elsewhere--see
         // [ErrorVerifier.checkForRecursiveFactoryRedirect()]).
         break;
       }
       constructor = redirectedConstructor;
     }
     return constructor;
   }
 
   /**
-   * Generate an error indicating that the given constant is not a valid compile-time constant
-   * because it references at least one of the constants in the given cycle, each of which directly
-   * or indirectly references the constant.
-   *
-   * @param constantsInCycle the constants in the cycle that includes the given constant
-   * @param constant the constant that is not a valid compile-time constant
+   * Generate an error indicating that the given [constant] is not a valid
+   * compile-time constant because it references at least one of the constants
+   * in the given [cycle], each of which directly or indirectly references the
+   * constant.
    */
-  void _generateCycleError(List<AstNode> constantsInCycle, AstNode constant) {
+  void _generateCycleError(List<AstNode> cycle, AstNode constant) {
     // TODO(brianwilkerson) Implement this.
   }
 
   ConstructorElement _getConstructorBase(ConstructorElement constructor) {
     while (constructor is ConstructorMember) {
       constructor = (constructor as ConstructorMember).baseElement;
     }
     return constructor;
   }
 
   /**
-   * Check if the object [obj] matches the type [type] according
-   * to runtime type checking rules.
+   * Check if the object [obj] matches the type [type] according to runtime type
+   * checking rules.
    */
   bool _runtimeTypeMatch(DartObjectImpl obj, DartType type) {
     if (obj.isNull) {
       return true;
     }
     if (type.isUndefined) {
       return false;
     }
     return obj.type.isSubtypeOf(type);
   }
 
   /**
-   * Determine whether the given string is a valid name for a public symbol (i.e. whether it is
-   * allowed for a call to the Symbol constructor).
+   * Determine whether the given string is a valid name for a public symbol
+   * (i.e. whether it is allowed for a call to the Symbol constructor).
    */
   static bool isValidPublicSymbol(String name) => name.isEmpty ||
       name == "void" ||
       new JavaPatternMatcher(_PUBLIC_SYMBOL_PATTERN, name).matches();
 }
 
 /**
- * A `ConstantValueComputer_InitializerCloner` is an [AstCloner] that copies the
- * necessary information from the AST to allow const constructor initializers to
- * be evaluated.
+ * An [AstCloner] that copies the necessary information from the AST to allow
+ * const constructor initializers to be evaluated.
  */
 class ConstantValueComputer_InitializerCloner extends AstCloner {
   // TODO(brianwilkerson) Investigate replacing uses of this class with uses of
   // AstCloner and ResolutionCopier.
 
   ConstantValueComputer_InitializerCloner() : super(true);
 
   @override
   InstanceCreationExpression visitInstanceCreationExpression(
       InstanceCreationExpression node) {
@@ skipping 23 matching lines @@
   SuperConstructorInvocation visitSuperConstructorInvocation(
       SuperConstructorInvocation node) {
     SuperConstructorInvocation invocation =
         super.visitSuperConstructorInvocation(node);
     invocation.staticElement = node.staticElement;
     return invocation;
   }
 }
 
 /**
- * Instances of the class `ConstantVisitor` evaluate constant expressions to produce their
- * compile-time value. According to the Dart Language Specification: <blockquote> A constant
+ * A visitor used to evaluate constant expressions to produce their compile-time
+ * value. According to the Dart Language Specification: <blockquote> A constant
  * expression is one of the following:
+ *
  * * A literal number.
  * * A literal boolean.
- * * A literal string where any interpolated expression is a compile-time constant that evaluates
- * to a numeric, string or boolean value or to <b>null</b>.
+ * * A literal string where any interpolated expression is a compile-time
+ *   constant that evaluates to a numeric, string or boolean value or to
+ *   <b>null</b>.
  * * A literal symbol.
  * * <b>null</b>.
  * * A qualified reference to a static constant variable.
- * * An identifier expression that denotes a constant variable, class or type alias.
+ * * An identifier expression that denotes a constant variable, class or type
+ *   alias.
  * * A constant constructor invocation.
  * * A constant list literal.
  * * A constant map literal.
- * * A simple or qualified identifier denoting a top-level function or a static method.
- * * A parenthesized expression <i>(e)</i> where <i>e</i> is a constant expression.
- * * An expression of the form <i>identical(e<sub>1</sub>, e<sub>2</sub>)</i> where
- * <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions and <i>identical()</i> is
- * statically bound to the predefined dart function <i>identical()</i> discussed above.
- * * An expression of one of the forms <i>e<sub>1</sub> == e<sub>2</sub></i> or <i>e<sub>1</sub>
- * != e<sub>2</sub></i> where <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions
- * that evaluate to a numeric, string or boolean value.
- * * An expression of one of the forms <i>!e</i>, <i>e<sub>1</sub> &amp;&amp; e<sub>2</sub></i> or
- * <i>e<sub>1</sub> || e<sub>2</sub></i>, where <i>e</i>, <i>e1</sub></i> and <i>e2</sub></i> are
- * constant expressions that evaluate to a boolean value.
- * * An expression of one of the forms <i>~e</i>, <i>e<sub>1</sub> ^ e<sub>2</sub></i>,
- * <i>e<sub>1</sub> &amp; e<sub>2</sub></i>, <i>e<sub>1</sub> | e<sub>2</sub></i>, <i>e<sub>1</sub>
- * &gt;&gt; e<sub>2</sub></i> or <i>e<sub>1</sub> &lt;&lt; e<sub>2</sub></i>, where <i>e</i>,
- * <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant expressions that evaluate to an
- * integer value or to <b>null</b>.
- * * An expression of one of the forms <i>-e</i>, <i>e<sub>1</sub> + e<sub>2</sub></i>,
- * <i>e<sub>1</sub> - e<sub>2</sub></i>, <i>e<sub>1</sub> * e<sub>2</sub></i>, <i>e<sub>1</sub> /
- * e<sub>2</sub></i>, <i>e<sub>1</sub> ~/ e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;
- * e<sub>2</sub></i>, <i>e<sub>1</sub> &lt; e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;=
- * e<sub>2</sub></i>, <i>e<sub>1</sub> &lt;= e<sub>2</sub></i> or <i>e<sub>1</sub> %
- * e<sub>2</sub></i>, where <i>e</i>, <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
- * expressions that evaluate to a numeric value or to <b>null</b>.
- * * An expression of the form <i>e<sub>1</sub> ? e<sub>2</sub> : e<sub>3</sub></i> where
- * <i>e<sub>1</sub></i>, <i>e<sub>2</sub></i> and <i>e<sub>3</sub></i> are constant expressions, and
- * <i>e<sub>1</sub></i> evaluates to a boolean value.
+ * * A simple or qualified identifier denoting a top-level function or a static
+ *   method.
+ * * A parenthesized expression <i>(e)</i> where <i>e</i> is a constant
+ *   expression.
+ * * An expression of the form <i>identical(e<sub>1</sub>, e<sub>2</sub>)</i>
+ *   where <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
+ *   expressions and <i>identical()</i> is statically bound to the predefined
+ *   dart function <i>identical()</i> discussed above.
+ * * An expression of one of the forms <i>e<sub>1</sub> == e<sub>2</sub></i> or
+ *   <i>e<sub>1</sub> != e<sub>2</sub></i> where <i>e<sub>1</sub></i> and
+ *   <i>e<sub>2</sub></i> are constant expressions that evaluate to a numeric,
+ *   string or boolean value.
+ * * An expression of one of the forms <i>!e</i>, <i>e<sub>1</sub> &amp;&amp;
+ *   e<sub>2</sub></i> or <i>e<sub>1</sub> || e<sub>2</sub></i>, where <i>e</i>,
+ *   <i>e1</sub></i> and <i>e2</sub></i> are constant expressions that evaluate
+ *   to a boolean value.
+ * * An expression of one of the forms <i>~e</i>, <i>e<sub>1</sub> ^
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> &amp; e<sub>2</sub></i>,
+ *   <i>e<sub>1</sub> | e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;&gt;
+ *   e<sub>2</sub></i> or <i>e<sub>1</sub> &lt;&lt; e<sub>2</sub></i>, where
+ *   <i>e</i>, <i>e<sub>1</sub></i> and <i>e<sub>2</sub></i> are constant
+ *   expressions that evaluate to an integer value or to <b>null</b>.
+ * * An expression of one of the forms <i>-e</i>, <i>e<sub>1</sub> +
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> - e<sub>2</sub></i>, <i>e<sub>1</sub> *
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> / e<sub>2</sub></i>, <i>e<sub>1</sub>
+ *   ~/ e<sub>2</sub></i>, <i>e<sub>1</sub> &gt; e<sub>2</sub></i>,
+ *   <i>e<sub>1</sub> &lt; e<sub>2</sub></i>, <i>e<sub>1</sub> &gt;=
+ *   e<sub>2</sub></i>, <i>e<sub>1</sub> &lt;= e<sub>2</sub></i> or
+ *   <i>e<sub>1</sub> % e<sub>2</sub></i>, where <i>e</i>, <i>e<sub>1</sub></i>
+ *   and <i>e<sub>2</sub></i> are constant expressions that evaluate to a
+ *   numeric value or to <b>null</b>.
+ * * An expression of the form <i>e<sub>1</sub> ? e<sub>2</sub> :
+ *   e<sub>3</sub></i> where <i>e<sub>1</sub></i>, <i>e<sub>2</sub></i> and
+ *   <i>e<sub>3</sub></i> are constant expressions, and <i>e<sub>1</sub></i>
+ *   evaluates to a boolean value.
  * </blockquote>
  */
 class ConstantVisitor extends UnifyingAstVisitor<DartObjectImpl> {
   /**
    * The type provider used to access the known types.
    */
   final TypeProvider _typeProvider;
 
   /**
    * An shared object representing the value 'null'.
    */
   DartObjectImpl _nullObject;
 
   HashMap<String, DartObjectImpl> _lexicalEnvironment;
 
   /**
-   * Error reporter that we use to report errors accumulated while computing the constant.
+   * Error reporter that we use to report errors accumulated while computing the
+   * constant.
    */
   final ErrorReporter _errorReporter;
 
   /**
    * Helper class used to compute constant values.
    */
   DartObjectComputer _dartObjectComputer;
 
   /**
-   * Initialize a newly created constant visitor.
-   *
-   * @param typeProvider the type provider used to access known types
-   * @param lexicalEnvironment values which should override simpleIdentifiers, or null if no
-   *          overriding is necessary.
+   * Initialize a newly created constant visitor. The [_typeProvider] is the
+   * type provider used to access known types. The [_errorReporter] is used to
+   * report errors found during evaluation.
    */
   ConstantVisitor.con1(this._typeProvider, this._errorReporter) {
     this._lexicalEnvironment = null;
     this._dartObjectComputer =
         new DartObjectComputer(_errorReporter, _typeProvider);
   }
 
   /**
-   * Initialize a newly created constant visitor.
-   *
-   * @param typeProvider the type provider used to access known types
-   * @param lexicalEnvironment values which should override simpleIdentifiers, or null if no
-   *          overriding is necessary.
+   * Initialize a newly created constant visitor. The [_typeProvider] is the
+   * type provider used to access known types. The [lexicalEnvironment] is a map
+   * containing values which should override identifiers, or `null` if no
+   * overriding is necessary. The [_errorReporter] is used to report errors
+   * found during evaluation.
    */
   ConstantVisitor.con2(this._typeProvider,
       HashMap<String, DartObjectImpl> lexicalEnvironment, this._errorReporter) {
     this._lexicalEnvironment = lexicalEnvironment;
     this._dartObjectComputer =
         new DartObjectComputer(_errorReporter, _typeProvider);
   }
 
   /**
    * Return an object representing the value 'null'.
-   *
-   * @return an object representing the value 'null'
    */
   DartObjectImpl get null2 {
     if (_nullObject == null) {
       _nullObject =
           new DartObjectImpl(_typeProvider.nullType, NullState.NULL_STATE);
     }
     return _nullObject;
   }
 
   /**
-   * This method is called just before retrieving an evaluation result from an AST node. Unit tests
-   * will override it to introduce additional error checking.
+   * This method is called just before retrieving an evaluation result from an
+   * AST node. Unit tests will override it to introduce additional error
+   * checking.
    */
   void beforeGetEvaluationResult(AstNode node) {}
 
   /**
    * Return `true` if the given [element] represents the `length` getter in
-   * class [String].
+   * class 'String'.
    */
   bool isStringLength(Element element) {
     if (element is PropertyAccessorElement) {
       if (element.isGetter && element.name == 'length') {
         return element.enclosingElement == _typeProvider.stringType.element;
       }
     }
     return false;
   }
 
@@ skipping 362 matching lines @@
       if (i > 0) {
         buffer.writeCharCode(0x2E);
       }
       buffer.write(components[i].lexeme);
     }
     return new DartObjectImpl(
         _typeProvider.symbolType, new SymbolState(buffer.toString()));
   }
 
   /**
-   * Create an error associated with the given node.
-   *
-   * @param node the AST node associated with the error
-   * @param code the error code indicating the nature of the error
+   * Create an error associated with the given [node]. The error will have the
+   * given error [code].
    */
   void _error(AstNode node, ErrorCode code) {
     _errorReporter.reportErrorForNode(
         code == null ? CompileTimeErrorCode.INVALID_CONSTANT : code, node);
   }
 
   /**
-   * Return the constant value of the static constant represented by the given element.
-   *
-   * @param node the node to be used if an error needs to be reported
-   * @param element the element whose value is to be returned
-   * @return the constant value of the static constant
+   * Return the constant value of the static constant represented by the given
+   * [element]. The [node] is the node to be used if an error needs to be
+   * reported.
    */
   DartObjectImpl _getConstantValue(AstNode node, Element element) {
     if (element is PropertyAccessorElement) {
       element = (element as PropertyAccessorElement).variable;
     }
     if (element is VariableElementImpl) {
       VariableElementImpl variableElementImpl = element;
       beforeGetEvaluationResult(node);
       EvaluationResultImpl value = variableElementImpl.evaluationResult;
       if (variableElementImpl.isConst && value != null) {
@@ skipping 26 matching lines @@
       } else if (typeName == "int") {
         return new DartObjectImpl(type, IntState.UNKNOWN_VALUE);
       } else if (typeName == "String") {
         return new DartObjectImpl(type, StringState.UNKNOWN_VALUE);
       }
     }
     return new DartObjectImpl(type, GenericState.UNKNOWN_VALUE);
   }
 
   /**
-   * Return the value of the given expression, or a representation of 'null' if the expression
-   * cannot be evaluated.
-   *
-   * @param expression the expression whose value is to be returned
-   * @return the value of the given expression
+   * Return the value of the given [expression], or a representation of 'null'
+   * if the expression cannot be evaluated.
    */
   DartObjectImpl _valueOf(Expression expression) {
     DartObjectImpl expressionValue = expression.accept(this);
     if (expressionValue != null) {
       return expressionValue;
     }
     return null2;
   }
 }
 
 /**
- * The interface `DartObject` defines the behavior of objects that represent the state of a
- * Dart object.
+ * The state of a Dart object.
  */
 abstract class DartObject {
   /**
-   * Return the boolean value of this object, or `null` if either the value of this object is
-   * not known or this object is not of type 'bool'.
-   *
-   * @return the boolean value of this object
+   * Return the boolean value of this object, or `null` if either the value of
+   * this object is not known or this object is not of type 'bool'.
    */
   bool get boolValue;
 
   /**
-   * Return the floating point value of this object, or `null` if either the value of this
-   * object is not known or this object is not of type 'double'.
-   *
-   * @return the floating point value of this object
+   * Return the floating point value of this object, or `null` if either the
+   * value of this object is not known or this object is not of type 'double'.
    */
   double get doubleValue;
 
   /**
    * Return `true` if this object's value can be represented exactly.
-   *
-   * @return `true` if this object's value can be represented exactly
    */
   bool get hasExactValue;
 
   /**
-   * Return the integer value of this object, or `null` if either the value of this object is
-   * not known or this object is not of type 'int'.
-   *
-   * @return the integer value of this object
+   * Return the integer value of this object, or `null` if either the value of
+   * this object is not known or this object is not of type 'int'.
    */
   int get intValue;
 
   /**
    * Return `true` if this object represents the value 'false'.
-   *
-   * @return `true` if this object represents the value 'false'
    */
   bool get isFalse;
 
   /**
    * Return `true` if this object represents the value 'null'.
-   *
-   * @return `true` if this object represents the value 'null'
    */
   bool get isNull;
 
   /**
    * Return `true` if this object represents the value 'true'.
-   *
-   * @return `true` if this object represents the value 'true'
    */
   bool get isTrue;
 
   /**
-   * Return the string value of this object, or `null` if either the value of this object is
-   * not known or this object is not of type 'String'.
-   *
-   * @return the string value of this object
+   * Return the string value of this object, or `null` if either the value of
+   * this object is not known or this object is not of type 'String'.
    */
   String get stringValue;
 
   /**
    * Return the run-time type of this object.
-   *
-   * @return the run-time type of this object
    */
   ParameterizedType get type;
 
   /**
-   * Return this object's value if it can be represented exactly, or `null` if either the
-   * value cannot be represented exactly or if the value is `null`. Clients should use
-   * [hasExactValue] to distinguish between these two cases.
-   *
-   * @return this object's value
+   * Return this object's value if it can be represented exactly, or `null` if
+   * either the value cannot be represented exactly or if the value is `null`.
+   * Clients should use [hasExactValue] to distinguish between these two cases.
    */
   Object get value;
 }
 
 /**
- * Instances of the class `DartObjectComputer` contain methods for manipulating instances of a
- * Dart class and for collecting errors during evaluation.
+ * A utility class that contains methods for manipulating instances of a Dart
+ * class and for collecting errors during evaluation.
  */
 class DartObjectComputer {
   /**
    * The error reporter that we are using to collect errors.
    */
   final ErrorReporter _errorReporter;
 
   /**
-   * The type provider. Used to create objects of the appropriate types, and to identify when an
-   * object is of a built-in type.
+   * The type provider used to create objects of the appropriate types, and to
+   * identify when an object is of a built-in type.
    */
   final TypeProvider _typeProvider;
 
   DartObjectComputer(this._errorReporter, this._typeProvider);
 
   DartObjectImpl add(BinaryExpression node, DartObjectImpl leftOperand,
       DartObjectImpl rightOperand) {
     if (leftOperand != null && rightOperand != null) {
       try {
         return leftOperand.add(_typeProvider, rightOperand);
       } on EvaluationException catch (exception) {
         _errorReporter.reportErrorForNode(exception.errorCode, node);
         return null;
       }
     }
     return null;
   }
 
   /**
-   * Return the result of applying boolean conversion to this result.
-   *
-   * @param node the node against which errors should be reported
-   * @return the result of applying boolean conversion to the given value
+   * Return the result of applying boolean conversion to the [evaluationResult].
+   * The [node] is the node against which errors should be reported.
    */
   DartObjectImpl applyBooleanConversion(
       AstNode node, DartObjectImpl evaluationResult) {
     if (evaluationResult != null) {
       try {
         return evaluationResult.convertToBool(_typeProvider);
       } on EvaluationException catch (exception) {
         _errorReporter.reportErrorForNode(exception.errorCode, node);
       }
     }
@@ skipping 267 matching lines @@
       try {
         return leftOperand.shiftRight(_typeProvider, rightOperand);
       } on EvaluationException catch (exception) {
         _errorReporter.reportErrorForNode(exception.errorCode, node);
       }
     }
     return null;
   }
 
   /**
-   * Return the result of invoking the 'length' getter on this result.
-   *
-   * @param node the node against which errors should be reported
-   * @return the result of invoking the 'length' getter on this result
+   * Return the result of invoking the 'length' getter on the
+   * [evaluationResult]. The [node] is the node against which errors should be
+   * reported.
    */
   EvaluationResultImpl stringLength(
       Expression node, EvaluationResultImpl evaluationResult) {
     if (evaluationResult.value != null) {
       try {
         return new EvaluationResultImpl.con1(
             evaluationResult.value.stringLength(_typeProvider));
       } on EvaluationException catch (exception) {
         _errorReporter.reportErrorForNode(exception.errorCode, node);
       }
     }
     return new EvaluationResultImpl.con1(null);
   }
 
   DartObjectImpl times(BinaryExpression node, DartObjectImpl leftOperand,
       DartObjectImpl rightOperand) {
     if (leftOperand != null && rightOperand != null) {
       try {
         return leftOperand.times(_typeProvider, rightOperand);
       } on EvaluationException catch (exception) {
         _errorReporter.reportErrorForNode(exception.errorCode, node);
       }
     }
     return null;
   }
 }
 
 /**
- * Instances of the class `DartObjectImpl` represent an instance of a Dart class.
+ * An instance of a Dart class.
  */
 class DartObjectImpl implements DartObject {
   /**
    * An empty list of objects.
    */
   static const List<DartObjectImpl> EMPTY_LIST = const <DartObjectImpl>[];
 
   /**
    * The run-time type of this object.
    */
   final ParameterizedType type;
 
   /**
    * The state of the object.
    */
   final InstanceState _state;
 
   /**
-   * Initialize a newly created object to have the given type and state.
-   *
-   * @param type the run-time type of this object
-   * @param state the state of the object
+   * Initialize a newly created object to have the given [type] and [_state].
    */
   DartObjectImpl(this.type, this._state);
 
   @override
   bool get boolValue {
     if (_state is BoolState) {
       return (_state as BoolState).value;
     }
     return null;
   }
@@ skipping 17 matching lines @@
   @override
   int get intValue {
     if (_state is IntState) {
       return (_state as IntState).value;
     }
     return null;
   }
 
   /**
    * Return `true` if this object represents an object whose type is 'bool'.
-   *
-   * @return `true` if this object represents a boolean value
    */
   bool get isBool => _state.isBool;
 
   /**
-   * Return `true` if this object represents an object whose type is either 'bool', 'num',
-   * 'String', or 'Null'.
-   *
-   * @return `true` if this object represents either a boolean, numeric, string or null value
+   * Return `true` if this object represents an object whose type is either
+   * 'bool', 'num', 'String', or 'Null'.
    */
   bool get isBoolNumStringOrNull => _state.isBoolNumStringOrNull;
 
   @override
   bool get isFalse =>
       _state is BoolState && identical((_state as BoolState).value, false);
 
   @override
   bool get isNull => _state is NullState;
 
   @override
   bool get isTrue =>
       _state is BoolState && identical((_state as BoolState).value, true);
 
   /**
-   * Return true if this object represents an unknown value.
+   * Return `true` if this object represents an unknown value.
    */
   bool get isUnknown => _state.isUnknown;
 
   /**
-   * Return `true` if this object represents an instance of a user-defined class.
-   *
-   * @return `true` if this object represents an instance of a user-defined class
+   * Return `true` if this object represents an instance of a user-defined
+   * class.
    */
   bool get isUserDefinedObject => _state is GenericState;
 
   @override
   String get stringValue {
     if (_state is StringState) {
       return (_state as StringState).value;
     }
     return null;
   }
 
   @override
   Object get value => _state.value;
 
   @override
   bool operator ==(Object object) {
     if (object is! DartObjectImpl) {
       return false;
     }
     DartObjectImpl dartObject = object as DartObjectImpl;
     return type == dartObject.type && _state == dartObject._state;
   }
 
   /**
-   * Return the result of invoking the '+' operator on this object with the given argument.
+   * Return the result of invoking the '+' operator on this object with the
+   * given [rightOperand]. The [typeProvider] is the type provider used to find
+   * known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '+' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl add(TypeProvider typeProvider, DartObjectImpl rightOperand) {
     InstanceState result = _state.add(rightOperand._state);
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     } else if (result is StringState) {
       return new DartObjectImpl(typeProvider.stringType, result);
     }
     // We should never get here.
     throw new IllegalStateException("add returned a ${result.runtimeType}");
   }
 
   /**
-   * Return the result of invoking the '&' operator on this object with the given argument.
+   * Return the result of invoking the '&' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl bitAnd(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.bitAnd(rightOperand._state));
 
   /**
-   * Return the result of invoking the '~' operator on this object.
+   * Return the result of invoking the '~' operator on this object. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of invoking the '~' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl bitNot(TypeProvider typeProvider) =>
       new DartObjectImpl(typeProvider.intType, _state.bitNot());
 
   /**
-   * Return the result of invoking the '|' operator on this object with the given argument.
+   * Return the result of invoking the '|' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '|' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl bitOr(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.bitOr(rightOperand._state));
 
   /**
-   * Return the result of invoking the '^' operator on this object with the given argument.
+   * Return the result of invoking the '^' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '^' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl bitXor(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.bitXor(rightOperand._state));
 
   /**
-   * Return the result of invoking the ' ' operator on this object with the given argument.
+   * Return the result of invoking the ' ' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the ' ' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl concatenate(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.stringType, _state.concatenate(rightOperand._state));
 
   /**
-   * Return the result of applying boolean conversion to this object.
+   * Return the result of applying boolean conversion to this object. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of applying boolean conversion to this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl convertToBool(TypeProvider typeProvider) {
     InterfaceType boolType = typeProvider.boolType;
     if (identical(type, boolType)) {
       return this;
     }
     return new DartObjectImpl(boolType, _state.convertToBool());
   }
 
   /**
-   * Return the result of invoking the '/' operator on this object with the given argument.
+   * Return the result of invoking the '/' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '/' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for
+   * an object of this kind.
    */
   DartObjectImpl divide(
       TypeProvider typeProvider, DartObjectImpl rightOperand) {
     InstanceState result = _state.divide(rightOperand._state);
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException("divide returned a ${result.runtimeType}");
   }
 
   /**
-   * Return the result of invoking the '==' operator on this object with the given argument.
+   * Return the result of invoking the '==' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '==' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl equalEqual(
       TypeProvider typeProvider, DartObjectImpl rightOperand) {
     if (type != rightOperand.type) {
       String typeName = type.name;
       if (!(typeName == "bool" ||
           typeName == "double" ||
           typeName == "int" ||
           typeName == "num" ||
           typeName == "String" ||
           typeName == "Null" ||
           type.isDynamic)) {
         throw new EvaluationException(
             CompileTimeErrorCode.CONST_EVAL_TYPE_BOOL_NUM_STRING);
       }
     }
     return new DartObjectImpl(
         typeProvider.boolType, _state.equalEqual(rightOperand._state));
   }
 
   /**
-   * Return the result of invoking the '&gt;' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl greaterThan(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.boolType, _state.greaterThan(rightOperand._state));
 
   /**
-   * Return the result of invoking the '&gt;=' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;=' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;=' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl greaterThanOrEqual(TypeProvider typeProvider,
       DartObjectImpl rightOperand) => new DartObjectImpl(
       typeProvider.boolType, _state.greaterThanOrEqual(rightOperand._state));
 
   /**
-   * Return the result of invoking the '~/' operator on this object with the given argument.
+   * Return the result of invoking the '~/' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '~/' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl integerDivide(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.integerDivide(rightOperand._state));
 
   /**
    * Return the result of invoking the identical function on this object with
-   * the given argument.
-   *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the identical function on this object with
-   *         the given argument
+   * the [rightOperand]. The [typeProvider] is the type provider used to find
+   * known types.
    */
   DartObjectImpl isIdentical(
       TypeProvider typeProvider, DartObjectImpl rightOperand) {
     return new DartObjectImpl(
         typeProvider.boolType, _state.isIdentical(rightOperand._state));
   }
 
   /**
-   * Return the result of invoking the '&lt;' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl lessThan(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.boolType, _state.lessThan(rightOperand._state));
 
   /**
-   * Return the result of invoking the '&lt;=' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;=' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;=' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl lessThanOrEqual(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.boolType, _state.lessThanOrEqual(rightOperand._state));
 
   /**
-   * Return the result of invoking the '&&' operator on this object with the given argument.
+   * Return the result of invoking the '&&' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&&' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl logicalAnd(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.boolType, _state.logicalAnd(rightOperand._state));
 
   /**
-   * Return the result of invoking the '!' operator on this object.
+   * Return the result of invoking the '!' operator on this object. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of invoking the '!' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl logicalNot(TypeProvider typeProvider) =>
       new DartObjectImpl(typeProvider.boolType, _state.logicalNot());
 
   /**
-   * Return the result of invoking the '||' operator on this object with the given argument.
+   * Return the result of invoking the '||' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '||' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl logicalOr(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.boolType, _state.logicalOr(rightOperand._state));
 
   /**
-   * Return the result of invoking the '-' operator on this object with the given argument.
+   * Return the result of invoking the '-' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '-' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl minus(TypeProvider typeProvider, DartObjectImpl rightOperand) {
     InstanceState result = _state.minus(rightOperand._state);
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException("minus returned a ${result.runtimeType}");
   }
 
   /**
-   * Return the result of invoking the '-' operator on this object.
+   * Return the result of invoking the '-' operator on this object. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of invoking the '-' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl negated(TypeProvider typeProvider) {
     InstanceState result = _state.negated();
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException("negated returned a ${result.runtimeType}");
   }
 
   /**
-   * Return the result of invoking the '!=' operator on this object with the given argument.
+   * Return the result of invoking the '!=' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '!=' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl notEqual(
       TypeProvider typeProvider, DartObjectImpl rightOperand) {
     if (type != rightOperand.type) {
       String typeName = type.name;
       if (typeName != "bool" &&
           typeName != "double" &&
           typeName != "int" &&
           typeName != "num" &&
           typeName != "String") {
         return new DartObjectImpl(typeProvider.boolType, BoolState.TRUE_STATE);
       }
     }
     return new DartObjectImpl(typeProvider.boolType,
         _state.equalEqual(rightOperand._state).logicalNot());
   }
 
   /**
-   * Return the result of converting this object to a String.
+   * Return the result of converting this object to a 'String'. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of converting this object to a String
-   * @throws EvaluationException if the object cannot be converted to a String
+   * Throws an [EvaluationException] if the object cannot be converted to a
+   * 'String'.
    */
   DartObjectImpl performToString(TypeProvider typeProvider) {
     InterfaceType stringType = typeProvider.stringType;
     if (identical(type, stringType)) {
       return this;
     }
     return new DartObjectImpl(stringType, _state.convertToString());
   }
 
   /**
-   * Return the result of invoking the '%' operator on this object with the given argument.
+   * Return the result of invoking the '%' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '%' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl remainder(
       TypeProvider typeProvider, DartObjectImpl rightOperand) {
     InstanceState result = _state.remainder(rightOperand._state);
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException(
         "remainder returned a ${result.runtimeType}");
   }
 
   /**
-   * Return the result of invoking the '&lt;&lt;' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;&lt;' operator on this object with
+   * the [rightOperand]. The [typeProvider] is the type provider used to find
+   * known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;&lt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl shiftLeft(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.shiftLeft(rightOperand._state));
 
   /**
-   * Return the result of invoking the '&gt;&gt;' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;&gt;' operator on this object with
+   * the [rightOperand]. The [typeProvider] is the type provider used to find
+   * known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;&gt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl shiftRight(
           TypeProvider typeProvider, DartObjectImpl rightOperand) =>
       new DartObjectImpl(
           typeProvider.intType, _state.shiftRight(rightOperand._state));
 
   /**
-   * Return the result of invoking the 'length' getter on this object.
+   * Return the result of invoking the 'length' getter on this object. The
+   * [typeProvider] is the type provider used to find known types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of invoking the 'length' getter on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl stringLength(TypeProvider typeProvider) =>
       new DartObjectImpl(typeProvider.intType, _state.stringLength());
 
   /**
-   * Return the result of invoking the '*' operator on this object with the given argument.
+   * Return the result of invoking the '*' operator on this object with the
+   * [rightOperand]. The [typeProvider] is the type provider used to find known
+   * types.
    *
-   * @param typeProvider the type provider used to find known types
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '*' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   DartObjectImpl times(TypeProvider typeProvider, DartObjectImpl rightOperand) {
     InstanceState result = _state.times(rightOperand._state);
     if (result is IntState) {
       return new DartObjectImpl(typeProvider.intType, result);
     } else if (result is DoubleState) {
       return new DartObjectImpl(typeProvider.doubleType, result);
     } else if (result is NumState) {
       return new DartObjectImpl(typeProvider.numType, result);
     }
     // We should never get here.
     throw new IllegalStateException("times returned a ${result.runtimeType}");
   }
 
   @override
   String toString() => "${type.displayName} ($_state)";
 }
 
 /**
- * Instances of the class `DeclaredVariables` provide access to the values of variables that
- * have been defined on the command line using the `-D` option.
+ * An object used to provide access to the values of variables that have been
+ * defined on the command line using the `-D` option.
  */
 class DeclaredVariables {
   /**
    * A table mapping the names of declared variables to their values.
    */
   HashMap<String, String> _declaredVariables = new HashMap<String, String>();
 
   /**
-   * Define a variable with the given name to have the given value.
-   *
-   * @param variableName the name of the variable being defined
-   * @param value the value of the variable
+   * Define a variable with the given [name] to have the given [value].
    */
-  void define(String variableName, String value) {
-    _declaredVariables[variableName] = value;
+  void define(String name, String value) {
+    _declaredVariables[name] = value;
   }
 
   /**
-   * Return the value of the variable with the given name interpreted as a boolean value. If the
-   * variable is not defined (or [variableName] is null), a DartObject representing "unknown"
-   * is returned. If the value can't be parsed as a boolean, a DartObject representing null is
-   * returned.
-   *
-   * @param typeProvider the type provider used to find the type 'bool'
-   * @param variableName the name of the variable whose value is to be returned
+   * Return the value of the variable with the given [name] interpreted as a
+   * 'boolean' value. If the variable is not defined (or [name] is `null`), a
+   * DartObject representing "unknown" is returned. If the value cannot be
+   * parsed as a boolean, a DartObject representing 'null' is returned. The
+   * [typeProvider] is the type provider used to find the type 'bool'.
    */
-  DartObject getBool(TypeProvider typeProvider, String variableName) {
-    String value = _declaredVariables[variableName];
+  DartObject getBool(TypeProvider typeProvider, String name) {
+    String value = _declaredVariables[name];
     if (value == null) {
       return new DartObjectImpl(typeProvider.boolType, BoolState.UNKNOWN_VALUE);
     }
     if (value == "true") {
       return new DartObjectImpl(typeProvider.boolType, BoolState.TRUE_STATE);
     } else if (value == "false") {
       return new DartObjectImpl(typeProvider.boolType, BoolState.FALSE_STATE);
     }
     return new DartObjectImpl(typeProvider.nullType, NullState.NULL_STATE);
   }
 
   /**
-   * Return the value of the variable with the given name interpreted as an integer value. If the
-   * variable is not defined (or [variableName] is null), a DartObject representing "unknown"
-   * is returned. If the value can't be parsed as an integer, a DartObject representing null is
-   * returned.
-   *
-   * @param typeProvider the type provider used to find the type 'int'
-   * @param variableName the name of the variable whose value is to be returned
+   * Return the value of the variable with the given [name] interpreted as an
+   * integer value. If the variable is not defined (or [name] is `null`), a
+   * DartObject representing "unknown" is returned. If the value cannot be
+   * parsed as an integer, a DartObject representing 'null' is returned.
    */
-  DartObject getInt(TypeProvider typeProvider, String variableName) {
-    String value = _declaredVariables[variableName];
+  DartObject getInt(TypeProvider typeProvider, String name) {
+    String value = _declaredVariables[name];
     if (value == null) {
       return new DartObjectImpl(typeProvider.intType, IntState.UNKNOWN_VALUE);
     }
     int bigInteger;
     try {
       bigInteger = int.parse(value);
     } on FormatException catch (exception) {
       return new DartObjectImpl(typeProvider.nullType, NullState.NULL_STATE);
     }
     return new DartObjectImpl(typeProvider.intType, new IntState(bigInteger));
   }
 
   /**
-   * Return the value of the variable with the given name interpreted as a String value, or
-   * `null` if the variable is not defined. Return the value of the variable with the given
-   * name interpreted as a String value. If the variable is not defined (or [variableName] is
-   * null), a DartObject representing "unknown" is returned.
-   *
-   * @param typeProvider the type provider used to find the type 'String'
-   * @param variableName the name of the variable whose value is to be returned
+   * Return the value of the variable with the given [name] interpreted as a
+   * String value, or `null` if the variable is not defined. Return the value of
+   * the variable with the given name interpreted as a String value. If the
+   * variable is not defined (or [name] is `null`), a DartObject representing
+   * "unknown" is returned. The [typeProvider] is the type provider used to find
+   * the type 'String'.
    */
-  DartObject getString(TypeProvider typeProvider, String variableName) {
-    String value = _declaredVariables[variableName];
+  DartObject getString(TypeProvider typeProvider, String name) {
+    String value = _declaredVariables[name];
     if (value == null) {
       return new DartObjectImpl(
           typeProvider.stringType, StringState.UNKNOWN_VALUE);
     }
     return new DartObjectImpl(typeProvider.stringType, new StringState(value));
   }
 }
 
 /**
- * Instances of the class `DoubleState` represent the state of an object representing a
- * double.
+ * The state of an object representing a double.
  */
 class DoubleState extends NumState {
   /**
    * A state that can be used to represent a double whose value is not known.
    */
   static DoubleState UNKNOWN_VALUE = new DoubleState(null);
 
   /**
    * The value of this instance.
    */
   final double value;
 
   /**
-   * Initialize a newly created state to represent a double with the given value.
-   *
-   * @param value the value of this instance
+   * Initialize a newly created state to represent a double with the given
+   * [value].
    */
   DoubleState(this.value);
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => value == null ? 0 : value.hashCode;
 
   @override
@@ skipping 304 matching lines @@
     }
     throw new EvaluationException(
         CompileTimeErrorCode.CONST_EVAL_THROWS_EXCEPTION);
   }
 
   @override
   String toString() => value == null ? "-unknown-" : value.toString();
 }
 
 /**
- * Instances of the class `DynamicState` represent the state of an object representing a Dart
- * object for which there is no type information.
+ * The state of an object representing a Dart object for which there is no type
+ * information.
  */
 class DynamicState extends InstanceState {
   /**
    * The unique instance of this class.
    */
   static DynamicState DYNAMIC_STATE = new DynamicState();
 
   @override
   bool get isBool => true;
 
@@ skipping 131 matching lines @@
     return IntState.UNKNOWN_VALUE;
   }
 
   @override
   NumState times(InstanceState rightOperand) {
     assertNumOrNull(rightOperand);
     return _unknownNum(rightOperand);
   }
 
   /**
-   * Return an object representing an unknown numeric value whose type is based on the type of the
-   * right-hand operand.
-   *
-   * @param rightOperand the operand whose type will determine the type of the result
-   * @return an object representing an unknown numeric value
+   * Return an object representing an unknown numeric value whose type is based
+   * on the type of the [rightOperand].
    */
   NumState _unknownNum(InstanceState rightOperand) {
     if (rightOperand is IntState) {
       return IntState.UNKNOWN_VALUE;
     } else if (rightOperand is DoubleState) {
       return DoubleState.UNKNOWN_VALUE;
     }
     return NumState.UNKNOWN_VALUE;
   }
 }
 
 /**
- * Instances of the class `EvaluationException` represent a run-time exception that would be
- * thrown during the evaluation of Dart code.
+ * A run-time exception that would be thrown during the evaluation of Dart code.
  */
 class EvaluationException extends JavaException {
   /**
    * The error code associated with the exception.
    */
   final ErrorCode errorCode;
 
   /**
-   * Initialize a newly created exception to have the given error code.
-   *
-   * @param errorCode the error code associated with the exception
+   * Initialize a newly created exception to have the given [errorCode].
    */
   EvaluationException(this.errorCode);
 }
 
 /**
- * Instances of the class `EvaluationResult` represent the result of attempting to evaluate an
- * expression.
+ * The result of attempting to evaluate an expression.
  */
 class EvaluationResult {
   /**
    * The value of the expression.
    */
   final DartObject value;
 
   /**
-   * The errors that should be reported for the expression(s) that were evaluated.
+   * The errors that should be reported for the expression(s) that were
+   * evaluated.
    */
   final List<AnalysisError> _errors;
 
   /**
-   * Initialize a newly created result object with the given state. Clients should use one of the
-   * factory methods: [forErrors] and [forValue].
-   *
-   * @param value the value of the expression
-   * @param errors the errors that should be reported for the expression(s) that were evaluated
+   * Initialize a newly created result object with the given [value] and set of
+   * [_errors]. Clients should use one of the factory methods: [forErrors] and
+   * [forValue].
    */
   EvaluationResult(this.value, this._errors);
 
   /**
-   * Return an array containing the errors that should be reported for the expression(s) that were
-   * evaluated. If there are no such errors, the array will be empty. The array can be empty even if
-   * the expression is not a valid compile time constant if the errors would have been reported by
-   * other parts of the analysis engine.
+   * Return a list containing the errors that should be reported for the
+   * expression(s) that were evaluated. If there are no such errors, the list
+   * will be empty. The list can be empty even if the expression is not a valid
+   * compile time constant if the errors would have been reported by other parts
+   * of the analysis engine.
    */
   List<AnalysisError> get errors =>
       _errors == null ? AnalysisError.NO_ERRORS : _errors;
 
   /**
-   * Return `true` if the expression is a compile-time constant expression that would not
-   * throw an exception when evaluated.
-   *
-   * @return `true` if the expression is a valid compile-time constant expression
+   * Return `true` if the expression is a compile-time constant expression that
+   * would not throw an exception when evaluated.
    */
   bool get isValid => _errors == null;
 
   /**
-   * Return an evaluation result representing the result of evaluating an expression that is not a
-   * compile-time constant because of the given errors.
-   *
-   * @param errors the errors that should be reported for the expression(s) that were evaluated
-   * @return the result of evaluating an expression that is not a compile-time constant
+   * Return an evaluation result representing the result of evaluating an
+   * expression that is not a compile-time constant because of the given
+   * [errors].
    */
   static EvaluationResult forErrors(List<AnalysisError> errors) =>
       new EvaluationResult(null, errors);
 
   /**
-   * Return an evaluation result representing the result of evaluating an expression that is a
-   * compile-time constant that evaluates to the given value.
-   *
-   * @param value the value of the expression
-   * @return the result of evaluating an expression that is a compile-time constant
+   * Return an evaluation result representing the result of evaluating an
+   * expression that is a compile-time constant that evaluates to the given
+   * [value].
    */
   static EvaluationResult forValue(DartObject value) =>
       new EvaluationResult(value, null);
 }
 
 /**
- * Instances of the class `InternalResult` represent the result of attempting to evaluate a
- * expression.
+ * The result of attempting to evaluate a expression.
  */
 class EvaluationResultImpl {
   /**
-   * The errors encountered while trying to evaluate the compile time constant. These errors may or
-   * may not have prevented the expression from being a valid compile time constant.
+   * The errors encountered while trying to evaluate the compile time constant.
+   * These errors may or may not have prevented the expression from being a
+   * valid compile time constant.
    */
   List<AnalysisError> _errors;
 
   /**
-   * The value of the expression, or null if the value couldn't be computed due to errors.
+   * The value of the expression, or `null` if the value couldn't be computed
+   * due to errors.
    */
   final DartObjectImpl value;
 
   EvaluationResultImpl.con1(this.value) {
     this._errors = new List<AnalysisError>(0);
   }
 
   EvaluationResultImpl.con2(this.value, List<AnalysisError> errors) {
     this._errors = errors;
   }
@@ skipping 14 matching lines @@
   @override
   String toString() {
     if (value == null) {
       return "error";
     }
     return value.toString();
   }
 }
 
 /**
- * Instances of the class `FunctionState` represent the state of an object representing a
- * function.
+ * The state of an object representing a function.
  */
 class FunctionState extends InstanceState {
   /**
    * The element representing the function being modeled.
    */
   final ExecutableElement _element;
 
   /**
-   * Initialize a newly created state to represent the given function.
-   *
-   * @param element the element representing the function being modeled
+   * Initialize a newly created state to represent the function with the given
+   * [element].
    */
   FunctionState(this._element);
 
   @override
   int get hashCode => _element == null ? 0 : _element.hashCode;
 
   @override
   String get typeName => "Function";
 
   @override
@@ skipping 28 matching lines @@
       return BoolState.UNKNOWN_VALUE;
     }
     return BoolState.FALSE_STATE;
   }
 
   @override
   String toString() => _element == null ? "-unknown-" : _element.name;
 }
 
 /**
- * Instances of the class `GenericState` represent the state of an object representing a Dart
- * object for which there is no more specific state.
+ * The state of an object representing a Dart object for which there is no more
+ * specific state.
  */
 class GenericState extends InstanceState {
   /**
    * Pseudo-field that we use to represent fields in the superclass.
    */
   static String SUPERCLASS_FIELD = "(super)";
 
   /**
    * A state that can be used to represent an object whose state is not known.
    */
   static GenericState UNKNOWN_VALUE =
       new GenericState(new HashMap<String, DartObjectImpl>());
 
   /**
    * The values of the fields of this instance.
    */
   final HashMap<String, DartObjectImpl> _fieldMap;
 
   /**
-   * Initialize a newly created state to represent a newly created object.
-   *
-   * @param fieldMap the values of the fields of this instance
+   * Initialize a newly created state to represent a newly created object. The
+   * [fieldMap] contains the values of the fields of the instance.
    */
   GenericState(this._fieldMap);
 
   @override
   HashMap<String, DartObjectImpl> get fields => _fieldMap;
 
   @override
   int get hashCode {
     int hashCode = 0;
     for (DartObjectImpl value in _fieldMap.values) {
@@ skipping 61 matching lines @@
       }
       buffer.write(fieldName);
       buffer.write(' = ');
       buffer.write(_fieldMap[fieldName]);
     }
     return buffer.toString();
   }
 }
 
 /**
- * The class `InstanceState` defines the behavior of objects representing the state of a Dart
- * object.
+ * The state of an object representing a Dart object.
  */
 abstract class InstanceState {
   /**
-   * If this represents a generic dart object, return a map from its fieldnames to their values.
-   * Otherwise return null.
+   * If this represents a generic dart object, return a map from its field names
+   * to their values. Otherwise return null.
    */
   HashMap<String, DartObjectImpl> get fields => null;
 
   /**
    * Return `true` if this object's value can be represented exactly.
-   *
-   * @return `true` if this object's value can be represented exactly
    */
   bool get hasExactValue => false;
 
   /**
    * Return `true` if this object represents an object whose type is 'bool'.
-   *
-   * @return `true` if this object represents a boolean value
    */
   bool get isBool => false;
 
   /**
-   * Return `true` if this object represents an object whose type is either 'bool', 'num',
-   * 'String', or 'Null'.
-   *
-   * @return `true` if this object represents either a boolean, numeric, string or null value
+   * Return `true` if this object represents an object whose type is either
+   * 'bool', 'num', 'String', or 'Null'.
    */
   bool get isBoolNumStringOrNull => false;
 
   /**
-   * Return true if this object represents an unknown value.
+   * Return `true` if this object represents an unknown value.
    */
   bool get isUnknown => false;
 
   /**
    * Return the name of the type of this value.
-   *
-   * @return the name of the type of this value
    */
   String get typeName;
 
   /**
-   * Return this object's value if it can be represented exactly, or `null` if either the
-   * value cannot be represented exactly or if the value is `null`. Clients should use
-   * [hasExactValue] to distinguish between these two cases.
-   *
-   * @return this object's value
+   * Return this object's value if it can be represented exactly, or `null` if
+   * either the value cannot be represented exactly or if the value is `null`.
+   * Clients should use [hasExactValue] to distinguish between these two cases.
    */
   Object get value => null;
 
   /**
-   * Return the result of invoking the '+' operator on this object with the given argument.
+   * Return the result of invoking the '+' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '+' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   InstanceState add(InstanceState rightOperand) {
     if (this is StringState && rightOperand is StringState) {
       return concatenate(rightOperand);
     }
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Throw an exception if the given state does not represent a boolean value.
-   *
-   * @param state the state being tested
-   * @throws EvaluationException if the given state does not represent a boolean value
+   * Throw an exception if the given [state] does not represent a boolean value.
    */
   void assertBool(InstanceState state) {
     if (!(state is BoolState || state is DynamicState)) {
       throw new EvaluationException(CompileTimeErrorCode.CONST_EVAL_TYPE_BOOL);
     }
   }
 
   /**
-   * Throw an exception if the given state does not represent a boolean, numeric, string or null
-   * value.
-   *
-   * @param state the state being tested
-   * @throws EvaluationException if the given state does not represent a boolean, numeric, string or
-   *           null value
+   * Throw an exception if the given [state] does not represent a boolean,
+   * numeric, string or null value.
    */
   void assertBoolNumStringOrNull(InstanceState state) {
     if (!(state is BoolState ||
         state is DoubleState ||
         state is IntState ||
         state is NumState ||
         state is StringState ||
         state is NullState ||
         state is DynamicState)) {
       throw new EvaluationException(
           CompileTimeErrorCode.CONST_EVAL_TYPE_BOOL_NUM_STRING);
     }
   }
 
   /**
-   * Throw an exception if the given state does not represent an integer or null value.
-   *
-   * @param state the state being tested
-   * @throws EvaluationException if the given state does not represent an integer or null value
+   * Throw an exception if the given [state] does not represent an integer or
+   * null value.
    */
   void assertIntOrNull(InstanceState state) {
     if (!(state is IntState ||
         state is NumState ||
         state is NullState ||
         state is DynamicState)) {
       throw new EvaluationException(CompileTimeErrorCode.CONST_EVAL_TYPE_INT);
     }
   }
 
   /**
-   * Throw an exception if the given state does not represent a boolean, numeric, string or null
-   * value.
-   *
-   * @param state the state being tested
-   * @throws EvaluationException if the given state does not represent a boolean, numeric, string or
-   *           null value
+   * Throw an exception if the given [state] does not represent a boolean,
+   * numeric, string or null value.
    */
   void assertNumOrNull(InstanceState state) {
     if (!(state is DoubleState ||
         state is IntState ||
         state is NumState ||
         state is NullState ||
         state is DynamicState)) {
       throw new EvaluationException(CompileTimeErrorCode.CONST_EVAL_TYPE_NUM);
     }
   }
 
   /**
-   * Throw an exception if the given state does not represent a String value.
-   *
-   * @param state the state being tested
-   * @throws EvaluationException if the given state does not represent a String value
+   * Throw an exception if the given [state] does not represent a String value.
    */
   void assertString(InstanceState state) {
     if (!(state is StringState || state is DynamicState)) {
       throw new EvaluationException(CompileTimeErrorCode.CONST_EVAL_TYPE_BOOL);
     }
   }
 
   /**
-   * Return the result of invoking the '&' operator on this object with the given argument.
+   * Return the result of invoking the '&' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState bitAnd(InstanceState rightOperand) {
     assertIntOrNull(this);
     assertIntOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
    * Return the result of invoking the '~' operator on this object.
    *
-   * @return the result of invoking the '~' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState bitNot() {
     assertIntOrNull(this);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '|' operator on this object with the given argument.
+   * Return the result of invoking the '|' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '|' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState bitOr(InstanceState rightOperand) {
     assertIntOrNull(this);
     assertIntOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '^' operator on this object with the given argument.
+   * Return the result of invoking the '^' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '^' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState bitXor(InstanceState rightOperand) {
     assertIntOrNull(this);
     assertIntOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the ' ' operator on this object with the given argument.
+   * Return the result of invoking the ' ' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the ' ' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   StringState concatenate(InstanceState rightOperand) {
     assertString(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
    * Return the result of applying boolean conversion to this object.
    *
-   * @param typeProvider the type provider used to find known types
-   * @return the result of applying boolean conversion to this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState convertToBool() => BoolState.FALSE_STATE;
 
   /**
    * Return the result of converting this object to a String.
    *
-   * @return the result of converting this object to a String
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   StringState convertToString();
 
   /**
-   * Return the result of invoking the '/' operator on this object with the given argument.
+   * Return the result of invoking the '/' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '/' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   NumState divide(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '==' operator on this object with the given argument.
+   * Return the result of invoking the '==' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '==' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState equalEqual(InstanceState rightOperand);
 
   /**
-   * Return the result of invoking the '&gt;' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState greaterThan(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '&gt;=' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;=' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;=' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState greaterThanOrEqual(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '~/' operator on this object with the given argument.
+   * Return the result of invoking the '~/' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '~/' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState integerDivide(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
    * Return the result of invoking the identical function on this object with
-   * the given argument.
-   *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the identical function on this object with
-   *         the given argument
+   * the [rightOperand].
    */
   BoolState isIdentical(InstanceState rightOperand);
 
   /**
-   * Return the result of invoking the '&lt;' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState lessThan(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '&lt;=' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;=' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;=' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState lessThanOrEqual(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '&&' operator on this object with the given argument.
+   * Return the result of invoking the '&&' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&&' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState logicalAnd(InstanceState rightOperand) {
     assertBool(this);
     assertBool(rightOperand);
     return BoolState.FALSE_STATE;
   }
 
   /**
    * Return the result of invoking the '!' operator on this object.
    *
-   * @return the result of invoking the '!' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState logicalNot() {
     assertBool(this);
     return BoolState.TRUE_STATE;
   }
 
   /**
-   * Return the result of invoking the '||' operator on this object with the given argument.
+   * Return the result of invoking the '||' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '||' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   BoolState logicalOr(InstanceState rightOperand) {
     assertBool(this);
     assertBool(rightOperand);
     return rightOperand.convertToBool();
   }
 
   /**
-   * Return the result of invoking the '-' operator on this object with the given argument.
+   * Return the result of invoking the '-' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '-' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   NumState minus(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
    * Return the result of invoking the '-' operator on this object.
    *
-   * @return the result of invoking the '-' operator on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   NumState negated() {
     assertNumOrNull(this);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '%' operator on this object with the given argument.
+   * Return the result of invoking the '%' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '%' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   NumState remainder(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '&lt;&lt;' operator on this object with the given argument.
+   * Return the result of invoking the '&lt;&lt;' operator on this object with
+   * the [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&lt;&lt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState shiftLeft(InstanceState rightOperand) {
     assertIntOrNull(this);
     assertIntOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '&gt;&gt;' operator on this object with the given argument.
+   * Return the result of invoking the '&gt;&gt;' operator on this object with
+   * the [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '&gt;&gt;' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState shiftRight(InstanceState rightOperand) {
     assertIntOrNull(this);
     assertIntOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
    * Return the result of invoking the 'length' getter on this object.
    *
-   * @return the result of invoking the 'length' getter on this object
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   IntState stringLength() {
     assertString(this);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 
   /**
-   * Return the result of invoking the '*' operator on this object with the given argument.
+   * Return the result of invoking the '*' operator on this object with the
+   * [rightOperand].
    *
-   * @param rightOperand the right-hand operand of the operation
-   * @return the result of invoking the '*' operator on this object with the given argument
-   * @throws EvaluationException if the operator is not appropriate for an object of this kind
+   * Throws an [EvaluationException] if the operator is not appropriate for an
+   * object of this kind.
    */
   NumState times(InstanceState rightOperand) {
     assertNumOrNull(this);
     assertNumOrNull(rightOperand);
     throw new EvaluationException(CompileTimeErrorCode.INVALID_CONSTANT);
   }
 }
 
 /**
- * Instances of the class `IntState` represent the state of an object representing an int.
+ * The state of an object representing an int.
  */
 class IntState extends NumState {
   /**
    * A state that can be used to represent an int whose value is not known.
    */
   static IntState UNKNOWN_VALUE = new IntState(null);
 
   /**
    * The value of this instance.
    */
   final int value;
 
   /**
-   * Initialize a newly created state to represent an int with the given value.
-   *
-   * @param value the value of this instance
+   * Initialize a newly created state to represent an int with the given
+   * [value].
    */
   IntState(this.value);
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => value == null ? 0 : value.hashCode;
 
   @override
@@ skipping 432 matching lines @@
     }
     throw new EvaluationException(
         CompileTimeErrorCode.CONST_EVAL_THROWS_EXCEPTION);
   }
 
   @override
   String toString() => value == null ? "-unknown-" : value.toString();
 }
 
 /**
- * The unique instance of the class `ListState` represents the state of an object representing
- * a list.
+ * The state of an object representing a list.
  */
 class ListState extends InstanceState {
   /**
    * The elements of the list.
    */
   final List<DartObjectImpl> _elements;
 
   /**
-   * Initialize a newly created state to represent a list with the given elements.
-   *
-   * @param elements the elements of the list
+   * Initialize a newly created state to represent a list with the given
+   * [elements].
    */
   ListState(this._elements);
 
   @override
   bool get hasExactValue {
     int count = _elements.length;
     for (int i = 0; i < count; i++) {
       if (!_elements[i].hasExactValue) {
         return false;
       }
@@ skipping 77 matching lines @@
         buffer.write(', ');
       }
       buffer.write(element);
     });
     buffer.write(']');
     return buffer.toString();
   }
 }
 
 /**
- * The unique instance of the class `ListState` represents the state of an object representing
- * a map.
+ * The state of an object representing a map.
  */
 class MapState extends InstanceState {
   /**
    * The entries in the map.
    */
   final HashMap<DartObjectImpl, DartObjectImpl> _entries;
 
   /**
-   * Initialize a newly created state to represent a map with the given entries.
-   *
-   * @param entries the entries in the map
+   * Initialize a newly created state to represent a map with the given
+   * [entries].
    */
   MapState(this._entries);
 
   @override
   bool get hasExactValue {
     for (DartObjectImpl key in _entries.keys) {
       if (!key.hasExactValue || !_entries[key].hasExactValue) {
         return false;
       }
     }
@@ skipping 79 matching lines @@
       buffer.write(key);
       buffer.write(' = ');
       buffer.write(value);
     });
     buffer.write('}');
     return buffer.toString();
   }
 }
 
 /**
- * The unique instance of the class `NullState` represents the state of the value 'null'.
+ * The state of an object representing the value 'null'.
  */
 class NullState extends InstanceState {
   /**
-   * An instance representing the boolean value 'true'.
+   * An instance representing the boolean value 'null'.
    */
   static NullState NULL_STATE = new NullState();
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => 0;
 
   @override
@@ skipping 32 matching lines @@
   BoolState logicalNot() {
     throw new EvaluationException(
         CompileTimeErrorCode.CONST_EVAL_THROWS_EXCEPTION);
   }
 
   @override
   String toString() => "null";
 }
 
 /**
- * Instances of the class `NumState` represent the state of an object representing a number of
- * an unknown type (a 'num').
+ * The state of an object representing a number of an unknown type (a 'num').
  */
 class NumState extends InstanceState {
   /**
    * A state that can be used to represent a number whose value is not known.
    */
   static NumState UNKNOWN_VALUE = new NumState();
 
   @override
   int get hashCode => 7;
 
@@ skipping 95 matching lines @@
   NumState times(InstanceState rightOperand) {
     assertNumOrNull(rightOperand);
     return UNKNOWN_VALUE;
   }
 
   @override
   String toString() => "-unknown-";
 }
 
 /**
- * Instances of the class `ReferenceFinder` add reference information for a given variable to
- * the bi-directional mapping used to order the evaluation of constants.
+ * An object used to add reference information for a given variable to the
+ * bi-directional mapping used to order the evaluation of constants.
  */
 class ReferenceFinder extends RecursiveAstVisitor<Object> {
   /**
    * The element representing the construct that will be visited.
    */
   final AstNode _source;
 
   /**
-   * A graph in which the nodes are the constant variables and the edges are from each variable to
-   * the other constant variables that are referenced in the head's initializer.
+   * A graph in which the nodes are the constant variables and the edges are
+   * from each variable to the other constant variables that are referenced in
+   * the head's initializer.
    */
   final DirectedGraph<AstNode> _referenceGraph;
 
   /**
    * A table mapping constant variables to the declarations of those variables.
    */
   final HashMap<VariableElement, VariableDeclaration> _variableDeclarationMap;
 
   /**
-   * A table mapping constant constructors to the declarations of those constructors.
+   * A table mapping constant constructors to the declarations of those
+   * constructors.
    */
   final HashMap<ConstructorElement, ConstructorDeclaration> _constructorDeclarationMap;
 
   /**
-   * Initialize a newly created reference finder to find references from the given variable to other
-   * variables and to add those references to the given graph.
-   *
-   * @param source the element representing the variable whose initializer will be visited
-   * @param referenceGraph a graph recording which variables (heads) reference which other variables
-   *          (tails) in their initializers
-   * @param variableDeclarationMap A table mapping constant variables to the declarations of those
-   *          variables.
-   * @param constructorDeclarationMap A table mapping constant constructors to the declarations of
-   *          those constructors.
+   * Initialize a newly created reference finder to find references from a given
+   * variable to other variables and to add those references to the given graph.
+   * The [source] is the element representing the variable whose initializer
+   * will be visited. The [referenceGraph] is a graph recording which variables
+   * (heads) reference which other variables (tails) in their initializers. The
+   * [variableDeclarationMap] is a table mapping constant variables to the
+   * declarations of those variables. The [constructorDeclarationMap] is a table
+   * mapping constant constructors to the declarations of those constructors.
    */
   ReferenceFinder(this._source, this._referenceGraph,
       this._variableDeclarationMap, this._constructorDeclarationMap);
 
   @override
   Object visitInstanceCreationExpression(InstanceCreationExpression node) {
     if (node.isConst) {
       _referenceGraph.addEdge(_source, node);
     }
     return null;
@@ skipping 51 matching lines @@
       // to check because there's nothing we can do about it at this point.
       if (constructorDeclaration != null) {
         _referenceGraph.addEdge(_source, constructorDeclaration);
       }
     }
     return null;
   }
 }
 
 /**
- * Instances of the class `StringState` represent the state of an object representing a
- * string.
+ * The state of an object representing a string.
  */
 class StringState extends InstanceState {
   /**
    * A state that can be used to represent a double whose value is not known.
    */
   static StringState UNKNOWN_VALUE = new StringState(null);
 
   /**
    * The value of this instance.
    */
   final String value;
 
   /**
-   * Initialize a newly created state to represent the given value.
-   *
-   * @param value the value of this instance
+   * Initialize a newly created state to represent the given [value].
    */
   StringState(this.value);
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => value == null ? 0 : value.hashCode;
 
   @override
@@ skipping 58 matching lines @@
       return IntState.UNKNOWN_VALUE;
     }
     return new IntState(value.length);
   }
 
   @override
   String toString() => value == null ? "-unknown-" : "'$value'";
 }
 
 /**
- * Instances of the class `StringState` represent the state of an object representing a
- * symbol.
+ * The state of an object representing a symbol.
  */
 class SymbolState extends InstanceState {
   /**
    * The value of this instance.
    */
   final String value;
 
   /**
-   * Initialize a newly created state to represent the given value.
-   *
-   * @param value the value of this instance
+   * Initialize a newly created state to represent the given [value].
    */
   SymbolState(this.value);
 
   @override
   bool get hasExactValue => true;
 
   @override
   int get hashCode => value == null ? 0 : value.hashCode;
 
   @override
@@ skipping 32 matching lines @@
       return BoolState.UNKNOWN_VALUE;
     }
     return BoolState.FALSE_STATE;
   }
 
   @override
   String toString() => value == null ? "-unknown-" : "#$value";
 }
 
 /**
- * Instances of the class `TypeState` represent the state of an object representing a type.
+ * The state of an object representing a type.
  */
 class TypeState extends InstanceState {
   /**
    * The element representing the type being modeled.
    */
   final Element _element;
 
   /**
-   * Initialize a newly created state to represent the given value.
-   *
-   * @param element the element representing the type being modeled
+   * Initialize a newly created state to represent the given [value].
    */
   TypeState(this._element);
 
   @override
   int get hashCode => _element == null ? 0 : _element.hashCode;
 
   @override
   String get typeName => "Type";
 
   @override
@@ skipping 27 matching lines @@
       return BoolState.from(_element == rightElement);
     } else if (rightOperand is DynamicState) {
       return BoolState.UNKNOWN_VALUE;
     }
     return BoolState.FALSE_STATE;
   }
 
   @override
   String toString() => _element == null ? "-unknown-" : _element.name;
 }