More comment clean-up

pkg/analyzer/lib/src/generated/engine.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;
 
 import "dart:math" as math;
@@ skipping 41 matching lines @@
  * The function may also throw an exception, in which case the corresponding
  * future will be completed with failure.
  *
  * Since this function is called while the state of analysis is being updated,
  * it should be free of side effects so that it doesn't cause reentrant
  * changes to the analysis state.
  */
 typedef T PendingFutureComputer<T>(SourceEntry sourceEntry);
 
 /**
- * Instances of the class `AnalysisCache` implement an LRU cache of information related to
- * analysis.
+ * An LRU cache of information related to analysis.
  */
 class AnalysisCache {
   /**
-   * A flag used to control whether trace information should be produced when the content of the
-   * cache is modified.
+   * A flag used to control whether trace information should be produced when
+   * the content of the cache is modified.
    */
   static bool _TRACE_CHANGES = false;
 
   /**
-   * An array containing the partitions of which this cache is comprised.
+   * A list containing the partitions of which this cache is comprised.
    */
   final List<CachePartition> _partitions;
 
   /**
-   * Initialize a newly created cache to have the given partitions. The partitions will be searched
-   * in the order in which they appear in the array, so the most specific partition (usually an
-   * [SdkCachePartition]) should be first and the most general (usually a
-   * [UniversalCachePartition]) last.
-   *
-   * @param partitions the partitions for the newly created cache
+   * Initialize a newly created cache to have the given [_partitions]. The
+   * partitions will be searched in the order in which they appear in the list,
+   * so the most specific partition (usually an [SdkCachePartition]) should be
+   * first and the most general (usually a [UniversalCachePartition]) last.
    */
   AnalysisCache(this._partitions);
 
   /**
-   * Return the number of entries in this cache that have an AST associated with them.
-   *
-   * @return the number of entries in this cache that have an AST associated with them
+   * Return the number of entries in this cache that have an AST associated with
+   * them.
    */
   int get astSize => _partitions[_partitions.length - 1].astSize;
 
   /**
    * Return information about each of the partitions in this cache.
-   *
-   * @return information about each of the partitions in this cache
    */
   List<AnalysisContextStatistics_PartitionData> get partitionData {
     int count = _partitions.length;
     List<AnalysisContextStatistics_PartitionData> data =
         new List<AnalysisContextStatistics_PartitionData>(count);
     for (int i = 0; i < count; i++) {
       CachePartition partition = _partitions[i];
       data[i] = new AnalysisContextStatisticsImpl_PartitionDataImpl(
           partition.astSize, partition.map.length);
     }
     return data;
   }
 
   /**
-   * Record that the AST associated with the given source was just read from the cache.
-   *
-   * @param source the source whose AST was accessed
+   * Record that the AST associated with the given [source] was just read from
+   * the cache.
    */
   void accessedAst(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         _partitions[i].accessedAst(source);
         return;
       }
     }
   }
 
   /**
-   * Return the entry associated with the given source.
-   *
-   * @param source the source whose entry is to be returned
-   * @return the entry associated with the given source
+   * Return the entry associated with the given [source].
    */
   SourceEntry get(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         return _partitions[i].get(source);
       }
     }
     //
     // We should never get to this point because the last partition should
     // always be a universal partition, except in the case of the SDK context,
     // in which case the source should always be part of the SDK.
     //
     return null;
   }
 
   /**
-   * Return context that owns the given source.
-   *
-   * @param source the source whose context is to be returned
-   * @return the context that owns the partition that contains the source
+   * Return context that owns the given [source].
    */
   InternalAnalysisContext getContextFor(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         return _partitions[i].context;
       }
     }
     //
     // We should never get to this point because the last partition should
     // always be a universal partition, except in the case of the SDK context,
     // in which case the source should always be part of the SDK.
     //
     AnalysisEngine.instance.logger.logInformation(
         "Could not find context for ${source.fullName}",
         new CaughtException(new AnalysisException(), null));
     return null;
   }
 
   /**
-   * Return an iterator returning all of the map entries mapping sources to cache entries.
-   *
-   * @return an iterator returning all of the map entries mapping sources to cache entries
+   * Return an iterator returning all of the map entries mapping sources to
+   * cache entries.
    */
   MapIterator<Source, SourceEntry> iterator() {
     int count = _partitions.length;
     List<Map<Source, SourceEntry>> maps = new List<Map>(count);
     for (int i = 0; i < count; i++) {
       maps[i] = _partitions[i].map;
     }
     return new MultipleMapIterator<Source, SourceEntry>(maps);
   }
 
   /**
-   * Associate the given entry with the given source.
-   *
-   * @param source the source with which the entry is to be associated
-   * @param entry the entry to be associated with the source
+   * Associate the given [entry] with the given [source].
    */
   void put(Source source, SourceEntry entry) {
     entry.fixExceptionState();
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         if (_TRACE_CHANGES) {
           try {
             SourceEntry oldEntry = _partitions[i].get(source);
             if (oldEntry == null) {
               AnalysisEngine.instance.logger.logInformation(
                   "Added a cache entry for '${source.fullName}'.");
             } else {
               AnalysisEngine.instance.logger.logInformation(
                   "Modified the cache entry for ${source.fullName}'. Diff = ${entry.getDiff(oldEntry)}");
             }
           } catch (exception) {
             // Ignored
             JavaSystem.currentTimeMillis();
           }
         }
         _partitions[i].put(source, entry);
         return;
       }
     }
   }
 
   /**
-   * Remove all information related to the given source from this cache.
-   *
-   * @param source the source to be removed
+   * Remove all information related to the given [source] from this cache.
    */
   void remove(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         if (_TRACE_CHANGES) {
           try {
             AnalysisEngine.instance.logger.logInformation(
                 "Removed the cache entry for ${source.fullName}'.");
           } catch (exception) {
             // Ignored
             JavaSystem.currentTimeMillis();
           }
         }
         _partitions[i].remove(source);
         return;
       }
     }
   }
 
   /**
-   * Record that the AST associated with the given source was just removed from the cache.
-   *
-   * @param source the source whose AST was removed
+   * Record that the AST associated with the given [source] was just removed
+   * from the cache.
    */
   void removedAst(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         _partitions[i].removedAst(source);
         return;
       }
     }
   }
 
   /**
    * Return the number of sources that are mapped to cache entries.
-   *
-   * @return the number of sources that are mapped to cache entries
    */
   int size() {
     int size = 0;
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       size += _partitions[i].size();
     }
     return size;
   }
 
   /**
-   * Record that the AST associated with the given source was just stored to the cache.
-   *
-   * @param source the source whose AST was stored
+   * Record that the AST associated with the given [source] was just stored to
+   * the cache.
    */
   void storedAst(Source source) {
     int count = _partitions.length;
     for (int i = 0; i < count; i++) {
       if (_partitions[i].contains(source)) {
         _partitions[i].storedAst(source);
         return;
       }
     }
   }
 }
 
 /**
- * The interface `AnalysisContext` defines the behavior of objects that represent a context in
- * which a single analysis can be performed and incrementally maintained. The context includes such
- * information as the version of the SDK being analyzed against as well as the package-root used to
- * resolve 'package:' URI's. (Both of which are known indirectly through the [SourceFactory
- ].)
+ * A context in which a single analysis can be performed and incrementally
+ * maintained. The context includes such information as the version of the SDK
+ * being analyzed against as well as the package-root used to resolve 'package:'
+ * URI's. (Both of which are known indirectly through the [SourceFactory].)
  *
- * An analysis context also represents the state of the analysis, which includes knowing which
- * sources have been included in the analysis (either directly or indirectly) and the results of the
- * analysis. Sources must be added and removed from the context using the method
- * [applyChanges], which is also used to notify the context when sources have been
- * modified and, consequently, previously known results might have been invalidated.
+ * An analysis context also represents the state of the analysis, which includes
+ * knowing which sources have been included in the analysis (either directly or
+ * indirectly) and the results of the analysis. Sources must be added and
+ * removed from the context using the method [applyChanges], which is also used
+ * to notify the context when sources have been modified and, consequently,
+ * previously known results might have been invalidated.
  *
- * There are two ways to access the results of the analysis. The most common is to use one of the
- * 'get' methods to access the results. The 'get' methods have the advantage that they will always
- * return quickly, but have the disadvantage that if the results are not currently available they
- * will return either nothing or in some cases an incomplete result. The second way to access
- * results is by using one of the 'compute' methods. The 'compute' methods will always attempt to
- * compute the requested results but might block the caller for a significant period of time.
+ * There are two ways to access the results of the analysis. The most common is
+ * to use one of the 'get' methods to access the results. The 'get' methods have
+ * the advantage that they will always return quickly, but have the disadvantage
+ * that if the results are not currently available they will return either
+ * nothing or in some cases an incomplete result. The second way to access
+ * results is by using one of the 'compute' methods. The 'compute' methods will
+ * always attempt to compute the requested results but might block the caller
+ * for a significant period of time.
  *
- * When results have been invalidated, have never been computed (as is the case for newly added
- * sources), or have been removed from the cache, they are <b>not</b> automatically recreated. They
- * will only be recreated if one of the 'compute' methods is invoked.
+ * When results have been invalidated, have never been computed (as is the case
+ * for newly added sources), or have been removed from the cache, they are
+ * <b>not</b> automatically recreated. They will only be recreated if one of the
+ * 'compute' methods is invoked.
  *
- * However, this is not always acceptable. Some clients need to keep the analysis results
- * up-to-date. For such clients there is a mechanism that allows them to incrementally perform
- * needed analysis and get notified of the consequent changes to the analysis results. This
- * mechanism is realized by the method [performAnalysisTask].
+ * However, this is not always acceptable. Some clients need to keep the
+ * analysis results up-to-date. For such clients there is a mechanism that
+ * allows them to incrementally perform needed analysis and get notified of the
+ * consequent changes to the analysis results. This mechanism is realized by the
+ * method [performAnalysisTask].
  *
- * Analysis engine allows for having more than one context. This can be used, for example, to
- * perform one analysis based on the state of files on disk and a separate analysis based on the
- * state of those files in open editors. It can also be used to perform an analysis based on a
- * proposed future state, such as the state after a refactoring.
+ * Analysis engine allows for having more than one context. This can be used,
+ * for example, to perform one analysis based on the state of files on disk and
+ * a separate analysis based on the state of those files in open editors. It can
+ * also be used to perform an analysis based on a proposed future state, such as
+ * the state after a refactoring.
  */
 abstract class AnalysisContext {
-
   /**
    * An empty list of contexts.
    */
   static const List<AnalysisContext> EMPTY_LIST = const <AnalysisContext>[];
 
   /**
-   * Return the set of analysis options controlling the behavior of this context. Clients should not
-   * modify the returned set of options. The options should only be set by invoking the method
-   * [setAnalysisOptions].
-   *
-   * @return the set of analysis options controlling the behavior of this context
+   * Return the set of analysis options controlling the behavior of this
+   * context. Clients should not modify the returned set of options. The options
+   * should only be set by invoking the method [setAnalysisOptions].
    */
   AnalysisOptions get analysisOptions;
 
   /**
-   * Set the set of analysis options controlling the behavior of this context to the given options.
-   * Clients can safely assume that all necessary analysis results have been invalidated.
-   *
-   * @param options the set of analysis options that will control the behavior of this context
+   * Set the set of analysis options controlling the behavior of this context to
+   * the given [options]. Clients can safely assume that all necessary analysis
+   * results have been invalidated.
    */
   void set analysisOptions(AnalysisOptions options);
 
   /**
-   * Set the order in which sources will be analyzed by [performAnalysisTask] to match the
-   * order of the sources in the given list. If a source that needs to be analyzed is not contained
-   * in the list, then it will be treated as if it were at the end of the list. If the list is empty
-   * (or `null`) then no sources will be given priority over other sources.
+   * Set the order in which sources will be analyzed by [performAnalysisTask] to
+   * match the order of the sources in the given list of [sources]. If a source
+   * that needs to be analyzed is not contained in the list, then it will be
+   * treated as if it were at the end of the list. If the list is empty (or
+   * `null`) then no sources will be given priority over other sources.
    *
-   * Changes made to the list after this method returns will <b>not</b> be reflected in the priority
-   * order.
-   *
-   * @param sources the sources to be given priority over other sources
+   * Changes made to the list after this method returns will <b>not</b> be
+   * reflected in the priority order.
    */
   void set analysisPriorityOrder(List<Source> sources);
 
   /**
    * Return the set of declared variables used when computing constant values.
-   *
-   * @return the set of declared variables used when computing constant values
    */
   DeclaredVariables get declaredVariables;
 
   /**
-   * Return an array containing all of the sources known to this context that represent HTML files.
-   * The contents of the array can be incomplete.
-   *
-   * @return the sources known to this context that represent HTML files
+   * Return a list containing all of the sources known to this context that
+   * represent HTML files. The contents of the list can be incomplete.
    */
   List<Source> get htmlSources;
 
   /**
    * Returns `true` if this context was disposed using [dispose].
-   *
-   * @return `true` if this context was disposed
    */
   bool get isDisposed;
 
   /**
-   * Return an array containing all of the sources known to this context that represent the defining
-   * compilation unit of a library that can be run within a browser. The sources that are returned
-   * represent libraries that have a 'main' method and are either referenced by an HTML file or
-   * import, directly or indirectly, a client-only library. The contents of the array can be
+   * Return a list containing all of the sources known to this context that
+   * represent the defining compilation unit of a library that can be run within
+   * a browser. The sources that are returned represent libraries that have a
+   * 'main' method and are either referenced by an HTML file or import, directly
+   * or indirectly, a client-only library. The contents of the list can be
    * incomplete.
-   *
-   * @return the sources known to this context that represent the defining compilation unit of a
-   *         library that can be run within a browser
    */
   List<Source> get launchableClientLibrarySources;
 
   /**
-   * Return an array containing all of the sources known to this context that represent the defining
-   * compilation unit of a library that can be run outside of a browser. The contents of the array
-   * can be incomplete.
-   *
-   * @return the sources known to this context that represent the defining compilation unit of a
-   *         library that can be run outside of a browser
+   * Return a list containing all of the sources known to this context that
+   * represent the defining compilation unit of a library that can be run
+   * outside of a browser. The contents of the list can be incomplete.
    */
   List<Source> get launchableServerLibrarySources;
 
   /**
-   * Return an array containing all of the sources known to this context that represent the defining
-   * compilation unit of a library. The contents of the array can be incomplete.
-   *
-   * @return the sources known to this context that represent the defining compilation unit of a
-   *         library
+   * Return a list containing all of the sources known to this context that
+   * represent the defining compilation unit of a library. The contents of the
+   * list can be incomplete.
    */
   List<Source> get librarySources;
 
   /**
    * Return a client-provided name used to identify this context, or `null` if
    * the client has not provided a name.
    */
   String get name;
 
   /**
    * Set the client-provided name used to identify this context to the given
    * [name].
    */
   set name(String name);
 
   /**
    * The stream that is notified when sources have been added or removed,
    * or the source's content has changed.
    */
   Stream<SourcesChangedEvent> get onSourcesChanged;
 
   /**
-   * Return an array containing all of the sources known to this context and their resolution state
-   * is not valid or flush. So, these sources are not safe to update during refactoring, because we
-   * may be don't know all the references in them.
-   *
-   * @return the sources known to this context and are not safe for refactoring
+   * Return a list containing all of the sources known to this context whose
+   * state is neither valid or flushed. These sources are not safe to update
+   * during refactoring, because we might not know all the references in them.
    */
   List<Source> get refactoringUnsafeSources;
 
   /**
-   * Return the source factory used to create the sources that can be analyzed in this context.
-   *
-   * @return the source factory used to create the sources that can be analyzed in this context
+   * Return the source factory used to create the sources that can be analyzed
+   * in this context.
    */
   SourceFactory get sourceFactory;
 
   /**
-   * Set the source factory used to create the sources that can be analyzed in this context to the
-   * given source factory. Clients can safely assume that all analysis results have been
-   * invalidated.
-   *
-   * @param factory the source factory used to create the sources that can be analyzed in this
-   *          context
+   * Set the source factory used to create the sources that can be analyzed in
+   * this context to the given source [factory]. Clients can safely assume that
+   * all analysis results have been invalidated.
    */
   void set sourceFactory(SourceFactory factory);
 
   /**
-   * Return an array containing all of the sources known to this context.
-   *
-   * @return all of the sources known to this context
+   * Return a list containing all of the sources known to this context.
    */
   List<Source> get sources;
 
   /**
-   * Returns a type provider for this context or throws [AnalysisException] if
-   * `dart:core` or `dart:async` cannot be resolved.
+   * Return a type provider for this context or throw [AnalysisException] if
+   * either `dart:core` or `dart:async` cannot be resolved.
    */
   TypeProvider get typeProvider;
 
   /**
-   * Add the given listener to the list of objects that are to be notified when various analysis
-   * results are produced in this context.
-   *
-   * @param listener the listener to be added
+   * Add the given [listener] to the list of objects that are to be notified
+   * when various analysis results are produced in this context.
    */
   void addListener(AnalysisListener listener);
 
   /**
-   * Apply the given delta to change the level of analysis that will be performed for the sources
-   * known to this context.
-   *
-   * @param delta a description of the level of analysis that should be performed for some sources
+   * Apply the given [delta] to change the level of analysis that will be
+   * performed for the sources known to this context.
    */
   void applyAnalysisDelta(AnalysisDelta delta);
 
   /**
-   * Apply the changes specified by the given change set to this context. Any analysis results that
-   * have been invalidated by these changes will be removed.
-   *
-   * @param changeSet a description of the changes that are to be applied
+   * Apply the changes specified by the given [changeSet] to this context. Any
+   * analysis results that have been invalidated by these changes will be
+   * removed.
    */
   void applyChanges(ChangeSet changeSet);
 
   /**
-   * Return the documentation comment for the given element as it appears in the original source
-   * (complete with the beginning and ending delimiters) for block documentation comments, or lines
-   * starting with `"///"` and separated with `"\n"` characters for end-of-line
-   * documentation comments, or `null` if the element does not have a documentation comment
-   * associated with it. This can be a long-running operation if the information needed to access
-   * the comment is not cached.
+   * Return the documentation comment for the given [element] as it appears in
+   * the original source (complete with the beginning and ending delimiters) for
+   * block documentation comments, or lines starting with `"///"` and separated
+   * with `"\n"` characters for end-of-line documentation comments, or `null` if
+   * the element does not have a documentation comment associated with it. This
+   * can be a long-running operation if the information needed to access the
+   * comment is not cached.
+   *
+   * Throws an [AnalysisException] if the documentation comment could not be
+   * determined because the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param element the element whose documentation comment is to be returned
-   * @return the element's documentation comment
-   * @throws AnalysisException if the documentation comment could not be determined because the
-   *           analysis could not be performed
    */
   String computeDocumentationComment(Element element);
 
   /**
-   * Return an array containing all of the errors associated with the given source. If the errors
-   * are not already known then the source will be analyzed in order to determine the errors
-   * associated with it.
+   * Return a list containing all of the errors associated with the given
+   * [source]. If the errors are not already known then the source will be
+   * analyzed in order to determine the errors associated with it.
+   *
+   * Throws an [AnalysisException] if the errors could not be determined because
+   * the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param source the source whose errors are to be returned
-   * @return all of the errors associated with the given source
-   * @throws AnalysisException if the errors could not be determined because the analysis could not
-   *           be performed
    * See [getErrors].
    */
   List<AnalysisError> computeErrors(Source source);
 
   /**
-   * Return the element model corresponding to the HTML file defined by the given source. If the
-   * element model does not yet exist it will be created. The process of creating an element model
-   * for an HTML file can be long-running, depending on the size of the file and the number of
-   * libraries that are defined in it (via script tags) that also need to have a model built for
-   * them.
+   * Return the element model corresponding to the HTML file defined by the
+   * given [source]. If the element model does not yet exist it will be created.
+   * The process of creating an element model for an HTML file can be
+   * long-running, depending on the size of the file and the number of libraries
+   * that are defined in it (via script tags) that also need to have a model
+   * built for them.
+   *
+   * Throws AnalysisException if the element model could not be determined
+   * because the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param source the source defining the HTML file whose element model is to be returned
-   * @return the element model corresponding to the HTML file defined by the given source
-   * @throws AnalysisException if the element model could not be determined because the analysis
-   *           could not be performed
    * See [getHtmlElement].
    */
   HtmlElement computeHtmlElement(Source source);
 
   /**
-   * Return the kind of the given source, computing it's kind if it is not already known. Return
-   * [SourceKind.UNKNOWN] if the source is not contained in this context.
+   * Return the kind of the given [source], computing it's kind if it is not
+   * already known. Return [SourceKind.UNKNOWN] if the source is not contained
+   * in this context.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param source the source whose kind is to be returned
-   * @return the kind of the given source
    * See [getKindOf].
    */
   SourceKind computeKindOf(Source source);
 
   /**
-   * Return the element model corresponding to the library defined by the given source. If the
-   * element model does not yet exist it will be created. The process of creating an element model
-   * for a library can long-running, depending on the size of the library and the number of
-   * libraries that are imported into it that also need to have a model built for them.
+   * Return the element model corresponding to the library defined by the given
+   * [source]. If the element model does not yet exist it will be created. The
+   * process of creating an element model for a library can long-running,
+   * depending on the size of the library and the number of libraries that are
+   * imported into it that also need to have a model built for them.
+   *
+   * Throws an [AnalysisException] if the element model could not be determined
+   * because the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param source the source defining the library whose element model is to be returned
-   * @return the element model corresponding to the library defined by the given source
-   * @throws AnalysisException if the element model could not be determined because the analysis
-   *           could not be performed
    * See [getLibraryElement].
    */
   LibraryElement computeLibraryElement(Source source);
 
   /**
-   * Return the line information for the given source, or `null` if the source is not of a
-   * recognized kind (neither a Dart nor HTML file). If the line information was not previously
-   * known it will be created. The line information is used to map offsets from the beginning of the
-   * source to line and column pairs.
+   * Return the line information for the given [source], or `null` if the source
+   * is not of a recognized kind (neither a Dart nor HTML file). If the line
+   * information was not previously known it will be created. The line
+   * information is used to map offsets from the beginning of the source to line
+   * and column pairs.
+   *
+   * Throws an [AnalysisException] if the line information could not be
+   * determined because the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param source the source whose line information is to be returned
-   * @return the line information for the given source
-   * @throws AnalysisException if the line information could not be determined because the analysis
-   *           could not be performed
    * See [getLineInfo].
    */
   LineInfo computeLineInfo(Source source);
 
   /**
    * Return a future which will be completed with the fully resolved AST for a
    * single compilation unit within the given library, once that AST is up to
    * date.
    *
    * If the resolved AST can't be computed for some reason, the future will be
    * completed with an error.  One possible error is AnalysisNotScheduledError,
    * which means that the resolved AST can't be computed because the given
    * source file is not scheduled to be analyzed within the context of the
    * given library.
    */
   CancelableFuture<CompilationUnit> computeResolvedCompilationUnitAsync(
       Source source, Source librarySource);
 
   /**
    * Notifies the context that the client is going to stop using this context.
    */
   void dispose();
 
   /**
-   * Return `true` if the given source exists.
+   * Return `true` if the given [source] exists.
    *
-   * This method should be used rather than the method [Source.exists] because contexts can
-   * have local overrides of the content of a source that the source is not aware of and a source
-   * with local content is considered to exist even if there is no file on disk.
-   *
-   * @param source the source whose modification stamp is to be returned
-   * @return `true` if the source exists
+   * This method should be used rather than the method [Source.exists] because
+   * contexts can have local overrides of the content of a source that the
+   * source is not aware of and a source with local content is considered to
+   * exist even if there is no file on disk.
    */
   bool exists(Source source);
 
   /**
-   * Return the element model corresponding to the compilation unit defined by the given source in
-   * the library defined by the given source, or `null` if the element model does not
-   * currently exist or if the library cannot be analyzed for some reason.
-   *
-   * @param unitSource the source of the compilation unit
-   * @param librarySource the source of the defining compilation unit of the library containing the
-   *          compilation unit
-   * @return the element model corresponding to the compilation unit defined by the given source
+   * Return the element model corresponding to the compilation unit defined by
+   * the given [unitSource] in the library defined by the given [librarySource],
+   * or `null` if the element model does not currently exist or if the library
+   * cannot be analyzed for some reason.
    */
   CompilationUnitElement getCompilationUnitElement(
       Source unitSource, Source librarySource);
 
   /**
-   * Get the contents and timestamp of the given source.
+   * Return the contents and timestamp of the given [source].
    *
-   * This method should be used rather than the method [Source.getContents] because contexts
-   * can have local overrides of the content of a source that the source is not aware of.
-   *
-   * @param source the source whose content is to be returned
-   * @return the contents and timestamp of the source
-   * @throws Exception if the contents of the source could not be accessed
+   * This method should be used rather than the method [Source.getContents]
+   * because contexts can have local overrides of the content of a source that
+   * the source is not aware of.
    */
   TimestampedData<String> getContents(Source source);
 
   /**
-   * Return the element referenced by the given location, or `null` if the element is not
-   * immediately available or if there is no element with the given location. The latter condition
-   * can occur, for example, if the location describes an element from a different context or if the
-   * element has been removed from this context as a result of some change since it was originally
-   * obtained.
-   *
-   * @param location the reference describing the element to be returned
-   * @return the element referenced by the given location
+   * Return the element referenced by the given [location], or `null` if the
+   * element is not immediately available or if there is no element with the
+   * given location. The latter condition can occur, for example, if the
+   * location describes an element from a different context or if the element
+   * has been removed from this context as a result of some change since it was
+   * originally obtained.
    */
   Element getElement(ElementLocation location);
 
   /**
-   * Return an analysis error info containing the array of all of the errors and the line info
-   * associated with the given source. The array of errors will be empty if the source is not known
-   * to this context or if there are no errors in the source. The errors contained in the array can
-   * be incomplete.
+   * Return an analysis error info containing the list of all of the errors and
+   * the line info associated with the given [source]. The list of errors will
+   * be empty if the source is not known to this context or if there are no
+   * errors in the source. The errors contained in the list can be incomplete.
    *
-   * @param source the source whose errors are to be returned
-   * @return all of the errors associated with the given source and the line info
    * See [computeErrors].
    */
   AnalysisErrorInfo getErrors(Source source);
 
   /**
-   * Return the element model corresponding to the HTML file defined by the given source, or
-   * `null` if the source does not represent an HTML file, the element representing the file
-   * has not yet been created, or the analysis of the HTML file failed for some reason.
+   * Return the element model corresponding to the HTML file defined by the
+   * given [source], or `null` if the source does not represent an HTML file,
+   * the element representing the file has not yet been created, or the analysis
+   * of the HTML file failed for some reason.
    *
-   * @param source the source defining the HTML file whose element model is to be returned
-   * @return the element model corresponding to the HTML file defined by the given source
    * See [computeHtmlElement].
    */
   HtmlElement getHtmlElement(Source source);
 
   /**
-   * Return the sources for the HTML files that reference the given compilation unit. If the source
-   * does not represent a Dart source or is not known to this context, the returned array will be
-   * empty. The contents of the array can be incomplete.
-   *
-   * @param source the source referenced by the returned HTML files
-   * @return the sources for the HTML files that reference the given compilation unit
+   * Return the sources for the HTML files that reference the compilation unit
+   * with the given [source]. If the source does not represent a Dart source or
+   * is not known to this context, the returned list will be empty. The contents
+   * of the list can be incomplete.
    */
   List<Source> getHtmlFilesReferencing(Source source);
 
   /**
-   * Return the kind of the given source, or `null` if the kind is not known to this context.
+   * Return the kind of the given [source], or `null` if the kind is not known
+   * to this context.
    *
-   * @param source the source whose kind is to be returned
-   * @return the kind of the given source
    * See [computeKindOf].
    */
   SourceKind getKindOf(Source source);
 
   /**
-   * Return the sources for the defining compilation units of any libraries of which the given
-   * source is a part. The array will normally contain a single library because most Dart sources
-   * are only included in a single library, but it is possible to have a part that is contained in
-   * multiple identically named libraries. If the source represents the defining compilation unit of
-   * a library, then the returned array will contain the given source as its only element. If the
-   * source does not represent a Dart source or is not known to this context, the returned array
-   * will be empty. The contents of the array can be incomplete.
-   *
-   * @param source the source contained in the returned libraries
-   * @return the sources for the libraries containing the given source
+   * Return the sources for the defining compilation units of any libraries of
+   * which the given [source] is a part. The list will normally contain a single
+   * library because most Dart sources are only included in a single library,
+   * but it is possible to have a part that is contained in multiple identically
+   * named libraries. If the source represents the defining compilation unit of
+   * a library, then the returned list will contain the given source as its only
+   * element. If the source does not represent a Dart source or is not known to
+   * this context, the returned list will be empty. The contents of the list can
+   * be incomplete.
    */
   List<Source> getLibrariesContaining(Source source);
 
   /**
-   * Return the sources for the defining compilation units of any libraries that depend on the given
-   * library. One library depends on another if it either imports or exports that library.
-   *
-   * @param librarySource the source for the defining compilation unit of the library being depended
-   *          on
-   * @return the sources for the libraries that depend on the given library
+   * Return the sources for the defining compilation units of any libraries that
+   * depend on the library defined by the given [librarySource]. One library
+   * depends on another if it either imports or exports that library.
    */
   List<Source> getLibrariesDependingOn(Source librarySource);
 
   /**
-   * Return the sources for the defining compilation units of any libraries that are referenced from
-   * the given HTML file.
-   *
-   * @param htmlSource the source for the HTML file
-   * @return the sources for the libraries that are referenced by the given HTML file
+   * Return the sources for the defining compilation units of any libraries that
+   * are referenced from the HTML file defined by the given [htmlSource].
    */
   List<Source> getLibrariesReferencedFromHtml(Source htmlSource);
 
   /**
-   * Return the element model corresponding to the library defined by the given source, or
-   * `null` if the element model does not currently exist or if the library cannot be analyzed
-   * for some reason.
-   *
-   * @param source the source defining the library whose element model is to be returned
-   * @return the element model corresponding to the library defined by the given source
+   * Return the element model corresponding to the library defined by the given
+   * [source], or `null` if the element model does not currently exist or if the
+   * library cannot be analyzed for some reason.
    */
   LibraryElement getLibraryElement(Source source);
 
   /**
-   * Return the line information for the given source, or `null` if the line information is
-   * not known. The line information is used to map offsets from the beginning of the source to line
-   * and column pairs.
+   * Return the line information for the given [source], or `null` if the line
+   * information is not known. The line information is used to map offsets from
+   * the beginning of the source to line and column pairs.
    *
-   * @param source the source whose line information is to be returned
-   * @return the line information for the given source
    * See [computeLineInfo].
    */
   LineInfo getLineInfo(Source source);
 
   /**
    * Return the modification stamp for the [source], or a negative value if the
    * source does not exist. A modification stamp is a non-negative integer with
    * the property that if the contents of the source have not been modified
    * since the last time the modification stamp was accessed then the same value
    * will be returned, but if the contents of the source have been modified one
    * or more times (even if the net change is zero) the stamps will be different.
    *
    * This method should be used rather than the method
    * [Source.getModificationStamp] because contexts can have local overrides of
    * the content of a source that the source is not aware of.
    */
   int getModificationStamp(Source source);
 
   /**
-   * Return a fully resolved AST for a single compilation unit within the given library, or
-   * `null` if the resolved AST is not already computed.
+   * Return a fully resolved AST for the compilation unit defined by the given
+   * [unitSource] within the given [library], or `null` if the resolved AST is
+   * not already computed.
    *
-   * @param unitSource the source of the compilation unit
-   * @param library the library containing the compilation unit
-   * @return a fully resolved AST for the compilation unit
    * See [resolveCompilationUnit].
    */
   CompilationUnit getResolvedCompilationUnit(
       Source unitSource, LibraryElement library);
 
   /**
-   * Return a fully resolved AST for a single compilation unit within the given library, or
+   * Return a fully resolved AST for the compilation unit defined by the given
+   * [unitSource] within the library defined by the given [librarySource], or
    * `null` if the resolved AST is not already computed.
    *
-   * @param unitSource the source of the compilation unit
-   * @param librarySource the source of the defining compilation unit of the library containing the
-   *          compilation unit
-   * @return a fully resolved AST for the compilation unit
-   * See [resolveCompilationUnit].
+   * See [resolveCompilationUnit2].
    */
   CompilationUnit getResolvedCompilationUnit2(
       Source unitSource, Source librarySource);
 
   /**
-   * Return a fully resolved HTML unit, or `null` if the resolved unit is not already
-   * computed.
+   * Return the fully resolved HTML unit defined by the given [htmlSource], or
+   * `null` if the resolved unit is not already computed.
    *
-   * @param htmlSource the source of the HTML unit
-   * @return a fully resolved HTML unit
    * See [resolveHtmlUnit].
    */
   ht.HtmlUnit getResolvedHtmlUnit(Source htmlSource);
 
   /**
    * Return a list of the sources being analyzed in this context whose full path
    * is equal to the given [path].
    */
   List<Source> getSourcesWithFullName(String path);
 
   /**
-   * Return `true` if the given source is known to be the defining compilation unit of a
-   * library that can be run on a client (references 'dart:html', either directly or indirectly).
+   * Return `true` if the given [librarySource] is known to be the defining
+   * compilation unit of a library that can be run on a client (references
+   * 'dart:html', either directly or indirectly).
    *
-   * <b>Note:</b> In addition to the expected case of returning `false` if the source is known
-   * to be a library that cannot be run on a client, this method will also return `false` if
-   * the source is not known to be a library or if we do not know whether it can be run on a client.
-   *
-   * @param librarySource the source being tested
-   * @return `true` if the given source is known to be a library that can be run on a client
+   * <b>Note:</b> In addition to the expected case of returning `false` if the
+   * source is known to be a library that cannot be run on a client, this method
+   * will also return `false` if the source is not known to be a library or if
+   * we do not know whether it can be run on a client.
    */
   bool isClientLibrary(Source librarySource);
 
   /**
-   * Return `true` if the given source is known to be the defining compilation unit of a
-   * library that can be run on the server (does not reference 'dart:html', either directly or
-   * indirectly).
+   * Return `true` if the given [librarySource] is known to be the defining
+   * compilation unit of a library that can be run on the server (does not
+   * reference 'dart:html', either directly or indirectly).
    *
-   * <b>Note:</b> In addition to the expected case of returning `false` if the source is known
-   * to be a library that cannot be run on the server, this method will also return `false` if
-   * the source is not known to be a library or if we do not know whether it can be run on the
-   * server.
-   *
-   * @param librarySource the source being tested
-   * @return `true` if the given source is known to be a library that can be run on the server
+   * <b>Note:</b> In addition to the expected case of returning `false` if the
+   * source is known to be a library that cannot be run on the server, this
+   * method will also return `false` if the source is not known to be a library
+   * or if we do not know whether it can be run on the server.
    */
   bool isServerLibrary(Source librarySource);
 
   /**
-   * Parse a single source to produce an AST structure. The resulting AST structure may or may not
-   * be resolved, and may have a slightly different structure depending upon whether it is resolved.
+   * Parse the content of the given [source] to produce an AST structure. The
+   * resulting AST structure may or may not be resolved, and may have a slightly
+   * different structure depending upon whether it is resolved.
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source to be parsed
-   * @return the AST structure representing the content of the source
-   * @throws AnalysisException if the analysis could not be performed
    */
   CompilationUnit parseCompilationUnit(Source source);
 
   /**
-   * Parse a single HTML source to produce an AST structure. The resulting HTML AST structure may or
-   * may not be resolved, and may have a slightly different structure depending upon whether it is
-   * resolved.
+   * Parse a single HTML [source] to produce an AST structure. The resulting
+   * HTML AST structure may or may not be resolved, and may have a slightly
+   * different structure depending upon whether it is resolved.
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the HTML source to be parsed
-   * @return the parse result (not `null`)
-   * @throws AnalysisException if the analysis could not be performed
    */
   ht.HtmlUnit parseHtmlUnit(Source source);
 
   /**
-   * Perform the next unit of work required to keep the analysis results up-to-date and return
-   * information about the consequent changes to the analysis results. This method can be long
-   * running.
-   *
-   * @return the results of performing the analysis
+   * Perform the next unit of work required to keep the analysis results
+   * up-to-date and return information about the consequent changes to the
+   * analysis results. This method can be long running.
    */
   AnalysisResult performAnalysisTask();
 
   /**
-   * Remove the given listener from the list of objects that are to be notified when various
-   * analysis results are produced in this context.
-   *
-   * @param listener the listener to be removed
+   * Remove the given [listener] from the list of objects that are to be
+   * notified when various analysis results are produced in this context.
    */
   void removeListener(AnalysisListener listener);
 
   /**
-   * Parse and resolve a single source within the given context to produce a fully resolved AST.
+   * Return a fully resolved AST for the compilation unit defined by the given
+   * [unitSource] within the given [library].
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param unitSource the source to be parsed and resolved
-   * @param library the library containing the source to be resolved
-   * @return the result of resolving the AST structure representing the content of the source in the
-   *         context of the given library
-   * @throws AnalysisException if the analysis could not be performed
    * See [getResolvedCompilationUnit].
    */
   CompilationUnit resolveCompilationUnit(
       Source unitSource, LibraryElement library);
 
   /**
-   * Parse and resolve a single source within the given context to produce a fully resolved AST.
-   * Return the resolved AST structure, or `null` if the source could not be either parsed or
-   * resolved.
+   * Return a fully resolved AST for the compilation unit defined by the given
+   * [unitSource] within the library defined by the given [librarySource].
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
    *
-   * @param unitSource the source to be parsed and resolved
-   * @param librarySource the source of the defining compilation unit of the library containing the
-   *          source to be resolved
-   * @return the result of resolving the AST structure representing the content of the source in the
-   *         context of the given library
-   * @throws AnalysisException if the analysis could not be performed
-   * See [getResolvedCompilationUnit].
+   * See [getResolvedCompilationUnit2].
    */
   CompilationUnit resolveCompilationUnit2(
       Source unitSource, Source librarySource);
 
   /**
-   * Parse and resolve a single source within the given context to produce a fully resolved AST.
+   * Parse and resolve a single [htmlSource] within the given context to produce
+   * a fully resolved AST.
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param htmlSource the source to be parsed and resolved
-   * @return the result of resolving the AST structure representing the content of the source
-   * @throws AnalysisException if the analysis could not be performed
    */
   ht.HtmlUnit resolveHtmlUnit(Source htmlSource);
 
   /**
-   * Set the contents of the given source to the given contents and mark the source as having
-   * changed. The additional offset and length information is used by the context to determine what
-   * reanalysis is necessary.
-   *
-   * @param source the source whose contents are being overridden
-   * @param contents the text to replace the range in the current contents
-   * @param offset the offset into the current contents
-   * @param oldLength the number of characters in the original contents that were replaced
-   * @param newLength the number of characters in the replacement text
+   * Set the contents of the given [source] to the given [contents] and mark the
+   * source as having changed. The additional [offset] and [length] information
+   * is used by the context to determine what reanalysis is necessary.
    */
   void setChangedContents(
       Source source, String contents, int offset, int oldLength, int newLength);
 
   /**
-   * Set the contents of the given source to the given contents and mark the source as having
-   * changed. This has the effect of overriding the default contents of the source. If the contents
-   * are `null` the override is removed so that the default contents will be returned.
-   *
-   * @param source the source whose contents are being overridden
-   * @param contents the new contents of the source
+   * Set the contents of the given [source] to the given [contents] and mark the
+   * source as having changed. This has the effect of overriding the default
+   * contents of the source. If the contents are `null` the override is removed
+   * so that the default contents will be returned.
    */
   void setContents(Source source, String contents);
 }
 
 /**
- * Instances of the class `AnalysisContextImpl` implement an [AnalysisContext].
+ * An [AnalysisContext].
  */
 class AnalysisContextImpl implements InternalAnalysisContext {
   /**
-   * The difference between the maximum cache size and the maximum priority order size. The priority
-   * list must be capped so that it is less than the cache size. Failure to do so can result in an
-   * infinite loop in performAnalysisTask() because re-caching one AST structure can cause another
-   * priority source's AST structure to be flushed.
+   * The difference between the maximum cache size and the maximum priority
+   * order size. The priority list must be capped so that it is less than the
+   * cache size. Failure to do so can result in an infinite loop in
+   * performAnalysisTask() because re-caching one AST structure can cause
+   * another priority source's AST structure to be flushed.
    */
   static int _PRIORITY_ORDER_SIZE_DELTA = 4;
 
   /**
-   * A flag indicating whether trace output should be produced as analysis tasks are performed. Used
-   * for debugging.
+   * A flag indicating whether trace output should be produced as analysis tasks
+   * are performed. Used for debugging.
    */
   static bool _TRACE_PERFORM_TASK = false;
 
   /**
    * The next context identifier.
    */
   static int _NEXT_ID = 0;
 
   /**
    * The unique identifier of this context.
@@ skipping 27 matching lines @@
    * A flag indicating whether this context is disposed.
    */
   bool _disposed = false;
 
   /**
    * A cache of content used to override the default content of a source.
    */
   ContentCache _contentCache = new ContentCache();
 
   /**
-   * The source factory used to create the sources that can be analyzed in this context.
+   * The source factory used to create the sources that can be analyzed in this
+   * context.
    */
   SourceFactory _sourceFactory;
 
   /**
    * The set of declared variables used when computing constant values.
    */
   DeclaredVariables _declaredVariables = new DeclaredVariables();
 
   /**
    * A source representing the core library.
    */
   Source _coreLibrarySource;
 
   /**
    * A source representing the async library.
    */
   Source _asyncLibrarySource;
 
   /**
-   * The partition that contains analysis results that are not shared with other contexts.
+   * The partition that contains analysis results that are not shared with other
+   * contexts.
    */
   CachePartition _privatePartition;
 
   /**
-   * A table mapping the sources known to the context to the information known about the source.
+   * A table mapping the sources known to the context to the information known
+   * about the source.
    */
   AnalysisCache _cache;
 
   /**
-   * An array containing sources for which data should not be flushed.
+   * A list containing sources for which data should not be flushed.
    */
   List<Source> _priorityOrder = Source.EMPTY_ARRAY;
 
   /**
    * A map from all sources for which there are futures pending to a list of
    * the corresponding PendingFuture objects.  These sources will be analyzed
    * in the same way as priority sources, except with higher priority.
    *
    * TODO(paulberry): since the size of this map is not constrained (as it is
    * for _priorityOrder), we run the risk of creating an analysis loop if
    * re-caching one AST structure causes the AST structure for another source
    * with pending futures to be flushed.  However, this is unlikely to happen
    * in practice since sources are removed from this hash set as soon as their
    * futures have completed.
    */
   HashMap<Source, List<PendingFuture>> _pendingFutureSources =
       new HashMap<Source, List<PendingFuture>>();
 
   /**
-   * An array containing sources whose AST structure is needed in order to resolve the next library
-   * to be resolved.
+   * A list containing sources whose AST structure is needed in order to resolve
+   * the next library to be resolved.
    */
   HashSet<Source> _neededForResolution = null;
 
   /**
-   * A table mapping sources to the change notices that are waiting to be returned related to that
-   * source.
+   * A table mapping sources to the change notices that are waiting to be
+   * returned related to that source.
    */
   HashMap<Source, ChangeNoticeImpl> _pendingNotices =
       new HashMap<Source, ChangeNoticeImpl>();
 
   /**
    * The object used to record the results of performing an analysis task.
    */
   AnalysisContextImpl_AnalysisTaskResultRecorder _resultRecorder;
 
   /**
-   * Cached information used in incremental analysis or `null` if none. Synchronize against
-   * [cacheLock] before accessing this field.
+   * Cached information used in incremental analysis or `null` if none.
    */
   IncrementalAnalysisCache _incrementalAnalysisCache;
 
   /**
    * The [TypeProvider] for this context, `null` if not yet created.
    */
   TypeProvider _typeProvider;
 
   /**
    * The object used to manage the list of sources that need to be analyzed.
    */
   WorkManager _workManager = new WorkManager();
 
   /**
    * The [Stopwatch] of the current "perform tasks cycle".
    */
   Stopwatch _performAnalysisTaskStopwatch;
 
   /**
    * The controller for sending [SourcesChangedEvent]s.
    */
   StreamController<SourcesChangedEvent> _onSourcesChangedController;
 
   /**
-   * The listeners that are to be notified when various analysis results are produced in this
-   * context.
+   * The listeners that are to be notified when various analysis results are
+   * produced in this context.
    */
   List<AnalysisListener> _listeners = new List<AnalysisListener>();
 
   /**
-   * The most recently incrementally resolved [Source].
-   * Is null when it was already validated, or the most recent change was
-   * not incrementally resolved.
+   * The most recently incrementally resolved source, or `null` when it was
+   * already validated, or the most recent change was not incrementally resolved.
    */
   Source incrementalResolutionValidation_lastUnitSource;
 
   /**
-   * The most recently incrementally resolved library [Source].
-   * Is null when it was already validated, or the most recent change was
-   * not incrementally resolved.
+   * The most recently incrementally resolved library source, or `null` when it
+   * was already validated, or the most recent change was not incrementally
+   * resolved.
    */
   Source incrementalResolutionValidation_lastLibrarySource;
 
   /**
    * The result of incremental resolution result of
    * [incrementalResolutionValidation_lastSource].
    */
   CompilationUnit incrementalResolutionValidation_lastUnit;
 
-  /** A factory to override how [ResolverVisitor] is created. */
+  /**
+   * A factory to override how the [ResolverVisitor] is created.
+   */
   ResolverVisitorFactory resolverVisitorFactory;
 
-  /** A factory to override how [TypeResolverVisitor] is created. */
+  /**
+   * A factory to override how the [TypeResolverVisitor] is created.
+   */
   TypeResolverVisitorFactory typeResolverVisitorFactory;
 
   /**
    * Initialize a newly created analysis context.
    */
   AnalysisContextImpl() {
     _resultRecorder = new AnalysisContextImpl_AnalysisTaskResultRecorder(this);
     _privatePartition = new UniversalCachePartition(this,
         AnalysisOptionsImpl.DEFAULT_CACHE_SIZE,
         new AnalysisContextImpl_ContextRetentionPolicy(this));
@@ skipping 129 matching lines @@
 //          }
       }
     }
     return sources;
   }
 
   @override
   List<Source> get librarySources => _getSources(SourceKind.LIBRARY);
 
   /**
-   * Look through the cache for a task that needs to be performed. Return the task that was found,
-   * or `null` if there is no more work to be done.
-   *
-   * @return the next task that needs to be performed
+   * Look through the cache for a task that needs to be performed. Return the
+   * task that was found, or `null` if there is no more work to be done.
    */
   AnalysisTask get nextAnalysisTask {
     bool hintsEnabled = _options.hint;
     bool lintsEnabled = _options.lint;
     bool hasBlockedTask = false;
     //
     // Look for incremental analysis
     //
     if (_incrementalAnalysisCache != null &&
         _incrementalAnalysisCache.hasWork) {
@@ skipping 176 matching lines @@
   List<Source> get sources {
     List<Source> sources = new List<Source>();
     MapIterator<Source, SourceEntry> iterator = _cache.iterator();
     while (iterator.moveNext()) {
       sources.add(iterator.key);
     }
     return sources;
   }
 
   /**
-   * Return a list of the sources that would be processed by [performAnalysisTask]. This
-   * method duplicates, and must therefore be kept in sync with, [getNextAnalysisTask].
-   * This method is intended to be used for testing purposes only.
-   *
-   * @return a list of the sources that would be processed by [performAnalysisTask]
+   * Return a list of the sources that would be processed by
+   * [performAnalysisTask]. This method duplicates, and must therefore be kept
+   * in sync with, [getNextAnalysisTask]. This method is intended to be used for
+   * testing purposes only.
    */
   List<Source> get sourcesNeedingProcessing {
     HashSet<Source> sources = new HashSet<Source>();
     bool hintsEnabled = _options.hint;
     bool lintsEnabled = _options.lint;
 
     //
     // Look for priority sources that need to be analyzed.
     //
     for (Source source in _priorityOrder) {
@@ skipping 324 matching lines @@
           throw sourceEntry.exception;
         }
         return sourceEntry.getValueInLibrary(
             DartEntry.RESOLVED_UNIT, librarySource);
       }
       throw new AnalysisNotScheduledError();
     });
   }
 
   /**
-   * Create an analysis cache based on the given source factory.
-   *
-   * @param factory the source factory containing the information needed to create the cache
-   * @return the cache that was created
+   * Create an analysis cache based on the given source [factory].
    */
   AnalysisCache createCacheFromSourceFactory(SourceFactory factory) {
     if (factory == null) {
       return new AnalysisCache(<CachePartition>[_privatePartition]);
     }
     DartSdk sdk = factory.dartSdk;
     if (sdk == null) {
       return new AnalysisCache(<CachePartition>[_privatePartition]);
     }
     return new AnalysisCache(<CachePartition>[
@@ skipping 322 matching lines @@
         return null;
       }
       if (identical(dartEntry.getValue(DartEntry.ELEMENT), library)) {
         dartEntry.setValue(DartEntry.PUBLIC_NAMESPACE, namespace);
       }
     }
     return namespace;
   }
 
   /**
-   * Return the cache entry associated with the given source, or `null` if there is no entry
-   * associated with the source.
-   *
-   * @param source the source for which a cache entry is being sought
-   * @return the source cache entry associated with the given source
+   * Return the cache entry associated with the given [source], or `null` if
+   * there is no entry associated with the source.
    */
   SourceEntry getReadableSourceEntryOrNull(Source source) => _cache.get(source);
 
   @override
   CompilationUnit getResolvedCompilationUnit(
       Source unitSource, LibraryElement library) {
     if (library == null) {
       return null;
     }
     return getResolvedCompilationUnit2(unitSource, library.source);
@@ skipping 494 matching lines @@
   }
 
   /**
    * Visit all entries of the content cache.
    */
   void visitContentCache(ContentCacheVisitor visitor) {
     _contentCache.accept(visitor);
   }
 
   /**
-   * Record that we have accessed the AST structure associated with the given source. At the moment,
-   * there is no differentiation between the parsed and resolved forms of the AST.
-   *
-   * @param source the source whose AST structure was accessed
+   * Record that we have accessed the AST structure associated with the given
+   * [source]. At the moment, there is no differentiation between the parsed and
+   * resolved forms of the AST.
    */
   void _accessedAst(Source source) {
     _cache.accessedAst(source);
   }
 
   /**
-   * Add all of the sources contained in the given source container to the given list of sources.
-   *
-   * Note: This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param sources the list to which sources are to be added
-   * @param container the source container containing the sources to be added to the list
+   * Add all of the sources contained in the given source [container] to the
+   * given list of [sources].
    */
   void _addSourcesInContainer(List<Source> sources, SourceContainer container) {
     MapIterator<Source, SourceEntry> iterator = _cache.iterator();
     while (iterator.moveNext()) {
       Source source = iterator.key;
       if (container.contains(source)) {
         sources.add(source);
       }
     }
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return a cache entry in which
-   * the state of the data represented by the given descriptor is either [CacheState.VALID] or
-   * [CacheStateERROR]. This method assumes that the data can be produced by generating hints
-   * for the library if the data is not already cached.
+   * Given the [unitSource] of a Dart file and the [librarySource] of the
+   * library that contains it, return a cache entry in which the state of the
+   * data represented by the given [descriptor] is either [CacheState.VALID] or
+   * [CacheState.ERROR]. This method assumes that the data can be produced by
+   * generating hints for the library if the data is not already cached. The
+   * [dartEntry] is the cache entry associated with the Dart file.
    *
-   * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be parsed.
    */
   DartEntry _cacheDartHintData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = dartEntry.getStateInLibrary(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information.
@@ skipping 27 matching lines @@
       }
       dartEntry = new GenerateDartHintsTask(
               this, units, getLibraryElement(librarySource))
           .perform(_resultRecorder) as DartEntry;
       state = dartEntry.getStateInLibrary(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return a cache entry in which
-   * the state of the data represented by the given descriptor is either [CacheState.VALID] or
-   * [CacheStateERROR]. This method assumes that the data can be produced by generating lints
-   * for the library if the data is not already cached.
+   * Given a source for a Dart file and the library that contains it, return a
+   * cache entry in which the state of the data represented by the given
+   * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
+   * assumes that the data can be produced by generating lints for the library
+   * if the data is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry _cacheDartLintData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = dartEntry.getStateInLibrary(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information.
@@ skipping 28 matching lines @@
       //TODO(pquitslund): revisit if we need all units or whether one will do
       dartEntry = new GenerateDartLintsTask(
               this, units, getLibraryElement(librarySource))
           .perform(_resultRecorder) as DartEntry;
       state = dartEntry.getStateInLibrary(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for a Dart file, return a cache entry in which the state of the data represented
-   * by the given descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This
-   * method assumes that the data can be produced by parsing the source if it is not already cached.
+   * Given a source for a Dart file, return a cache entry in which the state of
+   * the data represented by the given descriptor is either [CacheState.VALID]
+   * or [CacheState.ERROR]. This method assumes that the data can be produced by
+   * parsing the source if it is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry _cacheDartParseData(
       Source source, DartEntry dartEntry, DataDescriptor descriptor) {
     if (identical(descriptor, DartEntry.PARSED_UNIT)) {
       if (dartEntry.hasResolvableCompilationUnit) {
         return dartEntry;
       }
     }
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = dartEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information. Unless the modification date of the
       // source continues to change, this loop will eventually terminate.
       //
       dartEntry = _cacheDartScanData(source, dartEntry, DartEntry.TOKEN_STREAM);
       dartEntry = new ParseDartTask(this, source,
               dartEntry.getValue(DartEntry.TOKEN_STREAM),
               dartEntry.getValue(SourceEntry.LINE_INFO))
           .perform(_resultRecorder) as DartEntry;
       state = dartEntry.getState(descriptor);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return a cache entry in which
-   * the state of the data represented by the given descriptor is either [CacheState.VALID] or
-   * [CacheState.ERROR]. This method assumes that the data can be produced by resolving the
-   * source in the context of the library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return a
+   * cache entry in which the state of the data represented by the given
+   * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
+   * assumes that the data can be produced by resolving the source in the
+   * context of the library if it is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry _cacheDartResolutionData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = (identical(descriptor, DartEntry.ELEMENT))
         ? dartEntry.getState(descriptor)
         : dartEntry.getStateInLibrary(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information. Unless the modification date of the
       // source continues to change, this loop will eventually terminate.
       //
       // TODO(brianwilkerson) As an optimization, if we already have the
       // element model for the library we can use ResolveDartUnitTask to produce
       // the resolved AST structure much faster.
       dartEntry = new ResolveDartLibraryTask(this, unitSource, librarySource)
           .perform(_resultRecorder) as DartEntry;
       state = (identical(descriptor, DartEntry.ELEMENT))
           ? dartEntry.getState(descriptor)
           : dartEntry.getStateInLibrary(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for a Dart file, return a cache entry in which the state of the data represented
-   * by the given descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This
-   * method assumes that the data can be produced by scanning the source if it is not already
-   * cached.
+   * Given a source for a Dart file, return a cache entry in which the state of
+   * the data represented by the given descriptor is either [CacheState.VALID]
+   * or [CacheState.ERROR]. This method assumes that the data can be produced by
+   * scanning the source if it is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be scanned
    */
   DartEntry _cacheDartScanData(
       Source source, DartEntry dartEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = dartEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information. Unless the modification date of the
@@ skipping 12 matching lines @@
       } catch (exception, stackTrace) {
         throw new AnalysisException(
             "Exception", new CaughtException(exception, stackTrace));
       }
       state = dartEntry.getState(descriptor);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return a cache entry in which
-   * the state of the data represented by the given descriptor is either [CacheState.VALID] or
-   * [CacheState.ERROR]. This method assumes that the data can be produced by verifying the
-   * source in the given library if the data is not already cached.
+   * Given a source for a Dart file and the library that contains it, return a
+   * cache entry in which the state of the data represented by the given
+   * descriptor is either [CacheState.VALID] or [CacheState.ERROR]. This method
+   * assumes that the data can be produced by verifying the source in the given
+   * library if the data is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   DartEntry _cacheDartVerificationData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = dartEntry.getStateInLibrary(descriptor, librarySource);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information. Unless the modification date of the
       // source continues to change, this loop will eventually terminate.
       //
       LibraryElement library = computeLibraryElement(librarySource);
       CompilationUnit unit = resolveCompilationUnit(unitSource, library);
       if (unit == null) {
         throw new AnalysisException(
             "Could not resolve compilation unit ${unitSource.fullName} in ${librarySource.fullName}");
       }
       dartEntry = new GenerateDartErrorsTask(this, unitSource, unit, library)
           .perform(_resultRecorder) as DartEntry;
       state = dartEntry.getStateInLibrary(descriptor, librarySource);
     }
     return dartEntry;
   }
 
   /**
-   * Given a source for an HTML file, return a cache entry in which all of the data represented by
-   * the state of the given descriptors is either [CacheState.VALID] or
-   * [CacheState.ERROR]. This method assumes that the data can be produced by parsing the
-   * source if it is not already cached.
+   * Given a source for an HTML file, return a cache entry in which all of the
+   * data represented by the state of the given descriptors is either
+   * [CacheState.VALID] or [CacheState.ERROR]. This method assumes that the data
+   * can be produced by parsing the source if it is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the HTML file
-   * @param htmlEntry the cache entry associated with the HTML file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   HtmlEntry _cacheHtmlParseData(
       Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
     if (identical(descriptor, HtmlEntry.PARSED_UNIT)) {
       ht.HtmlUnit unit = htmlEntry.anyParsedUnit;
       if (unit != null) {
         return htmlEntry;
       }
     }
     //
@@ skipping 18 matching lines @@
       } catch (exception, stackTrace) {
         throw new AnalysisException(
             "Exception", new CaughtException(exception, stackTrace));
       }
       state = htmlEntry.getState(descriptor);
     }
     return htmlEntry;
   }
 
   /**
-   * Given a source for an HTML file, return a cache entry in which the state of the data
-   * represented by the given descriptor is either [CacheState.VALID] or
-   * [CacheState.ERROR]. This method assumes that the data can be produced by resolving the
-   * source if it is not already cached.
+   * Given a source for an HTML file, return a cache entry in which the state of
+   * the data represented by the given descriptor is either [CacheState.VALID]
+   * or [CacheState.ERROR]. This method assumes that the data can be produced by
+   * resolving the source if it is not already cached.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the HTML file
-   * @param dartEntry the cache entry associated with the HTML file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return a cache entry containing the required data
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   HtmlEntry _cacheHtmlResolutionData(
       Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
     //
     // Check to see whether we already have the information being requested.
     //
     CacheState state = htmlEntry.getState(descriptor);
     while (state != CacheState.ERROR && state != CacheState.VALID) {
       //
       // If not, compute the information. Unless the modification date of the
@@ skipping 17 matching lines @@
         _pendingFutureSources[pendingFuture.source];
     if (pendingFutures != null) {
       pendingFutures.remove(pendingFuture);
       if (pendingFutures.isEmpty) {
         _pendingFutureSources.remove(pendingFuture.source);
       }
     }
   }
 
   /**
-   * Compute the transitive closure of all libraries that depend on the given library by adding such
-   * libraries to the given collection.
-   *
-   * @param library the library on which the other libraries depend
-   * @param librariesToInvalidate the libraries that depend on the given library
+   * Compute the transitive closure of all libraries that depend on the given
+   * [library] by adding such libraries to the given collection of
+   * [librariesToInvalidate].
    */
   void _computeAllLibrariesDependingOn(
       Source library, HashSet<Source> librariesToInvalidate) {
     if (librariesToInvalidate.add(library)) {
       for (Source dependentLibrary in getLibrariesDependingOn(library)) {
         _computeAllLibrariesDependingOn(
             dependentLibrary, librariesToInvalidate);
       }
     }
   }
 
   /**
-   * Compute the priority that should be used when the source associated with the given entry is
-   * added to the work manager.
-   *
-   * @param dartEntry the entry associated with the source
-   * @return the priority that was computed
+   * Return the priority that should be used when the source associated with
+   * the given [dartEntry] is added to the work manager.
    */
   SourcePriority _computePriority(DartEntry dartEntry) {
     SourceKind kind = dartEntry.kind;
     if (kind == SourceKind.LIBRARY) {
       return SourcePriority.LIBRARY;
     } else if (kind == SourceKind.PART) {
       return SourcePriority.NORMAL_PART;
     }
     return SourcePriority.UNKNOWN;
   }
 
   /**
-   * Given the encoded form of a source, use the source factory to reconstitute the original source.
-   *
-   * @param encoding the encoded form of a source
-   * @return the source represented by the encoding
+   * Given the encoded form of a source ([encoding]), use the source factory to
+   * reconstitute the original source.
    */
   Source _computeSourceFromEncoding(String encoding) =>
       _sourceFactory.fromEncoding(encoding);
 
   /**
-   * Return `true` if the given array of sources contains the given source.
-   *
-   * @param sources the sources being searched
-   * @param targetSource the source being searched for
-   * @return `true` if the given source is in the array
+   * Return `true` if the given list of [sources] contains the given
+   * [targetSource].
    */
   bool _contains(List<Source> sources, Source targetSource) {
     for (Source source in sources) {
       if (source == targetSource) {
         return true;
       }
     }
     return false;
   }
 
   /**
-   * Return `true` if the given array of sources contains any of the given target sources.
-   *
-   * @param sources the sources being searched
-   * @param targetSources the sources being searched for
-   * @return `true` if any of the given target sources are in the array
+   * Return `true` if the given list of [sources] contains any of the given
+   * [targetSources].
    */
   bool _containsAny(List<Source> sources, List<Source> targetSources) {
     for (Source targetSource in targetSources) {
       if (_contains(sources, targetSource)) {
         return true;
       }
     }
     return false;
   }
 
   /**
-   * Set the contents of the given source to the given contents and mark the source as having
-   * changed. The additional offset and length information is used by the context to determine what
-   * reanalysis is necessary. [setChangedContents] triggers a source changed event
-   * where as this method does not.
-   *
-   * @param source the source whose contents are being overridden
-   * @param contents the text to replace the range in the current contents
-   * @param offset the offset into the current contents
-   * @param oldLength the number of characters in the original contents that were replaced
-   * @param newLength the number of characters in the replacement text
+   * Set the contents of the given [source] to the given [contents] and mark the
+   * source as having changed. The additional [offset], [oldLength] and
+   * [newLength] information is used by the context to determine what reanalysis
+   * is necessary. The method [setChangedContents] triggers a source changed
+   * event where as this method does not.
    */
   bool _contentRangeChanged(Source source, String contents, int offset,
       int oldLength, int newLength) {
     bool changed = false;
     String originalContents = _contentCache.setContents(source, contents);
     if (contents != null) {
       if (contents != originalContents) {
         if (_options.incremental) {
           _incrementalAnalysisCache = IncrementalAnalysisCache.update(
               _incrementalAnalysisCache, source, originalContents, contents,
@@ skipping 11 matching lines @@
     } else if (originalContents != null) {
       _incrementalAnalysisCache =
           IncrementalAnalysisCache.clear(_incrementalAnalysisCache, source);
       _sourceChanged(source);
       changed = true;
     }
     return changed;
   }
 
   /**
-   * Set the contents of the given source to the given contents and mark the source as having
-   * changed. This has the effect of overriding the default contents of the source. If the contents
-   * are `null` the override is removed so that the default contents will be returned.
-   *
-   * If [notify] is true, a source changed event is triggered.
-   *
-   * @param source the source whose contents are being overridden
-   * @param contents the new contents of the source
+   * Set the contents of the given [source] to the given [contents] and mark the
+   * source as having changed. This has the effect of overriding the default
+   * contents of the source. If the contents are `null` the override is removed
+   * so that the default contents will be returned. If [notify] is true, a
+   * source changed event is triggered.
    */
   void _contentsChanged(Source source, String contents, bool notify) {
     String originalContents = _contentCache.setContents(source, contents);
     handleContentsChanged(source, originalContents, contents, notify);
   }
 
-//  /**
-//   * Create a [BuildUnitElementTask] for the given [source].
-//   */
-//  AnalysisContextImpl_TaskData _createBuildUnitElementTask(Source source,
-//      DartEntry dartEntry, Source librarySource) {
-//    CompilationUnit unit = dartEntry.resolvableCompilationUnit;
-//    if (unit == null) {
-//      return _createParseDartTask(source, dartEntry);
-//    }
-//    return new AnalysisContextImpl_TaskData(
-//        new BuildUnitElementTask(this, source, librarySource, unit),
-//        false);
-//  }
-
   /**
-   * Create a [GenerateDartErrorsTask] for the given source, marking the verification errors
-   * as being in-process. The compilation unit and the library can be the same if the compilation
-   * unit is the defining compilation unit of the library.
-   *
-   * @param unitSource the source for the compilation unit to be verified
-   * @param unitEntry the entry for the compilation unit
-   * @param librarySource the source for the library containing the compilation unit
-   * @param libraryEntry the entry for the library
-   * @return task data representing the created task
+   * Create a [GenerateDartErrorsTask] for the given [unitSource], marking the
+   * verification errors as being in-process. The compilation unit and the
+   * library can be the same if the compilation unit is the defining compilation
+   * unit of the library.
    */
   AnalysisContextImpl_TaskData _createGenerateDartErrorsTask(Source unitSource,
       DartEntry unitEntry, Source librarySource, DartEntry libraryEntry) {
     if (unitEntry.getStateInLibrary(DartEntry.RESOLVED_UNIT, librarySource) !=
             CacheState.VALID ||
         libraryEntry.getState(DartEntry.ELEMENT) != CacheState.VALID) {
       return _createResolveDartLibraryTask(librarySource, libraryEntry);
     }
     CompilationUnit unit =
         unitEntry.getValueInLibrary(DartEntry.RESOLVED_UNIT, librarySource);
     if (unit == null) {
       CaughtException exception = new CaughtException(new AnalysisException(
               "Entry has VALID state for RESOLVED_UNIT but null value for ${unitSource.fullName} in ${librarySource.fullName}"),
           null);
       AnalysisEngine.instance.logger.logInformation(
           exception.toString(), exception);
       unitEntry.recordResolutionError(exception);
       return new AnalysisContextImpl_TaskData(null, false);
     }
     LibraryElement libraryElement = libraryEntry.getValue(DartEntry.ELEMENT);
     return new AnalysisContextImpl_TaskData(
         new GenerateDartErrorsTask(this, unitSource, unit, libraryElement),
         false);
   }
 
   /**
-   * Create a [GenerateDartHintsTask] for the given source, marking the hints as being
-   * in-process.
-   *
-   * @param source the source whose content is to be verified
-   * @param dartEntry the entry for the source
-   * @param librarySource the source for the library containing the source
-   * @param libraryEntry the entry for the library
-   * @return task data representing the created task
+   * Create a [GenerateDartHintsTask] for the given [source], marking the hints
+   * as being in-process.
    */
   AnalysisContextImpl_TaskData _createGenerateDartHintsTask(Source source,
       DartEntry dartEntry, Source librarySource, DartEntry libraryEntry) {
     if (libraryEntry.getState(DartEntry.ELEMENT) != CacheState.VALID) {
       return _createResolveDartLibraryTask(librarySource, libraryEntry);
     }
     LibraryElement libraryElement = libraryEntry.getValue(DartEntry.ELEMENT);
     CompilationUnitElement definingUnit =
         libraryElement.definingCompilationUnit;
     List<CompilationUnitElement> parts = libraryElement.parts;
@@ skipping 11 matching lines @@
         // TODO(brianwilkerson) We should return a ResolveDartUnitTask
         // (unless there are multiple ASTs that need to be resolved).
         return _createResolveDartLibraryTask(librarySource, libraryEntry);
       }
     }
     return new AnalysisContextImpl_TaskData(
         new GenerateDartHintsTask(this, units, libraryElement), false);
   }
 
   /**
-   * Create a [GenerateDartLintsTask] for the given source, marking the lints as
-   * being in-process.
-   *
-   * @param source the source whose content is to be verified
-   * @param dartEntry the entry for the source
-   * @param librarySource the source for the library containing the source
-   * @param libraryEntry the entry for the library
-   * @return task data representing the created task
+   * Create a [GenerateDartLintsTask] for the given [source], marking the lints
+   * as being in-process.
    */
   AnalysisContextImpl_TaskData _createGenerateDartLintsTask(Source source,
       DartEntry dartEntry, Source librarySource, DartEntry libraryEntry) {
     if (libraryEntry.getState(DartEntry.ELEMENT) != CacheState.VALID) {
       return _createResolveDartLibraryTask(librarySource, libraryEntry);
     }
     LibraryElement libraryElement = libraryEntry.getValue(DartEntry.ELEMENT);
     CompilationUnitElement definingUnit =
         libraryElement.definingCompilationUnit;
     List<CompilationUnitElement> parts = libraryElement.parts;
@@ skipping 12 matching lines @@
         // (unless there are multiple ASTs that need to be resolved).
         return _createResolveDartLibraryTask(librarySource, libraryEntry);
       }
     }
     //TODO(pquitslund): revisit if we need all units or whether one will do
     return new AnalysisContextImpl_TaskData(
         new GenerateDartLintsTask(this, units, libraryElement), false);
   }
 
   /**
-   * Create a [GetContentTask] for the given source, marking the content as being in-process.
-   *
-   * @param source the source whose content is to be accessed
-   * @param sourceEntry the entry for the source
-   * @return task data representing the created task
+   * Create a [GetContentTask] for the given [source], marking the content as
+   * being in-process.
    */
   AnalysisContextImpl_TaskData _createGetContentTask(
       Source source, SourceEntry sourceEntry) {
     return new AnalysisContextImpl_TaskData(
         new GetContentTask(this, source), false);
   }
 
   /**
    * Create a [ParseDartTask] for the given [source].
    */
@@ skipping 17 matching lines @@
     if (htmlEntry.getState(SourceEntry.CONTENT) != CacheState.VALID) {
       return _createGetContentTask(source, htmlEntry);
     }
     String content = htmlEntry.getValue(SourceEntry.CONTENT);
     htmlEntry.setState(SourceEntry.CONTENT, CacheState.FLUSHED);
     return new AnalysisContextImpl_TaskData(
         new ParseHtmlTask(this, source, content), false);
   }
 
   /**
-   * Create a [ResolveDartLibraryTask] for the given source, marking ? as being in-process.
-   *
-   * @param source the source whose content is to be resolved
-   * @param dartEntry the entry for the source
-   * @return task data representing the created task
+   * Create a [ResolveDartLibraryTask] for the given [source], marking ? as
+   * being in-process.
    */
   AnalysisContextImpl_TaskData _createResolveDartLibraryTask(
       Source source, DartEntry dartEntry) {
     try {
       AnalysisContextImpl_CycleBuilder builder =
           new AnalysisContextImpl_CycleBuilder(this);
       PerformanceStatistics.cycles.makeCurrentWhile(() {
         builder.computeCycleContaining(source);
       });
       AnalysisContextImpl_TaskData taskData = builder.taskData;
       if (taskData != null) {
         return taskData;
       }
       return new AnalysisContextImpl_TaskData(new ResolveDartLibraryCycleTask(
           this, source, source, builder.librariesInCycle), false);
     } on AnalysisException catch (exception, stackTrace) {
       dartEntry
           .recordResolutionError(new CaughtException(exception, stackTrace));
       AnalysisEngine.instance.logger.logError(
           "Internal error trying to create a ResolveDartLibraryTask",
           new CaughtException(exception, stackTrace));
     }
     return new AnalysisContextImpl_TaskData(null, false);
   }
 
   /**
-   * Create a [ResolveHtmlTask] for the given source, marking the resolved unit as being
-   * in-process.
-   *
-   * @param source the source whose content is to be resolved
-   * @param htmlEntry the entry for the source
-   * @return task data representing the created task
+   * Create a [ResolveHtmlTask] for the given [source], marking the resolved
+   * unit as being in-process.
    */
   AnalysisContextImpl_TaskData _createResolveHtmlTask(
       Source source, HtmlEntry htmlEntry) {
     if (htmlEntry.getState(HtmlEntry.PARSED_UNIT) != CacheState.VALID) {
       return _createParseHtmlTask(source, htmlEntry);
     }
     return new AnalysisContextImpl_TaskData(new ResolveHtmlTask(this, source,
         htmlEntry.modificationTime,
         htmlEntry.getValue(HtmlEntry.PARSED_UNIT)), false);
   }
 
   /**
-   * Create a [ScanDartTask] for the given source, marking the scan errors as being
-   * in-process.
-   *
-   * @param source the source whose content is to be scanned
-   * @param dartEntry the entry for the source
-   * @return task data representing the created task
+   * Create a [ScanDartTask] for the given [source], marking the scan errors as
+   * being in-process.
    */
   AnalysisContextImpl_TaskData _createScanDartTask(
       Source source, DartEntry dartEntry) {
     if (dartEntry.getState(SourceEntry.CONTENT) != CacheState.VALID) {
       return _createGetContentTask(source, dartEntry);
     }
     String content = dartEntry.getValue(SourceEntry.CONTENT);
     dartEntry.setState(SourceEntry.CONTENT, CacheState.FLUSHED);
     return new AnalysisContextImpl_TaskData(
         new ScanDartTask(this, source, content), false);
   }
 
   /**
-   * Create a source information object suitable for the given source. Return the source information
-   * object that was created, or `null` if the source should not be tracked by this context.
-   *
-   * @param source the source for which an information object is being created
-   * @param explicitlyAdded `true` if the source was explicitly added to the context
-   * @return the source information object that was created
+   * Create a source entry for the given [source]. Return the source entry that
+   * was created, or `null` if the source should not be tracked by this context.
    */
   SourceEntry _createSourceEntry(Source source, bool explicitlyAdded) {
     String name = source.shortName;
     if (AnalysisEngine.isHtmlFileName(name)) {
       HtmlEntry htmlEntry = new HtmlEntry();
       htmlEntry.modificationTime = getModificationStamp(source);
       htmlEntry.explicitlyAdded = explicitlyAdded;
       _cache.put(source, htmlEntry);
       return htmlEntry;
     } else {
       DartEntry dartEntry = new DartEntry();
       dartEntry.modificationTime = getModificationStamp(source);
       dartEntry.explicitlyAdded = explicitlyAdded;
       _cache.put(source, dartEntry);
       return dartEntry;
     }
   }
 
   /**
-   * Return an array containing all of the change notices that are waiting to be returned. If there
-   * are no notices, then return either `null` or an empty array, depending on the value of
-   * the argument.
-   *
-   * @param nullIfEmpty `true` if `null` should be returned when there are no notices
-   * @return the change notices that are waiting to be returned
+   * Return a list containing all of the change notices that are waiting to be
+   * returned. If there are no notices, then return either `null` or an empty
+   * list, depending on the value of [nullIfEmpty].
    */
   List<ChangeNotice> _getChangeNotices(bool nullIfEmpty) {
     if (_pendingNotices.isEmpty) {
       if (nullIfEmpty) {
         return null;
       }
       return ChangeNoticeImpl.EMPTY_ARRAY;
     }
     List<ChangeNotice> notices = new List.from(_pendingNotices.values);
     _pendingNotices.clear();
     return notices;
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return the data represented by
-   * the given descriptor that is associated with that source. This method assumes that the data can
-   * be produced by generating hints for the library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return the
+   * data represented by the given descriptor that is associated with that
+   * source. This method assumes that the data can be produced by generating
+   * hints for the library if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the entry representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getDartHintData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry =
         _cacheDartHintData(unitSource, librarySource, dartEntry, descriptor);
     if (identical(descriptor, DartEntry.ELEMENT)) {
       return dartEntry.getValue(descriptor);
     }
     return dartEntry.getValueInLibrary(descriptor, librarySource);
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return the data represented by
-   * the given descriptor that is associated with that source. This method assumes that the data can
-   * be produced by generating lints for the library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return the
+   * data represented by the given descriptor that is associated with that
+   * source. This method assumes that the data can be produced by generating
+   * lints for the library if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the entry representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getDartLintData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry =
         _cacheDartLintData(unitSource, librarySource, dartEntry, descriptor);
     if (identical(descriptor, DartEntry.ELEMENT)) {
       return dartEntry.getValue(descriptor);
     }
     return dartEntry.getValueInLibrary(descriptor, librarySource);
   }
 
   /**
-   * Given a source for a Dart file, return the data represented by the given descriptor that is
-   * associated with that source. This method assumes that the data can be produced by parsing the
-   * source if it is not already cached.
+   * Given a source for a Dart file, return the data represented by the given
+   * descriptor that is associated with that source. This method assumes that
+   * the data can be produced by parsing the source if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be parsed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   Object _getDartParseData(
       Source source, DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry = _cacheDartParseData(source, dartEntry, descriptor);
     if (identical(descriptor, DartEntry.PARSED_UNIT)) {
       _accessedAst(source);
       return dartEntry.anyParsedCompilationUnit;
     }
     return dartEntry.getValue(descriptor);
   }
 
   /**
-   * Given a source for a Dart file, return the data represented by the given descriptor that is
-   * associated with that source, or the given default value if the source is not a Dart file. This
-   * method assumes that the data can be produced by parsing the source if it is not already cached.
+   * Given a source for a Dart file, return the data represented by the given
+   * descriptor that is associated with that source, or the given default value
+   * if the source is not a Dart file. This method assumes that the data can be
+   * produced by parsing the source if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be parsed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @param defaultValue the value to be returned if the source is not a Dart file
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   Object _getDartParseData2(
       Source source, DataDescriptor descriptor, Object defaultValue) {
     DartEntry dartEntry = _getReadableDartEntry(source);
     if (dartEntry == null) {
       return defaultValue;
     }
     try {
       return _getDartParseData(source, dartEntry, descriptor);
     } on ObsoleteSourceAnalysisException catch (exception, stackTrace) {
       AnalysisEngine.instance.logger.logInformation(
           "Could not compute $descriptor",
           new CaughtException(exception, stackTrace));
       return defaultValue;
     }
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return the data represented by
-   * the given descriptor that is associated with that source. This method assumes that the data can
-   * be produced by resolving the source in the context of the library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return the
+   * data represented by the given descriptor that is associated with that
+   * source. This method assumes that the data can be produced by resolving the
+   * source in the context of the library if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the entry representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getDartResolutionData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry = _cacheDartResolutionData(
         unitSource, librarySource, dartEntry, descriptor);
     if (identical(descriptor, DartEntry.ELEMENT)) {
       return dartEntry.getValue(descriptor);
     } else if (identical(descriptor, DartEntry.RESOLVED_UNIT)) {
       _accessedAst(unitSource);
     }
     return dartEntry.getValueInLibrary(descriptor, librarySource);
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return the data represented by
-   * the given descriptor that is associated with that source, or the given default value if the
-   * source is not a Dart file. This method assumes that the data can be produced by resolving the
-   * source in the context of the library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return the
+   * data represented by the given descriptor that is associated with that
+   * source, or the given default value if the source is not a Dart file. This
+   * method assumes that the data can be produced by resolving the source in the
+   * context of the library if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @param defaultValue the value to be returned if the source is not a Dart file
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getDartResolutionData2(Source unitSource, Source librarySource,
       DataDescriptor descriptor, Object defaultValue) {
     DartEntry dartEntry = _getReadableDartEntry(unitSource);
     if (dartEntry == null) {
       return defaultValue;
     }
     try {
       return _getDartResolutionData(
           unitSource, librarySource, dartEntry, descriptor);
     } on ObsoleteSourceAnalysisException catch (exception, stackTrace) {
       AnalysisEngine.instance.logger.logInformation(
           "Could not compute $descriptor",
           new CaughtException(exception, stackTrace));
       return defaultValue;
     }
   }
 
   /**
-   * Given a source for a Dart file, return the data represented by the given descriptor that is
-   * associated with that source. This method assumes that the data can be produced by scanning the
-   * source if it is not already cached.
+   * Given a source for a Dart file, return the data represented by the given
+   * descriptor that is associated with that source. This method assumes that
+   * the data can be produced by scanning the source if it is not already
+   * cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be scanned.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param dartEntry the cache entry associated with the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be scanned
    */
   Object _getDartScanData(
       Source source, DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry = _cacheDartScanData(source, dartEntry, descriptor);
     return dartEntry.getValue(descriptor);
   }
 
   /**
-   * Given a source for a Dart file, return the data represented by the given descriptor that is
-   * associated with that source, or the given default value if the source is not a Dart file. This
-   * method assumes that the data can be produced by scanning the source if it is not already
-   * cached.
+   * Given a source for a Dart file, return the data represented by the given
+   * descriptor that is associated with that source, or the given default value
+   * if the source is not a Dart file. This method assumes that the data can be
+   * produced by scanning the source if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be scanned.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @param defaultValue the value to be returned if the source is not a Dart file
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be scanned
    */
   Object _getDartScanData2(
       Source source, DataDescriptor descriptor, Object defaultValue) {
     DartEntry dartEntry = _getReadableDartEntry(source);
     if (dartEntry == null) {
       return defaultValue;
     }
     try {
       return _getDartScanData(source, dartEntry, descriptor);
     } on ObsoleteSourceAnalysisException catch (exception, stackTrace) {
       AnalysisEngine.instance.logger.logInformation(
           "Could not compute $descriptor",
           new CaughtException(exception, stackTrace));
       return defaultValue;
     }
   }
 
   /**
-   * Given a source for a Dart file and the library that contains it, return the data represented by
-   * the given descriptor that is associated with that source. This method assumes that the data can
-   * be produced by verifying the source within the given library if it is not already cached.
+   * Given a source for a Dart file and the library that contains it, return the
+   * data represented by the given descriptor that is associated with that
+   * source. This method assumes that the data can be produced by verifying the
+   * source within the given library if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param unitSource the source representing the Dart file
-   * @param librarySource the source representing the library containing the Dart file
-   * @param dartEntry the entry representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getDartVerificationData(Source unitSource, Source librarySource,
       DartEntry dartEntry, DataDescriptor descriptor) {
     dartEntry = _cacheDartVerificationData(
         unitSource, librarySource, dartEntry, descriptor);
     return dartEntry.getValueInLibrary(descriptor, librarySource);
   }
 
   /**
-   * Given a source for an HTML file, return the data represented by the given descriptor that is
-   * associated with that source, or the given default value if the source is not an HTML file. This
-   * method assumes that the data can be produced by parsing the source if it is not already cached.
+   * Given a source for an HTML file, return the data represented by the given
+   * descriptor that is associated with that source, or the given default value
+   * if the source is not an HTML file. This method assumes that the data can be
+   * produced by parsing the source if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be parsed.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the Dart file
-   * @param descriptor the descriptor representing the data to be returned
-   * @param defaultValue the value to be returned if the source is not an HTML file
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be parsed
    */
   Object _getHtmlParseData(
       Source source, DataDescriptor descriptor, Object defaultValue) {
     HtmlEntry htmlEntry = _getReadableHtmlEntry(source);
     if (htmlEntry == null) {
       return defaultValue;
     }
     htmlEntry = _cacheHtmlParseData(source, htmlEntry, descriptor);
     if (identical(descriptor, HtmlEntry.PARSED_UNIT)) {
       _accessedAst(source);
       return htmlEntry.anyParsedUnit;
     }
     return htmlEntry.getValue(descriptor);
   }
 
   /**
-   * Given a source for an HTML file, return the data represented by the given descriptor that is
-   * associated with that source, or the given default value if the source is not an HTML file. This
-   * method assumes that the data can be produced by resolving the source if it is not already
-   * cached.
+   * Given a source for an HTML file, return the data represented by the given
+   * descriptor that is associated with that source, or the given default value
+   * if the source is not an HTML file. This method assumes that the data can be
+   * produced by resolving the source if it is not already cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the HTML file
-   * @param descriptor the descriptor representing the data to be returned
-   * @param defaultValue the value to be returned if the source is not an HTML file
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getHtmlResolutionData(
       Source source, DataDescriptor descriptor, Object defaultValue) {
     HtmlEntry htmlEntry = _getReadableHtmlEntry(source);
     if (htmlEntry == null) {
       return defaultValue;
     }
     try {
       return _getHtmlResolutionData2(source, htmlEntry, descriptor);
     } on ObsoleteSourceAnalysisException catch (exception, stackTrace) {
       AnalysisEngine.instance.logger.logInformation(
           "Could not compute $descriptor",
           new CaughtException(exception, stackTrace));
       return defaultValue;
     }
   }
 
   /**
-   * Given a source for an HTML file, return the data represented by the given descriptor that is
-   * associated with that source. This method assumes that the data can be produced by resolving the
-   * source if it is not already cached.
+   * Given a source for an HTML file, return the data represented by the given
+   * descriptor that is associated with that source. This method assumes that
+   * the data can be produced by resolving the source if it is not already
+   * cached.
+   *
+   * Throws an [AnalysisException] if data could not be returned because the
+   * source could not be resolved.
    *
    * <b>Note:</b> This method cannot be used in an async environment.
-   *
-   * @param source the source representing the HTML file
-   * @param htmlEntry the entry representing the HTML file
-   * @param descriptor the descriptor representing the data to be returned
-   * @return the requested data about the given source
-   * @throws AnalysisException if data could not be returned because the source could not be
-   *           resolved
    */
   Object _getHtmlResolutionData2(
       Source source, HtmlEntry htmlEntry, DataDescriptor descriptor) {
     htmlEntry = _cacheHtmlResolutionData(source, htmlEntry, descriptor);
     if (identical(descriptor, HtmlEntry.RESOLVED_UNIT)) {
       _accessedAst(source);
     }
     return htmlEntry.getValue(descriptor);
   }
 
   /**
-   * Look at the given source to see whether a task needs to be performed related to it. Return the
-   * task that should be performed, or `null` if there is no more work to be done for the
-   * source.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param source the source to be checked
-   * @param sourceEntry the cache entry associated with the source
-   * @param isPriority `true` if the source is a priority source
-   * @param hintsEnabled `true` if hints are currently enabled
-   * @param lintsEnabled `true` if lints are currently enabled
-   * @return the next task that needs to be performed for the given source
+   * Look at the given [source] to see whether a task needs to be performed
+   * related to it. Return the task that should be performed, or `null` if there
+   * is no more work to be done for the source.
    */
   AnalysisContextImpl_TaskData _getNextAnalysisTaskForSource(Source source,
       SourceEntry sourceEntry, bool isPriority, bool hintsEnabled,
       bool lintsEnabled) {
     // Refuse to generate tasks for html based files that are above 1500 KB
     if (_isTooBigHtmlSourceEntry(source, sourceEntry)) {
       // TODO (jwren) we still need to report an error of some kind back to the
       // client.
       return new AnalysisContextImpl_TaskData(null, false);
     }
@@ skipping 116 matching lines @@
           htmlEntry.getState(HtmlEntry.RESOLVED_UNIT);
       if (resolvedUnitState == CacheState.INVALID ||
           (isPriority && resolvedUnitState == CacheState.FLUSHED)) {
         return _createResolveHtmlTask(source, htmlEntry);
       }
     }
     return new AnalysisContextImpl_TaskData(null, false);
   }
 
   /**
-   * Return a change notice for the given source, creating one if one does not already exist.
-   *
-   * @param source the source for which changes are being reported
-   * @return a change notice for the given source
+   * Return a change notice for the given [source], creating one if one does not
+   * already exist.
    */
   ChangeNoticeImpl _getNotice(Source source) {
     ChangeNoticeImpl notice = _pendingNotices[source];
     if (notice == null) {
       notice = new ChangeNoticeImpl(source);
       _pendingNotices[source] = notice;
     }
     return notice;
   }
 
   /**
-   * Return the cache entry associated with the given source, or `null` if the source is not a
-   * Dart file.
+   * Return the cache entry associated with the given [source], or `null` if the
+   * source is not a Dart file.
    *
    * @param source the source for which a cache entry is being sought
    * @return the source cache entry associated with the given source
    */
   DartEntry _getReadableDartEntry(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry == null) {
       sourceEntry = _createSourceEntry(source, false);
     }
     if (sourceEntry is DartEntry) {
       return sourceEntry;
     }
     return null;
   }
 
   /**
-   * Return the cache entry associated with the given source, or `null` if the source is not
-   * an HTML file.
-   *
-   * @param source the source for which a cache entry is being sought
-   * @return the source cache entry associated with the given source
+   * Return the cache entry associated with the given [source], or `null` if the
+   * source is not an HTML file.
    */
   HtmlEntry _getReadableHtmlEntry(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry == null) {
       sourceEntry = _createSourceEntry(source, false);
     }
     if (sourceEntry is HtmlEntry) {
       return sourceEntry;
     }
     return null;
   }
 
   /**
-   * Return the cache entry associated with the given source, creating it if necessary.
-   *
-   * @param source the source for which a cache entry is being sought
-   * @return the source cache entry associated with the given source
+   * Return the cache entry associated with the given [source], creating it if
+   * necessary.
    */
   SourceEntry _getReadableSourceEntry(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry == null) {
       sourceEntry = _createSourceEntry(source, false);
     }
     return sourceEntry;
   }
 
   /**
-   * Return a resolved compilation unit corresponding to the given element in the given library, or
-   * `null` if the information is not cached.
-   *
-   * @param element the element representing the compilation unit
-   * @param librarySource the source representing the library containing the unit
-   * @return the specified resolved compilation unit
+   * Return a resolved compilation unit corresponding to the given [element] in
+   * the library defined by the given [librarySource], or `null` if the
+   * information is not cached.
    */
   TimestampedData<CompilationUnit> _getResolvedUnit(
       CompilationUnitElement element, Source librarySource) {
     SourceEntry sourceEntry = _cache.get(element.source);
     if (sourceEntry is DartEntry) {
       DartEntry dartEntry = sourceEntry;
       if (dartEntry.getStateInLibrary(DartEntry.RESOLVED_UNIT, librarySource) ==
           CacheState.VALID) {
         return new TimestampedData<CompilationUnit>(dartEntry.modificationTime,
             dartEntry.getValueInLibrary(
                 DartEntry.RESOLVED_UNIT, librarySource));
       }
     }
     return null;
   }
 
   /**
-   * Return an array containing all of the sources known to this context that have the given kind.
-   *
-   * @param kind the kind of sources to be returned
-   * @return all of the sources known to this context that have the given kind
+   * Return a list containing all of the sources known to this context that have
+   * the given [kind].
    */
   List<Source> _getSources(SourceKind kind) {
     List<Source> sources = new List<Source>();
     MapIterator<Source, SourceEntry> iterator = _cache.iterator();
     while (iterator.moveNext()) {
       if (iterator.value.kind == kind) {
         sources.add(iterator.key);
       }
     }
     return sources;
   }
 
   /**
-   * Look at the given source to see whether a task needs to be performed related to it. If so, add
-   * the source to the set of sources that need to be processed. This method duplicates, and must
-   * therefore be kept in sync with,
-   * [getNextAnalysisTask]. This method is intended to
-   * be used for testing purposes only.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param source the source to be checked
-   * @param sourceEntry the cache entry associated with the source
-   * @param isPriority `true` if the source is a priority source
-   * @param hintsEnabled `true` if hints are currently enabled
-   * @param lintsEnabled `true` if lints are currently enabled
-   * @param sources the set to which sources should be added
+   * Look at the given [source] to see whether a task needs to be performed
+   * related to it. If so, add the source to the set of sources that need to be
+   * processed. This method duplicates, and must therefore be kept in sync with,
+   * [_getNextAnalysisTaskForSource]. This method is intended to be used for
+   * testing purposes only.
    */
   void _getSourcesNeedingProcessing(Source source, SourceEntry sourceEntry,
       bool isPriority, bool hintsEnabled, bool lintsEnabled,
       HashSet<Source> sources) {
     if (sourceEntry is DartEntry) {
       DartEntry dartEntry = sourceEntry;
       CacheState scanErrorsState = dartEntry.getState(DartEntry.SCAN_ERRORS);
       if (scanErrorsState == CacheState.INVALID ||
           (isPriority && scanErrorsState == CacheState.FLUSHED)) {
         sources.add(source);
@@ skipping 84 matching lines @@
           htmlEntry.getState(HtmlEntry.RESOLVED_UNIT);
       if (resolvedUnitState == CacheState.INVALID ||
           (isPriority && resolvedUnitState == CacheState.FLUSHED)) {
         sources.add(source);
         return;
       }
     }
   }
 
   /**
-   * Invalidate all of the resolution results computed by this context.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param invalidateUris `true` if the cached results of converting URIs to source files
-   *          should also be invalidated.
+   * Invalidate all of the resolution results computed by this context. The flag
+   * [invalidateUris] should be `true` if the cached results of converting URIs
+   * to source files should also be invalidated.
    */
   void _invalidateAllLocalResolutionInformation(bool invalidateUris) {
     HashMap<Source, List<Source>> oldPartMap =
         new HashMap<Source, List<Source>>();
     MapIterator<Source, SourceEntry> iterator = _privatePartition.iterator();
     while (iterator.moveNext()) {
       Source source = iterator.key;
       SourceEntry sourceEntry = iterator.value;
       if (sourceEntry is HtmlEntry) {
         HtmlEntry htmlEntry = sourceEntry;
         htmlEntry.invalidateAllResolutionInformation(invalidateUris);
         iterator.value = htmlEntry;
         _workManager.add(source, SourcePriority.HTML);
       } else if (sourceEntry is DartEntry) {
         DartEntry dartEntry = sourceEntry;
         oldPartMap[source] = dartEntry.getValue(DartEntry.INCLUDED_PARTS);
         dartEntry.invalidateAllResolutionInformation(invalidateUris);
         iterator.value = dartEntry;
         _workManager.add(source, _computePriority(dartEntry));
       }
     }
     _removeFromPartsUsingMap(oldPartMap);
   }
 
   /**
-   * In response to a change to at least one of the compilation units in the given library,
-   * invalidate any results that are dependent on the result of resolving that library.
+   * In response to a change to at least one of the compilation units in the
+   * library defined by the given [librarySource], invalidate any results that
+   * are dependent on the result of resolving that library.
    *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * <b>Note:</b> Any cache entries that were accessed before this method was invoked must be
-   * re-accessed after this method returns.
-   *
-   * @param librarySource the source of the library being invalidated
+   * <b>Note:</b> Any cache entries that were accessed before this method was
+   * invoked must be re-accessed after this method returns.
    */
   void _invalidateLibraryResolution(Source librarySource) {
     // TODO(brianwilkerson) This could be optimized. There's no need to flush
     // all of these entries if the public namespace hasn't changed, which will
     // be a fairly common case. The question is whether we can afford the time
     // to compute the namespace to look for differences.
     DartEntry libraryEntry = _getReadableDartEntry(librarySource);
     if (libraryEntry != null) {
       List<Source> includedParts =
           libraryEntry.getValue(DartEntry.INCLUDED_PARTS);
       libraryEntry.invalidateAllResolutionInformation(false);
       _workManager.add(librarySource, SourcePriority.LIBRARY);
       for (Source partSource in includedParts) {
         SourceEntry partEntry = _cache.get(partSource);
         if (partEntry is DartEntry) {
           partEntry.invalidateAllResolutionInformation(false);
         }
       }
     }
   }
 
   /**
-   * Return `true` if this library is, or depends on, dart:html.
-   *
-   * @param library the library being tested
-   * @param visitedLibraries a collection of the libraries that have been visited, used to prevent
-   *          infinite recursion
-   * @return `true` if this library is, or depends on, dart:html
+   * Return `true` if the given [library] is, or depends on, 'dart:html'. The
+   * [visitedLibraries] is a collection of the libraries that have been visited,
+   * used to prevent infinite recursion.
    */
   bool _isClient(LibraryElement library, Source htmlSource,
       HashSet<LibraryElement> visitedLibraries) {
     if (visitedLibraries.contains(library)) {
       return false;
     }
     if (library.source == htmlSource) {
       return true;
     }
     visitedLibraries.add(library);
     for (LibraryElement imported in library.importedLibraries) {
       if (_isClient(imported, htmlSource, visitedLibraries)) {
         return true;
       }
     }
     for (LibraryElement exported in library.exportedLibraries) {
       if (_isClient(exported, htmlSource, visitedLibraries)) {
         return true;
       }
     }
     return false;
   }
 
   bool _isTooBigHtmlSourceEntry(Source source, SourceEntry sourceEntry) =>
       false;
 
   /**
-   * Log the given debugging information.
-   *
-   * @param message the message to be added to the log
+   * Log the given debugging [message].
    */
   void _logInformation(String message) {
     AnalysisEngine.instance.logger.logInformation(message);
   }
 
   /**
    * Notify all of the analysis listeners that a task is about to be performed.
-   *
-   * @param taskDescription a human readable description of the task that is about to be performed
    */
   void _notifyAboutToPerformTask(String taskDescription) {
     int count = _listeners.length;
     for (int i = 0; i < count; i++) {
       _listeners[i].aboutToPerformTask(this, taskDescription);
     }
   }
 
   /**
-   * Notify all of the analysis listeners that the errors associated with the given source has been
-   * updated to the given errors.
-   *
-   * @param source the source containing the errors that were computed
-   * @param errors the errors that were computed
-   * @param lineInfo the line information associated with the source
+   * Notify all of the analysis listeners that the errors associated with the
+   * given [source] has been updated to the given [errors].
    */
   void _notifyErrors(
       Source source, List<AnalysisError> errors, LineInfo lineInfo) {
     int count = _listeners.length;
     for (int i = 0; i < count; i++) {
       _listeners[i].computedErrors(this, source, errors, lineInfo);
     }
   }
 
   /**
@@ skipping 131 matching lines @@
 //   * @param unit the result of resolving the source
 //   */
 //  void _notifyResolvedHtml(Source source, ht.HtmlUnit unit) {
 //    int count = _listeners.length;
 //    for (int i = 0; i < count; i++) {
 //      _listeners[i].resolvedHtml(this, source, unit);
 //    }
 //  }
 
   /**
-   * Given a cache entry and a library element, record the library element and other information
-   * gleaned from the element in the cache entry.
-   *
-   * @param dartCopy the cache entry in which data is to be recorded
-   * @param library the library element used to record information
-   * @param librarySource the source for the library used to record information
-   * @param htmlSource the source for the HTML library
+   * Given a [dartEntry] and a [library] element, record the library element and
+   * other information gleaned from the element in the cache entry.
    */
   void _recordElementData(DartEntry dartEntry, LibraryElement library,
       Source librarySource, Source htmlSource) {
     dartEntry.setValue(DartEntry.ELEMENT, library);
     dartEntry.setValue(DartEntry.IS_LAUNCHABLE, library.entryPoint != null);
     dartEntry.setValue(DartEntry.IS_CLIENT,
         _isClient(library, htmlSource, new HashSet<LibraryElement>()));
   }
 
   /**
@@ skipping 122 matching lines @@
       }
       _workManager.remove(source);
       throw new AnalysisException('<rethrow>', thrownException);
     }
     sourceEntry.modificationTime = task.modificationTime;
     sourceEntry.setValue(SourceEntry.CONTENT, task.content);
     return sourceEntry;
   }
 
   /**
-   * Record the results produced by performing a [IncrementalAnalysisTask].
-   *
-   * @param task the task that was performed
-   * @return an entry containing the computed results
-   * @throws AnalysisException if the results could not be recorded
+   * Record the results produced by performing a [task] and return the cache
+   * entry associated with the results.
    */
   DartEntry _recordIncrementalAnalysisTaskResults(
       IncrementalAnalysisTask task) {
     CompilationUnit unit = task.compilationUnit;
     if (unit != null) {
       ChangeNoticeImpl notice = _getNotice(task.source);
       notice.resolvedDartUnit = unit;
       _incrementalAnalysisCache =
           IncrementalAnalysisCache.cacheResult(task.cache, unit);
     }
@@ skipping 154 matching lines @@
     dartEntry.setValue(SourceEntry.LINE_INFO, lineInfo);
     dartEntry.setValue(DartEntry.TOKEN_STREAM, task.tokenStream);
     dartEntry.setValue(DartEntry.SCAN_ERRORS, task.errors);
     _cache.storedAst(source);
     ChangeNoticeImpl notice = _getNotice(source);
     notice.setErrors(dartEntry.allErrors, lineInfo);
     return dartEntry;
   }
 
   /**
-   * Remove the given library from the list of containing libraries for all of the parts referenced
-   * by the given entry.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param librarySource the library to be removed
-   * @param dartEntry the entry containing the list of included parts
+   * Remove the given [librarySource] from the list of containing libraries for
+   * all of the parts referenced by the given [dartEntry].
    */
   void _removeFromParts(Source librarySource, DartEntry dartEntry) {
     List<Source> oldParts = dartEntry.getValue(DartEntry.INCLUDED_PARTS);
     for (int i = 0; i < oldParts.length; i++) {
       Source partSource = oldParts[i];
       DartEntry partEntry = _getReadableDartEntry(partSource);
       if (partEntry != null && !identical(partEntry, dartEntry)) {
         partEntry.removeContainingLibrary(librarySource);
         if (partEntry.containingLibraries.length == 0 && !exists(partSource)) {
           _cache.remove(partSource);
         }
       }
     }
   }
 
   /**
-   * Remove the given libraries that are keys in the given map from the list of containing libraries
-   * for each of the parts in the corresponding value.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param oldPartMap the table containing the parts associated with each library
+   * Remove the given libraries that are keys in the given map from the list of
+   * containing libraries for each of the parts in the corresponding value.
    */
   void _removeFromPartsUsingMap(HashMap<Source, List<Source>> oldPartMap) {
     oldPartMap.forEach((Source librarySource, List<Source> oldParts) {
       for (int i = 0; i < oldParts.length; i++) {
         Source partSource = oldParts[i];
         if (partSource != librarySource) {
           DartEntry partEntry = _getReadableDartEntry(partSource);
           if (partEntry != null) {
             partEntry.removeContainingLibrary(librarySource);
             if (partEntry.containingLibraries.length == 0 &&
                 !exists(partSource)) {
               _cache.remove(partSource);
             }
           }
         }
       }
     });
   }
 
   /**
-   * Remove the given source from the priority order if it is in the list.
-   *
-   * @param source the source to be removed
+   * Remove the given [source] from the priority order if it is in the list.
    */
   void _removeFromPriorityOrder(Source source) {
     int count = _priorityOrder.length;
     List<Source> newOrder = new List<Source>();
     for (int i = 0; i < count; i++) {
       if (_priorityOrder[i] != source) {
         newOrder.add(_priorityOrder[i]);
       }
     }
     if (newOrder.length < count) {
@@ skipping 11 matching lines @@
     } else if (!dartEntry.explicitlyAdded) {
       return _generateImplicitErrors;
     } else {
       return true;
     }
   }
 
   /**
    * Create an entry for the newly added [source] and invalidate any sources
    * that referenced the source before it existed.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on
-   * [cacheLock].
    */
   void _sourceAvailable(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry == null) {
       sourceEntry = _createSourceEntry(source, true);
     } else {
       _propagateInvalidation(source, sourceEntry);
       sourceEntry = _cache.get(source);
     }
     if (sourceEntry is HtmlEntry) {
       _workManager.add(source, SourcePriority.HTML);
     } else if (sourceEntry is DartEntry) {
       _workManager.add(source, _computePriority(sourceEntry));
     }
   }
 
   /**
    * Invalidate the [source] that was changed and any sources that referenced
    * the source before it existed.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on
-   * [cacheLock].
    */
   void _sourceChanged(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     // If the source is removed, we don't care about it.
     if (sourceEntry == null) {
       return;
     }
     // Check if the content of the source is the same as it was the last time.
     String sourceContent = sourceEntry.getValue(SourceEntry.CONTENT);
     if (sourceContent != null) {
       sourceEntry.setState(SourceEntry.CONTENT, CacheState.FLUSHED);
       try {
         TimestampedData<String> fileContents = getContents(source);
         if (fileContents.data == sourceContent) {
           return;
         }
       } catch (e) {}
     }
     // We have to invalidate the cache.
     _propagateInvalidation(source, sourceEntry);
   }
 
   /**
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param source the source that has been deleted
+   * Record that the give [source] has been deleted.
    */
   void _sourceDeleted(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry is HtmlEntry) {
       HtmlEntry htmlEntry = sourceEntry;
       htmlEntry.recordContentError(new CaughtException(
           new AnalysisException("This source was marked as being deleted"),
           null));
     } else if (sourceEntry is DartEntry) {
       DartEntry dartEntry = sourceEntry;
@@ skipping 10 matching lines @@
       }
       dartEntry.recordContentError(new CaughtException(
           new AnalysisException("This source was marked as being deleted"),
           null));
     }
     _workManager.remove(source);
     _removeFromPriorityOrder(source);
   }
 
   /**
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @param source the source that has been removed
+   * Record that the given [source] has been removed.
    */
   void _sourceRemoved(Source source) {
     SourceEntry sourceEntry = _cache.get(source);
     if (sourceEntry is HtmlEntry) {} else if (sourceEntry is DartEntry) {
       HashSet<Source> libraries = new HashSet<Source>();
       for (Source librarySource in getLibrariesContaining(source)) {
         libraries.add(librarySource);
         for (Source dependentLibrary
             in getLibrariesDependingOn(librarySource)) {
           libraries.add(dependentLibrary);
@@ skipping 64 matching lines @@
         ChangeNoticeImpl notice = _getNotice(unitSource);
         notice.resolvedDartUnit = oldUnit;
         notice.setErrors(dartEntry.allErrors, lineInfo);
       }
       // OK
       return true;
     });
   }
 
   /**
-   * Check the cache for any invalid entries (entries whose modification time does not match the
-   * modification time of the source associated with the entry). Invalid entries will be marked as
-   * invalid so that the source will be re-analyzed.
-   *
-   * <b>Note:</b> This method must only be invoked while we are synchronized on [cacheLock].
-   *
-   * @return `true` if at least one entry was invalid
+   * Check the cache for any invalid entries (entries whose modification time
+   * does not match the modification time of the source associated with the
+   * entry). Invalid entries will be marked as invalid so that the source will
+   * be re-analyzed. Return `true` if at least one entry was invalid.
    */
   bool _validateCacheConsistency() {
     int consistencyCheckStart = JavaSystem.nanoTime();
     List<Source> changedSources = new List<Source>();
     List<Source> missingSources = new List<Source>();
     MapIterator<Source, SourceEntry> iterator = _cache.iterator();
     while (iterator.moveNext()) {
       Source source = iterator.key;
       SourceEntry sourceEntry = iterator.value;
       int sourceTime = getModificationStamp(source);
@@ skipping 61 matching lines @@
         AnalysisEngine.instance.logger.logError(message);
       }
     }
     incrementalResolutionValidation_lastUnitSource = null;
     incrementalResolutionValidation_lastLibrarySource = null;
     incrementalResolutionValidation_lastUnit = null;
   }
 }
 
 /**
- * An `AnalysisTaskResultRecorder` is used by an analysis context to record the
- * results of a task.
+ * An object used by an analysis context to record the results of a task.
  */
 class AnalysisContextImpl_AnalysisTaskResultRecorder
     implements AnalysisTaskVisitor<SourceEntry> {
   final AnalysisContextImpl AnalysisContextImpl_this;
 
   AnalysisContextImpl_AnalysisTaskResultRecorder(this.AnalysisContextImpl_this);
 
   @override
   DartEntry visitBuildUnitElementTask(BuildUnitElementTask task) =>
       AnalysisContextImpl_this._recordBuildUnitElementTask(task);
@@ skipping 76 matching lines @@
   }
 
   bool _astIsNeeded(DartEntry dartEntry) =>
       dartEntry.hasInvalidData(DartEntry.HINTS) ||
           dartEntry.hasInvalidData(DartEntry.LINTS) ||
           dartEntry.hasInvalidData(DartEntry.VERIFICATION_ERRORS) ||
           dartEntry.hasInvalidData(DartEntry.RESOLUTION_ERRORS);
 }
 
 /**
- * Instances of the class `CycleBuilder` are used to construct a list of the libraries that
- * must be resolved together in order to resolve any one of the libraries.
+ * An object used to construct a list of the libraries that must be resolved
+ * together in order to resolve any one of the libraries.
  */
 class AnalysisContextImpl_CycleBuilder {
   final AnalysisContextImpl AnalysisContextImpl_this;
 
   /**
-   * A table mapping the sources of the defining compilation units of libraries to the
-   * representation of the library that has the information needed to resolve the library.
+   * A table mapping the sources of the defining compilation units of libraries
+   * to the representation of the library that has the information needed to
+   * resolve the library.
    */
   HashMap<Source, ResolvableLibrary> _libraryMap =
       new HashMap<Source, ResolvableLibrary>();
 
   /**
    * The dependency graph used to compute the libraries in the cycle.
    */
   DirectedGraph<ResolvableLibrary> _dependencyGraph;
 
   /**
    * A list containing the libraries that are ready to be resolved.
    */
   List<ResolvableLibrary> _librariesInCycle;
 
   /**
-   * The analysis task that needs to be performed before the cycle of libraries can be resolved,
-   * or `null` if the libraries are ready to be resolved.
+   * The analysis task that needs to be performed before the cycle of libraries
+   * can be resolved, or `null` if the libraries are ready to be resolved.
    */
   AnalysisContextImpl_TaskData _taskData;
 
   /**
    * Initialize a newly created cycle builder.
    */
   AnalysisContextImpl_CycleBuilder(this.AnalysisContextImpl_this) : super();
 
   /**
-   * Return a list containing the libraries that are ready to be resolved (assuming that
-   * [getTaskData] returns `null`).
-   *
-   * @return the libraries that are ready to be resolved
+   * Return a list containing the libraries that are ready to be resolved
+   * (assuming that [getTaskData] returns `null`).
    */
   List<ResolvableLibrary> get librariesInCycle => _librariesInCycle;
 
   /**
-   * Return a representation of an analysis task that needs to be performed before the cycle of
-   * libraries can be resolved, or `null` if the libraries are ready to be resolved.
-   *
-   * @return the analysis task that needs to be performed before the cycle of libraries can be
-   *         resolved
+   * Return a representation of an analysis task that needs to be performed
+   * before the cycle of libraries can be resolved, or `null` if the libraries
+   * are ready to be resolved.
    */
   AnalysisContextImpl_TaskData get taskData => _taskData;
 
   /**
-   * Compute a list of the libraries that need to be resolved together in order to resolve the
-   * given library.
-   *
-   * @param librarySource the source of the library to be resolved
-   * @throws AnalysisException if the core library cannot be found
+   * Compute a list of the libraries that need to be resolved together in orde
+   *  to resolve the given [librarySource].
    */
   void computeCycleContaining(Source librarySource) {
     //
     // Create the object representing the library being resolved.
     //
     ResolvableLibrary targetLibrary = _createLibrary(librarySource);
     //
     // Compute the set of libraries that need to be resolved together.
     //
     _dependencyGraph = new DirectedGraph<ResolvableLibrary>();
@@ skipping 46 matching lines @@
     if (importedLibrary != null) {
       if (dependencyList != null) {
         dependencyList.add(importedLibrary);
       }
       _dependencyGraph.addEdge(dependant, importedLibrary);
     }
     return true;
   }
 
   /**
-   * Recursively traverse the libraries reachable from the given library, creating instances of
-   * the class [Library] to represent them, and record the references in the library
-   * objects.
+   * Recursively traverse the libraries reachable from the given [library],
+   * creating instances of the class [Library] to represent them, and record the
+   * references in the library objects.
    *
-   * @param library the library to be processed to find libraries that have not yet been traversed
-   * @throws AnalysisException if some portion of the library graph could not be traversed
+   * Throws an [AnalysisException] if some portion of the library graph could
+   * not be traversed.
    */
   void _computeLibraryDependencies(ResolvableLibrary library) {
     Source librarySource = library.librarySource;
     DartEntry dartEntry =
         AnalysisContextImpl_this._getReadableDartEntry(librarySource);
     List<Source> importedSources =
         _getSources(librarySource, dartEntry, DartEntry.IMPORTED_LIBRARIES);
     if (_taskData != null) {
       return;
     }
     List<Source> exportedSources =
         _getSources(librarySource, dartEntry, DartEntry.EXPORTED_LIBRARIES);
     if (_taskData != null) {
       return;
     }
     _computeLibraryDependenciesFromDirectives(
         library, importedSources, exportedSources);
   }
 
   /**
-   * Recursively traverse the libraries reachable from the given library, creating instances of
-   * the class [Library] to represent them, and record the references in the library
-   * objects.
-   *
-   * @param library the library to be processed to find libraries that have not yet been traversed
-   * @param importedSources an array containing the sources that are imported into the given
-   *          library
-   * @param exportedSources an array containing the sources that are exported from the given
-   *          library
+   * Recursively traverse the libraries reachable from the given [library],
+   * creating instances of the class [Library] to represent them, and record the
+   * references in the library objects. The [importedSources] is a list
+   * containing the sources that are imported into the given library. The
+   * [exportedSources] is a list containing the sources that are exported from
+   * the given library.
    */
   void _computeLibraryDependenciesFromDirectives(ResolvableLibrary library,
       List<Source> importedSources, List<Source> exportedSources) {
     int importCount = importedSources.length;
     List<ResolvableLibrary> importedLibraries = new List<ResolvableLibrary>();
     bool explicitlyImportsCore = false;
     bool importsAsync = false;
     for (int i = 0; i < importCount; i++) {
       Source importedSource = importedSources[i];
       if (importedSource == AnalysisContextImpl_this._coreLibrarySource) {
@@ skipping 36 matching lines @@
         Source exportedSource = exportedSources[i];
         if (!_addDependency(library, exportedSource, exportedLibraries)) {
           return;
         }
       }
       library.exportedLibraries = exportedLibraries;
     }
   }
 
   /**
-   * Gather the resolvable AST structures for each of the compilation units in each of the
-   * libraries in the cycle. This is done in two phases: first we ensure that we have cached an
-   * AST structure for each compilation unit, then we gather them. We split the work this way
-   * because getting the AST structures can change the state of the cache in such a way that we
-   * would have more work to do if any compilation unit didn't have a resolvable AST structure.
+   * Gather the resolvable AST structures for each of the compilation units in
+   * each of the libraries in the cycle. This is done in two phases: first we
+   * ensure that we have cached an AST structure for each compilation unit, then
+   * we gather them. We split the work this way because getting the AST
+   * structures can change the state of the cache in such a way that we would
+   * have more work to do if any compilation unit didn't have a resolvable AST
+   * structure.
    */
   void _computePartsInCycle(Source librarySource) {
     int count = _librariesInCycle.length;
     List<CycleBuilder_LibraryPair> libraryData =
         new List<CycleBuilder_LibraryPair>();
     for (int i = 0; i < count; i++) {
       ResolvableLibrary library = _librariesInCycle[i];
       libraryData.add(new CycleBuilder_LibraryPair(
           library, _ensurePartsInLibrary(library)));
     }
     AnalysisContextImpl_this._neededForResolution = _gatherSources(libraryData);
     if (AnalysisContextImpl._TRACE_PERFORM_TASK) {
       print(
           "  preserve resolution data for ${AnalysisContextImpl_this._neededForResolution.length} sources while resolving ${librarySource.fullName}");
     }
     if (_taskData != null) {
       return;
     }
     for (int i = 0; i < count; i++) {
       _computePartsInLibrary(libraryData[i]);
     }
   }
 
   /**
-   * Gather the resolvable compilation units for each of the compilation units in the specified
-   * library.
-   *
-   * @param libraryPair a holder containing both the library and a list of (source, entry) pairs
-   *          for all of the compilation units in the library
+   * Gather the resolvable compilation units for each of the compilation units
+   * in the library represented by the [libraryPair].
    */
   void _computePartsInLibrary(CycleBuilder_LibraryPair libraryPair) {
     ResolvableLibrary library = libraryPair.library;
     List<CycleBuilder_SourceEntryPair> entryPairs = libraryPair.entryPairs;
     int count = entryPairs.length;
     List<ResolvableCompilationUnit> units =
         new List<ResolvableCompilationUnit>(count);
     for (int i = 0; i < count; i++) {
       CycleBuilder_SourceEntryPair entryPair = entryPairs[i];
       Source source = entryPair.source;
       DartEntry dartEntry = entryPair.entry;
       units[i] = new ResolvableCompilationUnit(
           source, dartEntry.resolvableCompilationUnit);
     }
     library.resolvableCompilationUnits = units;
   }
 
   /**
-   * Create an object to represent the information about the library defined by the compilation
-   * unit with the given source.
-   *
-   * @param librarySource the source of the library's defining compilation unit
-   * @return the library object that was created
+   * Create an object to represent the information about the library defined by
+   * the compilation unit with the given [librarySource].
    */
   ResolvableLibrary _createLibrary(Source librarySource) {
     ResolvableLibrary library = new ResolvableLibrary(librarySource);
     SourceEntry sourceEntry =
         AnalysisContextImpl_this._cache.get(librarySource);
     if (sourceEntry is DartEntry) {
       LibraryElementImpl libraryElement =
           sourceEntry.getValue(DartEntry.ELEMENT) as LibraryElementImpl;
       if (libraryElement != null) {
         library.libraryElement = libraryElement;
       }
     }
     _libraryMap[librarySource] = library;
     return library;
   }
 
   /**
-   * Create an object to represent the information about the library defined by the compilation
-   * unit with the given source.
-   *
-   * @param librarySource the source of the library's defining compilation unit
-   * @return the library object that was created
+   * Create an object to represent the information about the library defined by
+   * the compilation unit with the given [librarySource].
    */
   ResolvableLibrary _createLibraryOrNull(Source librarySource) {
     ResolvableLibrary library = new ResolvableLibrary(librarySource);
     SourceEntry sourceEntry =
         AnalysisContextImpl_this._cache.get(librarySource);
     if (sourceEntry is DartEntry) {
       LibraryElementImpl libraryElement =
           sourceEntry.getValue(DartEntry.ELEMENT) as LibraryElementImpl;
       if (libraryElement != null) {
         library.libraryElement = libraryElement;
       }
     }
     _libraryMap[librarySource] = library;
     return library;
   }
 
   /**
-   * Ensure that the given library has an element model built for it. If another task needs to be
-   * executed first in order to build the element model, that task is placed in [taskData].
-   *
-   * @param library the library which needs an element model.
+   * Ensure that the given [library] has an element model built for it. If
+   * another task needs to be executed first in order to build the element
+   * model, that task is placed in [taskData].
    */
   void _ensureElementModel(ResolvableLibrary library) {
     Source librarySource = library.librarySource;
     DartEntry libraryEntry =
         AnalysisContextImpl_this._getReadableDartEntry(librarySource);
     if (libraryEntry != null &&
         libraryEntry.getState(DartEntry.PARSED_UNIT) != CacheState.ERROR) {
       AnalysisContextImpl_this._workManager.addFirst(
           librarySource, SourcePriority.LIBRARY);
       if (_taskData == null) {
         _taskData = AnalysisContextImpl_this._createResolveDartLibraryTask(
             librarySource, libraryEntry);
       }
     }
   }
 
   /**
-   * Ensure that all of the libraries that are exported by the given library (but are not
-   * themselves in the cycle) have element models built for them. If another task needs to be
-   * executed first in order to build the element model, that task is placed in [taskData].
-   *
-   * @param library the library being tested
+   * Ensure that all of the libraries that are exported by the given [library]
+   * (but are not themselves in the cycle) have element models built for them.
+   * If another task needs to be executed first in order to build the element
+   * model, that task is placed in [taskData].
    */
   void _ensureExports(
       ResolvableLibrary library, HashSet<Source> visitedLibraries) {
     List<ResolvableLibrary> dependencies = library.exports;
     int dependencyCount = dependencies.length;
     for (int i = 0; i < dependencyCount; i++) {
       ResolvableLibrary dependency = dependencies[i];
       if (!_librariesInCycle.contains(dependency) &&
           visitedLibraries.add(dependency.librarySource)) {
         if (dependency.libraryElement == null) {
           _ensureElementModel(dependency);
         } else {
           _ensureExports(dependency, visitedLibraries);
         }
         if (_taskData != null) {
           return;
         }
       }
     }
   }
 
   /**
-   * Ensure that all of the libraries that are exported by the given library (but are not
-   * themselves in the cycle) have element models built for them. If another task needs to be
-   * executed first in order to build the element model, that task is placed in [taskData].
-   *
-   * @param library the library being tested
+   * Ensure that all of the libraries that are exported by the given [library]
+   * (but are not themselves in the cycle) have element models built for them.
+   * If another task needs to be executed first in order to build the element
+   * model, that task is placed in [taskData].
    */
   void _ensureImports(ResolvableLibrary library) {
     List<ResolvableLibrary> dependencies = library.imports;
     int dependencyCount = dependencies.length;
     for (int i = 0; i < dependencyCount; i++) {
       ResolvableLibrary dependency = dependencies[i];
       if (!_librariesInCycle.contains(dependency) &&
           dependency.libraryElement == null) {
         _ensureElementModel(dependency);
         if (_taskData != null) {
           return;
         }
       }
     }
   }
 
   /**
-   * Ensure that all of the libraries that are either imported or exported by libraries in the
-   * cycle (but are not themselves in the cycle) have element models built for them.
+   * Ensure that all of the libraries that are either imported or exported by
+   * libraries in the cycle (but are not themselves in the cycle) have element
+   * models built for them.
    */
   void _ensureImportsAndExports() {
     HashSet<Source> visitedLibraries = new HashSet<Source>();
     int libraryCount = _librariesInCycle.length;
     for (int i = 0; i < libraryCount; i++) {
       ResolvableLibrary library = _librariesInCycle[i];
       _ensureImports(library);
       if (_taskData != null) {
         return;
       }
       _ensureExports(library, visitedLibraries);
       if (_taskData != null) {
         return;
       }
     }
   }
 
   /**
-   * Ensure that there is a resolvable compilation unit available for all of the compilation units
-   * in the given library.
-   *
-   * @param library the library for which resolvable compilation units must be available
-   * @return a list of (source, entry) pairs for all of the compilation units in the library
+   * Ensure that there is a resolvable compilation unit available for all of the
+   * compilation units in the given [library].
    */
   List<CycleBuilder_SourceEntryPair> _ensurePartsInLibrary(
       ResolvableLibrary library) {
     List<CycleBuilder_SourceEntryPair> pairs =
         new List<CycleBuilder_SourceEntryPair>();
     Source librarySource = library.librarySource;
     DartEntry libraryEntry =
         AnalysisContextImpl_this._getReadableDartEntry(librarySource);
     if (libraryEntry == null) {
       throw new AnalysisException(
@@ skipping 21 matching lines @@
       if (partEntry != null &&
           partEntry.getState(DartEntry.PARSED_UNIT) != CacheState.ERROR) {
         _ensureResolvableCompilationUnit(partSource, partEntry);
         pairs.add(new CycleBuilder_SourceEntryPair(partSource, partEntry));
       }
     }
     return pairs;
   }
 
   /**
-   * Ensure that there is a resolvable compilation unit available for the given source.
-   *
-   * @param source the source for which a resolvable compilation unit must be available
-   * @param dartEntry the entry associated with the source
+   * Ensure that there is a resolvable compilation unit available for the given
+   * [source].
    */
   void _ensureResolvableCompilationUnit(Source source, DartEntry dartEntry) {
     // The entry will be null if the source represents a non-Dart file.
     if (dartEntry != null && !dartEntry.hasResolvableCompilationUnit) {
       if (_taskData == null) {
         _taskData =
             AnalysisContextImpl_this._createParseDartTask(source, dartEntry);
       }
     }
   }
 
   HashSet<Source> _gatherSources(List<CycleBuilder_LibraryPair> libraryData) {
     int libraryCount = libraryData.length;
     HashSet<Source> sources = new HashSet<Source>();
     for (int i = 0; i < libraryCount; i++) {
       List<CycleBuilder_SourceEntryPair> entryPairs = libraryData[i].entryPairs;
       int entryCount = entryPairs.length;
       for (int j = 0; j < entryCount; j++) {
         sources.add(entryPairs[j].source);
       }
     }
     return sources;
   }
 
   /**
-   * Return the sources described by the given descriptor.
-   *
-   * @param source the source with which the sources are associated
-   * @param dartEntry the entry corresponding to the source
-   * @param descriptor the descriptor indicating which sources are to be returned
-   * @return the sources described by the given descriptor
+   * Return the sources described by the given [descriptor].
    */
   List<Source> _getSources(Source source, DartEntry dartEntry,
       DataDescriptor<List<Source>> descriptor) {
     if (dartEntry == null) {
       return Source.EMPTY_ARRAY;
     }
     CacheState exportState = dartEntry.getState(descriptor);
     if (exportState == CacheState.ERROR) {
       return Source.EMPTY_ARRAY;
     } else if (exportState != CacheState.VALID) {
       if (_taskData == null) {
         _taskData =
             AnalysisContextImpl_this._createParseDartTask(source, dartEntry);
       }
       return Source.EMPTY_ARRAY;
     }
     return dartEntry.getValue(descriptor);
   }
 }
 
 /**
- * Instances of the class `TaskData` represent information about the next task to be
- * performed. Each data has an implicit associated source: the source that might need to be
- * analyzed. There are essentially three states that can be represented:
+ * Information about the next task to be performed. Each data has an implicit
+ * associated source: the source that might need to be analyzed. There are
+ * essentially three states that can be represented:
+ *
  * * If [getTask] returns a non-`null` value, then that is the task that should
- * be executed to further analyze the associated source.
+ *   be executed to further analyze the associated source.
  * * Otherwise, if [isBlocked] returns `true`, then there is no work that can be
- * done, but analysis for the associated source is not complete.
- * * Otherwise, [getDependentSource] should return a source that needs to be analyzed
- * before the analysis of the associated source can be completed.
+ *   done, but analysis for the associated source is not complete.
+ * * Otherwise, [getDependentSource] should return a source that needs to be
+ *   analyzed before the analysis of the associated source can be completed.
  */
 class AnalysisContextImpl_TaskData {
   /**
    * The task that is to be performed.
    */
   final AnalysisTask task;
 
   /**
-   * A flag indicating whether the associated source is blocked waiting for its contents to be
-   * loaded.
+   * A flag indicating whether the associated source is blocked waiting for its
+   * contents to be loaded.
    */
   final bool _blocked;
 
   /**
    * Initialize a newly created data holder.
-   *
-   * @param task the task that is to be performed
-   * @param blocked `true` if the associated source is blocked waiting for its contents to
-   *          be loaded
    */
   AnalysisContextImpl_TaskData(this.task, this._blocked);
 
   /**
-   * Return `true` if the associated source is blocked waiting for its contents to be
-   * loaded.
-   *
-   * @return `true` if the associated source is blocked waiting for its contents to be
-   *         loaded
+   * Return `true` if the associated source is blocked waiting for its contents
+   * to be loaded.
    */
   bool get isBlocked => _blocked;
 
   @override
   String toString() {
     if (task == null) {
       return "blocked: $_blocked";
     }
     return task.toString();
   }
 }
 
 /**
- * The interface `AnalysisContextStatistics` defines access to statistics about a single
- * [AnalysisContext].
+ * Statistics and information about a single [AnalysisContext].
  */
 abstract class AnalysisContextStatistics {
   /**
    * Return the statistics for each kind of cached data.
    */
   List<AnalysisContextStatistics_CacheRow> get cacheRows;
 
   /**
-   * Return the exceptions that caused some entries to have a state of [CacheState.ERROR].
+   * Return the exceptions that caused some entries to have a state of
+   * [CacheState.ERROR].
    */
   List<CaughtException> get exceptions;
 
   /**
    * Return information about each of the partitions in the cache.
    */
   List<AnalysisContextStatistics_PartitionData> get partitionData;
 
   /**
-   * Return an array containing all of the sources in the cache.
+   * Return a list containing all of the sources in the cache.
    */
   List<Source> get sources;
 }
 
 /**
  * Information about single piece of data in the cache.
  */
 abstract class AnalysisContextStatistics_CacheRow {
   /**
    * List of possible states which can be queried.
@@ skipping 40 matching lines @@
    * Return the number of entries whose state is [state].
    */
   int getCount(CacheState state);
 }
 
 /**
  * Information about a single partition in the cache.
  */
 abstract class AnalysisContextStatistics_PartitionData {
   /**
-   * Return the number of entries in the partition that have an AST structure in one state or
-   * another.
+   * Return the number of entries in the partition that have an AST structure in
+   * one state or another.
    */
   int get astCount;
 
   /**
    * Return the total number of entries in the partition.
    */
   int get totalCount;
 }
 
 /**
@@ skipping 106 matching lines @@
     implements AnalysisContextStatistics_PartitionData {
   final int astCount;
 
   final int totalCount;
 
   AnalysisContextStatisticsImpl_PartitionDataImpl(
       this.astCount, this.totalCount);
 }
 
 /**
- * Instances of the class `AnalysisDelta` indicate changes to the types of analysis that
- * should be performed.
+ * A representation of changes to the types of analysis that should be
+ * performed.
  */
 class AnalysisDelta {
   /**
-   * A mapping from source to what type of analysis should be performed on that source.
+   * A mapping from source to what type of analysis should be performed on that
+   * source.
    */
   HashMap<Source, AnalysisLevel> _analysisMap =
       new HashMap<Source, AnalysisLevel>();
 
   /**
-   * Return a collection of the sources that have been added. This is equivalent to calling
-   * [getAnalysisLevels] and collecting all sources that do not have an analysis level of
-   * [AnalysisLevel.NONE].
-   *
-   * @return a collection of the sources
+   * Return a collection of the sources that have been added. This is equivalent
+   * to calling [getAnalysisLevels] and collecting all sources that do not have
+   * an analysis level of [AnalysisLevel.NONE].
    */
   List<Source> get addedSources {
     List<Source> result = new List<Source>();
     _analysisMap.forEach((Source source, AnalysisLevel level) {
       if (level != AnalysisLevel.NONE) {
         result.add(source);
       }
     });
     return result;
   }
 
   /**
-   * Return a mapping of sources to the level of analysis that should be performed.
-   *
-   * @return the analysis map
+   * Return a mapping of sources to the level of analysis that should be
+   * performed.
    */
   Map<Source, AnalysisLevel> get analysisLevels => _analysisMap;
 
   /**
-   * Record that the specified source should be analyzed at the specified level.
-   *
-   * @param source the source
-   * @param level the level at which the given source should be analyzed
+   * Record that the given [source] should be analyzed at the given [level].
    */
   void setAnalysisLevel(Source source, AnalysisLevel level) {
     _analysisMap[source] = level;
   }
 
   @override
   String toString() {
     StringBuffer buffer = new StringBuffer();
     bool needsSeparator = _appendSources(buffer, false, AnalysisLevel.ALL);
     needsSeparator =
         _appendSources(buffer, needsSeparator, AnalysisLevel.RESOLVED);
     _appendSources(buffer, needsSeparator, AnalysisLevel.NONE);
     return buffer.toString();
   }
 
   /**
-   * Appendto the given [builder] all sources with the given analysis [level],
+   * Appendto the given [buffer] all sources with the given analysis [level],
    * prefixed with a label and a separator if [needsSeparator] is `true`.
    */
   bool _appendSources(
       StringBuffer buffer, bool needsSeparator, AnalysisLevel level) {
     bool first = true;
     _analysisMap.forEach((Source source, AnalysisLevel sourceLevel) {
       if (sourceLevel == level) {
         if (first) {
           first = false;
           if (needsSeparator) {
@@ skipping 138 matching lines @@
     if (fileName == null) {
       return false;
     }
     String extension = FileNameUtilities.getExtension(fileName);
     return javaStringEqualsIgnoreCase(extension, SUFFIX_HTML) ||
         javaStringEqualsIgnoreCase(extension, SUFFIX_HTM);
   }
 }
 
 /**
- * The interface `AnalysisErrorInfo` contains the analysis errors and line information for the
- * errors.
+ * The analysis errors and line information for the errors.
  */
 abstract class AnalysisErrorInfo {
   /**
-   * Return the errors that as a result of the analysis, or `null` if there were no errors.
-   *
-   * @return the errors as a result of the analysis
+   * Return the errors that as a result of the analysis, or `null` if there were
+   * no errors.
    */
   List<AnalysisError> get errors;
 
   /**
-   * Return the line information associated with the errors, or `null` if there were no
-   * errors.
-   *
-   * @return the line information associated with the errors
+   * Return the line information associated with the errors, or `null` if there
+   * were no errors.
    */
   LineInfo get lineInfo;
 }
 
 /**
- * Instances of the class `AnalysisErrorInfoImpl` represent the analysis errors and line info
- * associated with a source.
+ * The analysis errors and line info associated with a source.
  */
 class AnalysisErrorInfoImpl implements AnalysisErrorInfo {
   /**
-   * The analysis errors associated with a source, or `null` if there are no errors.
+   * The analysis errors associated with a source, or `null` if there are no
+   * errors.
    */
   final List<AnalysisError> errors;
 
   /**
-   * The line information associated with the errors, or `null` if there are no errors.
+   * The line information associated with the errors, or `null` if there are no
+   * errors.
    */
   final LineInfo lineInfo;
 
   /**
-   * Initialize an newly created error info with the errors and line information
-   *
-   * @param errors the errors as a result of analysis
-   * @param lineinfo the line info for the errors
+   * Initialize an newly created error info with the given [errors] and
+   * [lineInfo].
    */
   AnalysisErrorInfoImpl(this.errors, this.lineInfo);
 }
 
 /**
- * The enumeration `AnalysisLevel` encodes the different levels at which a source can be
- * analyzed.
+ * The levels at which a source can be analyzed.
  */
 class AnalysisLevel extends Enum<AnalysisLevel> {
   /**
    * Indicates a source should be fully analyzed.
    */
   static const AnalysisLevel ALL = const AnalysisLevel('ALL', 0);
 
   /**
    * Indicates a source should be resolved and that errors, warnings and hints are needed.
    */
   static const AnalysisLevel ERRORS = const AnalysisLevel('ERRORS', 1);
 
   /**
    * Indicates a source should be resolved, but that errors, warnings and hints are not needed.
    */
   static const AnalysisLevel RESOLVED = const AnalysisLevel('RESOLVED', 2);
 
   /**
    * Indicates a source is not of interest to the client.
    */
   static const AnalysisLevel NONE = const AnalysisLevel('NONE', 3);
 
   static const List<AnalysisLevel> values = const [ALL, ERRORS, RESOLVED, NONE];
 
   const AnalysisLevel(String name, int ordinal) : super(name, ordinal);
 }
 
 /**
- * The interface `AnalysisListener` defines the behavior of objects that are listening for
- * results being produced by an analysis context.
+ * An object that is listening for results being produced by an analysis
+ * context.
  */
 abstract class AnalysisListener {
   /**
-   * Reports that a task is about to be performed by the given context.
-   *
-   * @param context the context in which the task is to be performed
-   * @param taskDescription a human readable description of the task that is about to be performed
+   * Reports that a task, described by the given [taskDescription] is about to
+   * be performed by the given [context].
    */
   void aboutToPerformTask(AnalysisContext context, String taskDescription);
 
   /**
-   * Reports that the errors associated with the given source in the given context has been updated
-   * to the given errors.
-   *
-   * @param context the context in which the new list of errors was produced
-   * @param source the source containing the errors that were computed
-   * @param errors the errors that were computed
-   * @param lineInfo the line information associated with the source
+   * Reports that the [errors] associated with the given [source] in the given
+   * [context] has been updated to the given errors. The [lineInfo] is the line
+   * information associated with the source.
    */
   void computedErrors(AnalysisContext context, Source source,
       List<AnalysisError> errors, LineInfo lineInfo);
 
   /**
-   * Reports that the given source is no longer included in the set of sources that are being
-   * analyzed by the given analysis context.
-   *
-   * @param context the context in which the source is being analyzed
-   * @param source the source that is no longer being analyzed
+   * Reports that the given [source] is no longer included in the set of sources
+   * that are being analyzed by the given analysis [context].
    */
   void excludedSource(AnalysisContext context, Source source);
 
   /**
-   * Reports that the given source is now included in the set of sources that are being analyzed by
-   * the given analysis context.
-   *
-   * @param context the context in which the source is being analyzed
-   * @param source the source that is now being analyzed
+   * Reports that the given [source] is now included in the set of sources that
+   * are being analyzed by the given analysis [context].
    */
   void includedSource(AnalysisContext context, Source source);
 
   /**
-   * Reports that the given Dart source was parsed in the given context.
-   *
-   * @param context the context in which the source was parsed
-   * @param source the source that was parsed
-   * @param unit the result of parsing the source in the given context
+   * Reports that the given Dart [source] was parsed in the given [context],
+   * producing the given [unit].
    */
   void parsedDart(AnalysisContext context, Source source, CompilationUnit unit);
 
   /**
-   * Reports that the given HTML source was parsed in the given context.
-   *
-   * @param context the context in which the source was parsed
-   * @param source the source that was parsed
-   * @param unit the result of parsing the source in the given context
+   * Reports that the given HTML [source] was parsed in the given [context].
    */
   void parsedHtml(AnalysisContext context, Source source, ht.HtmlUnit unit);
 
   /**
-   * Reports that the given Dart source was resolved in the given context.
-   *
-   * @param context the context in which the source was resolved
-   * @param source the source that was resolved
-   * @param unit the result of resolving the source in the given context
+   * Reports that the given Dart [source] was resolved in the given [context].
    */
   void resolvedDart(
       AnalysisContext context, Source source, CompilationUnit unit);
 
   /**
-   * Reports that the given HTML source was resolved in the given context.
-   *
-   * @param context the context in which the source was resolved
-   * @param source the source that was resolved
-   * @param unit the result of resolving the source in the given context
+   * Reports that the given HTML [source] was resolved in the given [context].
    */
   void resolvedHtml(AnalysisContext context, Source source, ht.HtmlUnit unit);
 }
 
 /**
  * Futures returned by [AnalysisContext] for pending analysis results will
  * complete with this error if it is determined that analysis results will
  * never become available (e.g. because the requested source is not subject to
  * analysis, or because the requested source is a part file which is not a part
  * of any known library).
@@ skipping 285 matching lines @@
   static bool _analyzeAllFunctionBodies(Source _) => true;
 
   /**
    * Predicate used for [analyzeFunctionBodiesPredicate] when
    * [analyzeFunctionBodies] is set to `false`.
    */
   static bool _analyzeNoFunctionBodies(Source _) => false;
 }
 
 /**
- * Instances of the class `AnalysisResult`
+ *
  */
 class AnalysisResult {
   /**
-   * The change notices associated with this result, or `null` if there were no changes and
-   * there is no more work to be done.
+   * The change notices associated with this result, or `null` if there were no
+   * changes and there is no more work to be done.
    */
   final List<ChangeNotice> _notices;
 
   /**
-   * The number of milliseconds required to determine which task was to be performed.
+   * The number of milliseconds required to determine which task was to be
+   * performed.
    */
   final int getTime;
 
   /**
    * The name of the class of the task that was performed.
    */
   final String taskClassName;
 
   /**
    * The number of milliseconds required to perform the task.
    */
   final int performTime;
 
   /**
-   * Initialize a newly created analysis result to have the given values.
-   *
-   * @param notices the change notices associated with this result
-   * @param getTime the number of milliseconds required to determine which task was to be performed
-   * @param taskClassName the name of the class of the task that was performed
-   * @param performTime the number of milliseconds required to perform the task
+   * Initialize a newly created analysis result to have the given values. The
+   * [notices] is the change notices associated with this result. The [getTime]
+   * is the number of milliseconds required to determine which task was to be
+   * performed. The [taskClassName] is the name of the class of the task that
+   * was performed. The [performTime] is the number of milliseconds required to
+   * perform the task.
    */
   AnalysisResult(
       this._notices, this.getTime, this.taskClassName, this.performTime);
 
   /**
-   * Return the change notices associated with this result, or `null` if there were no changes
-   * and there is no more work to be done.
-   *
-   * @return the change notices associated with this result
+   * Return the change notices associated with this result, or `null` if there
+   * were no changes and there is no more work to be done.
    */
   List<ChangeNotice> get changeNotices => _notices;
 
   /**
-   * Return `true` if there is more to be performed after the task that was performed.
-   *
-   * @return `true` if there is more to be performed after the task that was performed
+   * Return `true` if there is more to be performed after the task that was
+   * performed.
    */
   bool get hasMoreWork => _notices != null;
 }
 
 /**
- * The abstract class `AnalysisTask` defines the behavior of objects used to perform an
- * analysis task.
+ * An analysis task.
  */
 abstract class AnalysisTask {
   /**
    * The context in which the task is to be performed.
    */
   final InternalAnalysisContext context;
 
   /**
-   * The exception that was thrown while performing this task, or `null` if the task completed
-   * successfully.
+   * The exception that was thrown while performing this task, or `null` if the
+   * task completed successfully.
    */
   CaughtException _thrownException;
 
   /**
-   * Initialize a newly created task to perform analysis within the given context.
-   *
-   * @param context the context in which the task is to be performed
+   * Initialize a newly created task to perform analysis within the given
+   * [context].
    */
   AnalysisTask(this.context);
 
   /**
-   * Return the exception that was thrown while performing this task, or `null` if the task
-   * completed successfully.
-   *
-   * @return the exception that was thrown while performing this task
+   * Return the exception that was thrown while performing this task, or `null`
+   * if the task completed successfully.
    */
   CaughtException get exception => _thrownException;
 
   /**
    * Return a textual description of this task.
-   *
-   * @return a textual description of this task
    */
   String get taskDescription;
 
   /**
-   * Use the given visitor to visit this task.
-   *
-   * @param visitor the visitor that should be used to visit this task
-   * @return the value returned by the visitor
-   * @throws AnalysisException if the visitor throws the exception
+   * Use the given [visitor] to visit this task. Throws an [AnalysisException]
+   * if the visitor throws the exception.
    */
   accept(AnalysisTaskVisitor visitor);
 
   /**
-   * Perform this analysis task, protected by an exception handler.
-   *
-   * @throws AnalysisException if an exception occurs while performing the task
+   * Perform this analysis task, protected by an exception handler. Throws an
+   * [AnalysisException] if an exception occurs while performing the task.
    */
   void internalPerform();
 
   /**
-   * Perform this analysis task and use the given visitor to visit this task after it has completed.
-   *
-   * @param visitor the visitor used to visit this task after it has completed
-   * @return the value returned by the visitor
-   * @throws AnalysisException if the visitor throws the exception
+   * Perform this analysis task and use the given [visitor] to visit this task
+   * after it has completed. Throws an [AnalysisException] if the visitor throws
+   * the exception.
    */
   Object perform(AnalysisTaskVisitor visitor) {
     try {
       _safelyPerform();
     } on AnalysisException catch (exception, stackTrace) {
       _thrownException = new CaughtException(exception, stackTrace);
       AnalysisEngine.instance.logger.logInformation(
           "Task failed: $taskDescription",
           new CaughtException(exception, stackTrace));
     }
     return PerformanceStatistics.analysisTaskVisitor
         .makeCurrentWhile(() => accept(visitor));
   }
 
   @override
   String toString() => taskDescription;
 
   /**
    * Perform this analysis task, ensuring that all exceptions are wrapped in an
-   * [AnalysisException].
-   *
-   * @throws AnalysisException if any exception occurs while performing the task
+   * [AnalysisException]. Throws an [AnalysisException] if any exception occurs
+   * while performing the task
    */
   void _safelyPerform() {
     try {
       String contextName = context.name;
       if (contextName == null) {
         contextName = 'unnamed';
       }
       AnalysisEngine.instance.instrumentationService.logAnalysisTask(
           contextName, taskDescription);
       internalPerform();
     } on AnalysisException {
       rethrow;
     } catch (exception, stackTrace) {
       throw new AnalysisException(
           exception.toString(), new CaughtException(exception, stackTrace));
     }
   }
 }
 
 /**
- * An `AnalysisTaskVisitor` visits tasks. While tasks are not structured in any
+ * An object used to visit tasks. While tasks are not structured in any
  * interesting way, this class provides the ability to dispatch to an
  * appropriate method.
  */
 abstract class AnalysisTaskVisitor<E> {
   /**
    * Visit the given [task], returning the result of the visit. This method will
    * throw an AnalysisException if the visitor throws an exception.
    */
   E visitBuildUnitElementTask(BuildUnitElementTask task);
 
@@ skipping 91 matching lines @@
    * Initialize a newly created result holder to represent the value of data
    * described by the given [descriptor].
    */
   CachedResult(DataDescriptor descriptor) {
     state = CacheState.INVALID;
     value = descriptor.defaultValue;
   }
 }
 
 /**
- * Instances of the class `CachePartition` implement a single partition in an LRU cache of
- * information related to analysis.
+ * A single partition in an LRU cache of information related to analysis.
  */
 abstract class CachePartition {
   /**
-   * The context that owns this partition. Multiple contexts can reference a partition, but only one
-   * context can own it.
+   * The context that owns this partition. Multiple contexts can reference a
+   * partition, but only one context can own it.
    */
   final InternalAnalysisContext context;
 
   /**
-   * The maximum number of sources for which AST structures should be kept in the cache.
+   * The maximum number of sources for which AST structures should be kept in
+   * the cache.
    */
   int _maxCacheSize = 0;
 
   /**
    * The policy used to determine which pieces of data to remove from the cache.
    */
   final CacheRetentionPolicy _retentionPolicy;
 
   /**
-   * A table mapping the sources belonging to this partition to the information known about those
-   * sources.
+   * A table mapping the sources belonging to this partition to the information
+   * known about those sources.
    */
   HashMap<Source, SourceEntry> _sourceMap = new HashMap<Source, SourceEntry>();
 
   /**
-   * A list containing the most recently accessed sources with the most recently used at the end of
-   * the list. When more sources are added than the maximum allowed then the least recently used
-   * source will be removed and will have it's cached AST structure flushed.
+   * A list containing the most recently accessed sources with the most recently
+   * used at the end of the list. When more sources are added than the maximum
+   * allowed then the least recently used source will be removed and will have
+   * it's cached AST structure flushed.
    */
   List<Source> _recentlyUsed;
 
   /**
-   * Initialize a newly created cache to maintain at most the given number of AST structures in the
-   * cache.
-   *
-   * @param context the context that owns this partition
-   * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
-   *          the cache
-   * @param retentionPolicy the policy used to determine which pieces of data to remove from the
-   *          cache
+   * Initialize a newly created cache to maintain at most [maxCacheSize] AST
+   * structures in the cache. The cache is owned by the give [context], and the
+   * [retentionPolicy] will be used to determine which pieces of data to remove
+   * from the cache.
    */
   CachePartition(this.context, int maxCacheSize, this._retentionPolicy) {
     this._maxCacheSize = maxCacheSize;
     _recentlyUsed = new List<Source>();
   }
 
   /**
-   * Return the number of entries in this partition that have an AST associated with them.
-   *
-   * @return the number of entries in this partition that have an AST associated with them
+   * Return the number of entries in this partition that have an AST associated
+   * with them.
    */
   int get astSize {
     int astSize = 0;
     int count = _recentlyUsed.length;
     for (int i = 0; i < count; i++) {
       Source source = _recentlyUsed[i];
       SourceEntry sourceEntry = _sourceMap[source];
       if (sourceEntry is DartEntry) {
         if (sourceEntry.anyParsedCompilationUnit != null) {
           astSize++;
         }
       } else if (sourceEntry is HtmlEntry) {
         if (sourceEntry.anyParsedUnit != null) {
           astSize++;
         }
       }
     }
     return astSize;
   }
 
   /**
-   * Return a table mapping the sources known to the context to the information known about the
-   * source.
+   * Return a table mapping the sources known to the context to the information
+   * known about the source.
    *
-   * <b>Note:</b> This method is only visible for use by [AnalysisCache] and should not be
-   * used for any other purpose.
-   *
-   * @return a table mapping the sources known to the context to the information known about the
-   *         source
+   * <b>Note:</b> This method is only visible for use by [AnalysisCache] and
+   * should not be used for any other purpose.
    */
   Map<Source, SourceEntry> get map => _sourceMap;
 
   /**
-   * Set the maximum size of the cache to the given size.
-   *
-   * @param size the maximum number of sources for which AST structures should be kept in the cache
+   * Set the maximum size of the cache to the given [size].
    */
   void set maxCacheSize(int size) {
     _maxCacheSize = size;
     while (_recentlyUsed.length > _maxCacheSize) {
       if (!_flushAstFromCache()) {
         break;
       }
     }
   }
 
   /**
-   * Record that the AST associated with the given source was just read from the cache.
-   *
-   * @param source the source whose AST was accessed
+   * Record that the AST associated with the given source was just read from the
+   * cache.
    */
   void accessedAst(Source source) {
     if (_recentlyUsed.remove(source)) {
       _recentlyUsed.add(source);
       return;
     }
     while (_recentlyUsed.length >= _maxCacheSize) {
       if (!_flushAstFromCache()) {
         break;
       }
     }
     _recentlyUsed.add(source);
   }
 
   /**
-   * Return `true` if the given source is contained in this partition.
-   *
-   * @param source the source being tested
-   * @return `true` if the source is contained in this partition
+   * Return `true` if the given [source] is contained in this partition.
    */
   bool contains(Source source);
 
   /**
-   * Return the entry associated with the given source.
-   *
-   * @param source the source whose entry is to be returned
-   * @return the entry associated with the given source
+   * Return the entry associated with the given [source].
    */
   SourceEntry get(Source source) => _sourceMap[source];
 
   /**
-   * Return an iterator returning all of the map entries mapping sources to cache entries.
-   *
-   * @return an iterator returning all of the map entries mapping sources to cache entries
+   * Return an iterator returning all of the map entries mapping sources to
+   * cache entries.
    */
   MapIterator<Source, SourceEntry> iterator() =>
       new SingleMapIterator<Source, SourceEntry>(_sourceMap);
 
   /**
-   * Associate the given entry with the given source.
-   *
-   * @param source the source with which the entry is to be associated
-   * @param entry the entry to be associated with the source
+   * Associate the given [entry] with the given [source].
    */
   void put(Source source, SourceEntry entry) {
     entry.fixExceptionState();
     _sourceMap[source] = entry;
   }
 
   /**
-   * Remove all information related to the given source from this cache.
-   *
-   * @param source the source to be removed
+   * Remove all information related to the given [source] from this cache.
    */
   void remove(Source source) {
     _recentlyUsed.remove(source);
     _sourceMap.remove(source);
   }
 
   /**
-   * Record that the AST associated with the given source was just removed from the cache.
-   *
-   * @param source the source whose AST was removed
+   * Record that the AST associated with the given [source] was just removed
+   * from the cache.
    */
   void removedAst(Source source) {
     _recentlyUsed.remove(source);
   }
 
   /**
    * Return the number of sources that are mapped to cache entries.
-   *
-   * @return the number of sources that are mapped to cache entries
    */
   int size() => _sourceMap.length;
 
   /**
-   * Record that the AST associated with the given source was just stored to the cache.
-   *
-   * @param source the source whose AST was stored
+   * Record that the AST associated with the given [source] was just stored to
+   * the cache.
    */
   void storedAst(Source source) {
     if (_recentlyUsed.contains(source)) {
       return;
     }
     while (_recentlyUsed.length >= _maxCacheSize) {
       if (!_flushAstFromCache()) {
         break;
       }
     }
     _recentlyUsed.add(source);
   }
 
   /**
-   * Attempt to flush one AST structure from the cache.
-   *
-   * @return `true` if a structure was flushed
+   * Attempt to flush one AST structure from the cache. Return `true` if a
+   * structure was flushed.
    */
   bool _flushAstFromCache() {
     Source removedSource = _removeAstToFlush();
     if (removedSource == null) {
       return false;
     }
     SourceEntry sourceEntry = _sourceMap[removedSource];
     if (sourceEntry is HtmlEntry) {
       HtmlEntry htmlEntry = sourceEntry;
       htmlEntry.flushAstStructures();
     } else if (sourceEntry is DartEntry) {
       DartEntry dartEntry = sourceEntry;
       dartEntry.flushAstStructures();
     }
     return true;
   }
 
   /**
-   * Remove and return one source from the list of recently used sources whose AST structure can be
-   * flushed from the cache. The source that will be returned will be the source that has been
-   * unreferenced for the longest period of time but that is not a priority for analysis.
-   *
-   * @return the source that was removed
+   * Remove and return one source from the list of recently used sources whose
+   * AST structure can be flushed from the cache. The source that will be
+   * returned will be the source that has been unreferenced for the longest
+   * period of time but that is not a priority for analysis.
    */
   Source _removeAstToFlush() {
     int sourceToRemove = -1;
     for (int i = 0; i < _recentlyUsed.length; i++) {
       Source source = _recentlyUsed[i];
       RetentionPriority priority =
           _retentionPolicy.getAstPriority(source, _sourceMap[source]);
       if (priority == RetentionPriority.LOW) {
         return _recentlyUsed.removeAt(i);
       } else if (priority == RetentionPriority.MEDIUM && sourceToRemove < 0) {
         sourceToRemove = i;
       }
     }
     if (sourceToRemove < 0) {
       // This happens if the retention policy returns a priority of HIGH for all
       // of the sources that have been recently used. This is the case, for
       // example, when the list of priority sources is bigger than the current
       // cache size.
       return null;
     }
     return _recentlyUsed.removeAt(sourceToRemove);
   }
 }
 
 /**
- * Instances of the class `CacheRetentionPolicy` define the behavior of objects that determine
- * how important it is for data to be retained in the analysis cache.
+ * An object used to determine how important it is for data to be retained in
+ * the analysis cache.
  */
 abstract class CacheRetentionPolicy {
   /**
-   * Return the priority of retaining the AST structure for the given source.
-   *
-   * @param source the source whose AST structure is being considered for removal
-   * @param sourceEntry the entry representing the source
-   * @return the priority of retaining the AST structure for the given source
+   * Return the priority of retaining the AST structure for the given [source].
    */
   RetentionPriority getAstPriority(Source source, SourceEntry sourceEntry);
 }
 
 /**
  * The possible states of cached data.
  */
 class CacheState extends Enum<CacheState> {
   /**
    * The data is not in the cache and the last time an attempt was made to
@@ skipping 155 matching lines @@
       AnalysisEngine.instance.logger.logInformation("No line info: $source",
           new CaughtException(new AnalysisException(), null));
     }
   }
 
   @override
   String toString() => "Changes for ${source.fullName}";
 }
 
 /**
- * Instances of the class `ChangeSet` indicate which sources have been added, changed,
- * removed, or deleted. In the case of a changed source, there are multiple ways of indicating the
+ * An indication of which sources have been added, changed, removed, or deleted.
+ * In the case of a changed source, there are multiple ways of indicating the
  * nature of the change.
  *
- * No source should be added to the change set more than once, either with the same or a different
- * kind of change. It does not make sense, for example, for a source to be both added and removed,
- * and it is redundant for a source to be marked as changed in its entirety and changed in some
- * specific range.
+ * No source should be added to the change set more than once, either with the
+ * same or a different kind of change. It does not make sense, for example, for
+ * a source to be both added and removed, and it is redundant for a source to be
+ * marked as changed in its entirety and changed in some specific range.
  */
 class ChangeSet {
   /**
    * A list containing the sources that have been added.
    */
   final List<Source> addedSources = new List<Source>();
 
   /**
    * A list containing the sources that have been changed.
    */
   final List<Source> changedSources = new List<Source>();
 
   /**
-   * A table mapping the sources whose content has been changed to the current content of those
-   * sources.
+   * A table mapping the sources whose content has been changed to the current
+   * content of those sources.
    */
   HashMap<Source, String> _changedContent = new HashMap<Source, String>();
 
   /**
-   * A table mapping the sources whose content has been changed within a single range to the current
-   * content of those sources and information about the affected range.
+   * A table mapping the sources whose content has been changed within a single
+   * range to the current content of those sources and information about the
+   * affected range.
    */
   final HashMap<Source, ChangeSet_ContentChange> changedRanges =
       new HashMap<Source, ChangeSet_ContentChange>();
 
   /**
    * A list containing the sources that have been removed.
    */
   final List<Source> removedSources = new List<Source>();
 
   /**
-   * A list containing the source containers specifying additional sources that have been removed.
+   * A list containing the source containers specifying additional sources that
+   * have been removed.
    */
   final List<SourceContainer> removedContainers = new List<SourceContainer>();
 
   /**
    * A list containing the sources that have been deleted.
    */
   final List<Source> deletedSources = new List<Source>();
 
   /**
-   * Return a table mapping the sources whose content has been changed to the current content of
-   * those sources.
-   *
-   * @return a table mapping the sources whose content has been changed to the current content of
-   *         those sources
+   * Return a table mapping the sources whose content has been changed to the
+   * current content of those sources.
    */
   Map<Source, String> get changedContents => _changedContent;
 
   /**
    * Return `true` if this change set does not contain any changes.
-   *
-   * @return `true` if this change set does not contain any changes
    */
   bool get isEmpty => addedSources.isEmpty &&
       changedSources.isEmpty &&
       _changedContent.isEmpty &&
       changedRanges.isEmpty &&
       removedSources.isEmpty &&
       removedContainers.isEmpty &&
       deletedSources.isEmpty;
 
   /**
-   * Record that the specified source has been added and that its content is the default contents of
-   * the source.
-   *
-   * @param source the source that was added
+   * Record that the specified [source] has been added and that its content is
+   * the default contents of the source.
    */
   void addedSource(Source source) {
     addedSources.add(source);
   }
 
   /**
-   * Record that the specified source has been changed and that its content is the given contents.
-   *
-   * @param source the source that was changed
-   * @param contents the new contents of the source, or `null` if the default contents of the
-   *          source are to be used
+   * Record that the specified [source] has been changed and that its content is
+   * the given [contents].
    */
   void changedContent(Source source, String contents) {
     _changedContent[source] = contents;
   }
 
   /**
-   * Record that the specified source has been changed and that its content is the given contents.
-   *
-   * @param source the source that was changed
-   * @param contents the new contents of the source
-   * @param offset the offset into the current contents
-   * @param oldLength the number of characters in the original contents that were replaced
-   * @param newLength the number of characters in the replacement text
+   * Record that the specified [source] has been changed and that its content is
+   * the given [contents]. The [offset] is the offset into the current contents.
+   * The [oldLength] is the number of characters in the original contents that
+   * were replaced. The [newLength] is the number of characters in the
+   * replacement text.
    */
   void changedRange(Source source, String contents, int offset, int oldLength,
       int newLength) {
     changedRanges[source] =
         new ChangeSet_ContentChange(contents, offset, oldLength, newLength);
   }
 
   /**
-   * Record that the specified source has been changed. If the content of the source was previously
-   * overridden, this has no effect (the content remains overridden). To cancel (or change) the
-   * override, use [changedContent] instead.
-   *
-   * @param source the source that was changed
+   * Record that the specified [source] has been changed. If the content of the
+   * source was previously overridden, this has no effect (the content remains
+   * overridden). To cancel (or change) the override, use [changedContent]
+   * instead.
    */
   void changedSource(Source source) {
     changedSources.add(source);
   }
 
   /**
-   * Record that the specified source has been deleted.
-   *
-   * @param source the source that was deleted
+   * Record that the specified [source] has been deleted.
    */
   void deletedSource(Source source) {
     deletedSources.add(source);
   }
 
   /**
-   * Record that the specified source container has been removed.
-   *
-   * @param container the source container that was removed
+   * Record that the specified source [container] has been removed.
    */
   void removedContainer(SourceContainer container) {
     if (container != null) {
       removedContainers.add(container);
     }
   }
 
   /**
-   * Record that the specified source has been removed.
-   *
-   * @param source the source that was removed
+   * Record that the specified [source] has been removed.
    */
   void removedSource(Source source) {
     if (source != null) {
       removedSources.add(source);
     }
   }
 
   @override
   String toString() {
     StringBuffer buffer = new StringBuffer();
@@ skipping 21 matching lines @@
       } else {
         buffer.write(", and more from ");
         buffer.write(count);
         buffer.write(" containers");
       }
     }
     return buffer.toString();
   }
 
   /**
-   * Append the given sources to the given builder, prefixed with the given label and possibly a
-   * separator.
-   *
-   * @param builder the builder to which the sources are to be appended
-   * @param sources the sources to be appended
-   * @param needsSeparator `true` if a separator is needed before the label
-   * @param label the label used to prefix the sources
-   * @return `true` if future lists of sources will need a separator
+   * Append the given [sources] to the given [buffer], prefixed with the given
+   * [label] and a separator if [needsSeparator] is `true`. Return `true` if
+   * future lists of sources will need a separator.
    */
   bool _appendSources(StringBuffer buffer, List<Source> sources,
       bool needsSeparator, String label) {
     if (sources.isEmpty) {
       return needsSeparator;
     }
     if (needsSeparator) {
       buffer.write("; ");
     }
     buffer.write(label);
     String prefix = " ";
     for (Source source in sources) {
       buffer.write(prefix);
       buffer.write(source.fullName);
       prefix = ", ";
     }
     return true;
   }
 
   /**
-   * Append the given sources to the given builder, prefixed with the given label and possibly a
-   * separator.
-   *
-   * @param builder the builder to which the sources are to be appended
-   * @param sources the sources to be appended
-   * @param needsSeparator `true` if a separator is needed before the label
-   * @param label the label used to prefix the sources
-   * @return `true` if future lists of sources will need a separator
+   * Append the given [sources] to the given [builder], prefixed with the given
+   * [label] and a separator if [needsSeparator] is `true`. Return `true` if
+   * future lists of sources will need a separator.
    */
   bool _appendSources2(StringBuffer buffer, HashMap<Source, dynamic> sources,
       bool needsSeparator, String label) {
     if (sources.isEmpty) {
       return needsSeparator;
     }
     if (needsSeparator) {
       buffer.write("; ");
     }
     buffer.write(label);
     String prefix = " ";
     for (Source source in sources.keys.toSet()) {
       buffer.write(prefix);
       buffer.write(source.fullName);
       prefix = ", ";
     }
     return true;
   }
 }
 
 /**
- * Instances of the class `ContentChange` represent a change to the content of a source.
+ * A change to the content of a source.
  */
 class ChangeSet_ContentChange {
   /**
    * The new contents of the source.
    */
   final String contents;
 
   /**
    * The offset into the current contents.
    */
   final int offset;
 
   /**
    * The number of characters in the original contents that were replaced
    */
   final int oldLength;
 
   /**
    * The number of characters in the replacement text.
    */
   final int newLength;
 
   /**
-   * Initialize a newly created change object to represent a change to the content of a source.
-   *
-   * @param contents the new contents of the source
-   * @param offset the offset into the current contents
-   * @param oldLength the number of characters in the original contents that were replaced
-   * @param newLength the number of characters in the replacement text
+   * Initialize a newly created change object to represent a change to the
+   * content of a source. The [contents] is the new contents of the source. The
+   * [offse] ist the offset into the current contents. The [oldLength] is the
+   * number of characters in the original contents that were replaced. The
+   * [newLength] is the number of characters in the replacement text.
    */
   ChangeSet_ContentChange(
       this.contents, this.offset, this.oldLength, this.newLength);
 }
 
 /**
- * Instances of the class `LibraryPair` hold a library and a list of the (source, entry)
- * pairs for compilation units in the library.
+ * A pair containing a library and a list of the (source, entry) pairs for
+ * compilation units in the library.
  */
 class CycleBuilder_LibraryPair {
   /**
    * The library containing the compilation units.
    */
   ResolvableLibrary library;
 
   /**
-   * The (source, entry) pairs representing the compilation units in the library.
+   * The (source, entry) pairs representing the compilation units in the
+   * library.
    */
   List<CycleBuilder_SourceEntryPair> entryPairs;
 
   /**
-   * Initialize a newly created pair.
-   *
-   * @param library the library containing the compilation units
-   * @param entryPairs the (source, entry) pairs representing the compilation units in the
-   *          library
+   * Initialize a newly created pair from the given [library] and [entryPairs].
    */
   CycleBuilder_LibraryPair(ResolvableLibrary library,
       List<CycleBuilder_SourceEntryPair> entryPairs) {
     this.library = library;
     this.entryPairs = entryPairs;
   }
 }
 
 /**
- * Instances of the class `SourceEntryPair` hold a source and the cache entry associated
- * with that source. They are used to reduce the number of times an entry must be looked up in
- * the [cache].
+ * A pair containing a source and the cache entry associated with that source.
+ * They are used to reduce the number of times an entry must be looked up in the
+ * [cache].
  */
 class CycleBuilder_SourceEntryPair {
   /**
    * The source associated with the entry.
    */
   Source source;
 
   /**
    * The entry associated with the source.
    */
   DartEntry entry;
 
   /**
-   * Initialize a newly created pair.
-   *
-   * @param source the source associated with the entry
-   * @param entry the entry associated with the source
+   * Initialize a newly created pair from the given [source] and [entry].
    */
   CycleBuilder_SourceEntryPair(Source source, DartEntry entry) {
     this.source = source;
     this.entry = entry;
   }
 }
 
 /**
- * A `DartEntry` maintains the information cached by an analysis context about
- * an individual Dart file.
+ * The information cached by an analysis context about an individual Dart file.
  */
 class DartEntry extends SourceEntry {
   /**
    * The data descriptor representing the element model representing a single
    * compilation unit. This model is incomplete and should not be used except as
    * input to another task.
    */
   static final DataDescriptor<List<AnalysisError>> BUILT_ELEMENT =
       new DataDescriptor<List<AnalysisError>>("DartEntry.BUILT_ELEMENT");
 
@@ skipping 176 matching lines @@
       state = state._nextState;
     }
     if (errors.length == 0) {
       return AnalysisError.NO_ERRORS;
     }
     return errors;
   }
 
   /**
    * Return a valid parsed compilation unit, either an unresolved AST structure
-   * or the result of resolving the AST structure in the context of some library,
-   * or `null` if there is no parsed compilation unit available.
+   * or the result of resolving the AST structure in the context of some
+   * library, or `null` if there is no parsed compilation unit available.
    */
   CompilationUnit get anyParsedCompilationUnit {
     if (getState(PARSED_UNIT) == CacheState.VALID) {
       return getValue(PARSED_UNIT);
     }
     ResolutionState state = _resolutionState;
     while (state != null) {
       if (state.getState(BUILT_UNIT) == CacheState.VALID) {
         return state.getValue(BUILT_UNIT);
       }
@@ skipping 18 matching lines @@
     return null;
   }
 
   /**
    * The libraries that are known to contain this part.
    */
   List<Source> get containingLibraries => _containingLibraries;
 
   /**
    * Set the list of libraries that contain this compilation unit to contain
-   * only the given source. This method should only be invoked on entries that
-   * represent a library.
-   *
-   * @param librarySource the source of the single library that the list should contain
+   * only the given [librarySource]. This method should only be invoked on
+   * entries that represent a library.
    */
   void set containingLibrary(Source librarySource) {
     _containingLibraries.clear();
     _containingLibraries.add(librarySource);
   }
 
   @override
   List<DataDescriptor> get descriptors {
     List<DataDescriptor> result = super.descriptors;
     result.addAll(<DataDescriptor>[
@@ skipping 255 matching lines @@
 
   @override
   void recordContentError(CaughtException exception) {
     super.recordContentError(exception);
     recordScanError(exception);
   }
 
   /**
    * Record that an error occurred while attempting to generate hints for the
    * source represented by this entry. This will set the state of all
-   * verification information as being in error.
-   *
-   * @param librarySource the source of the library in which hints were being generated
-   * @param exception the exception that shows where the error occurred
+   * verification information as being in error. The [librarySource] is the
+   * source of the library in which hints were being generated. The [exception]
+   * is the exception that shows where the error occurred.
    */
   void recordHintErrorInLibrary(
       Source librarySource, CaughtException exception) {
     this.exception = exception;
     ResolutionState state = _getOrCreateResolutionState(librarySource);
     state.recordHintError();
   }
 
   /**
    * Record that an error occurred while attempting to generate lints for the
    * source represented by this entry. This will set the state of all
-   * verification information as being in error.
-   *
-   * @param librarySource the source of the library in which lints were being generated
-   * @param exception the exception that shows where the error occurred
+   * verification information as being in error. The [librarySource] is the
+   * source of the library in which lints were being generated. The [exception]
+   * is the exception that shows where the error occurred.
    */
   void recordLintErrorInLibrary(
       Source librarySource, CaughtException exception) {
     this.exception = exception;
     ResolutionState state = _getOrCreateResolutionState(librarySource);
     state.recordLintError();
   }
 
   /**
    * Record that an [exception] occurred while attempting to scan or parse the
    * entry represented by this entry. This will set the state of all information,
    * including any resolution-based information, as being in error.
    */
   void recordParseError(CaughtException exception) {
     setState(SOURCE_KIND, CacheState.ERROR);
     setState(PARSE_ERRORS, CacheState.ERROR);
     setState(PARSED_UNIT, CacheState.ERROR);
     setState(EXPORTED_LIBRARIES, CacheState.ERROR);
     setState(IMPORTED_LIBRARIES, CacheState.ERROR);
     setState(INCLUDED_PARTS, CacheState.ERROR);
     recordResolutionError(exception);
   }
 
   /**
    * Record that an [exception] occurred while attempting to resolve the source
    * represented by this entry. This will set the state of all resolution-based
    * information as being in error, but will not change the state of any parse
    * results.
-   *
-   * @param exception the exception that shows where the error occurred
    */
   void recordResolutionError(CaughtException exception) {
     this.exception = exception;
     setState(ELEMENT, CacheState.ERROR);
     setState(IS_CLIENT, CacheState.ERROR);
     setState(IS_LAUNCHABLE, CacheState.ERROR);
     setState(PUBLIC_NAMESPACE, CacheState.ERROR);
     _resolutionState.recordResolutionErrorsInAllLibraries();
   }
 
   /**
-   * Record that an error occurred while attempting to resolve the source represented by this entry.
-   * This will set the state of all resolution-based information as being in error, but will not
-   * change the state of any parse results.
-   *
-   * @param librarySource the source of the library in which resolution was being performed
-   * @param exception the exception that shows where the error occurred
+   * Record that an error occurred while attempting to resolve the source
+   * represented by this entry. This will set the state of all resolution-based
+   * information as being in error, but will not change the state of any parse
+   * results. The [librarySource] is the source of the library in which
+   * resolution was being performed. The [exception] is the exception that shows
+   * where the error occurred.
    */
   void recordResolutionErrorInLibrary(
       Source librarySource, CaughtException exception) {
     this.exception = exception;
     setState(ELEMENT, CacheState.ERROR);
     setState(IS_CLIENT, CacheState.ERROR);
     setState(IS_LAUNCHABLE, CacheState.ERROR);
     setState(PUBLIC_NAMESPACE, CacheState.ERROR);
     ResolutionState state = _getOrCreateResolutionState(librarySource);
     state.recordResolutionError();
   }
 
   /**
    * Record that an [exception] occurred while attempting to scan or parse the
-   * entry represented by this entry. This will set the state of all information,
-   * including any resolution-based information, as being in error.
+   * entry represented by this entry. This will set the state of all
+   * information, including any resolution-based information, as being in error.
    */
   @override
   void recordScanError(CaughtException exception) {
     super.recordScanError(exception);
     setState(SCAN_ERRORS, CacheState.ERROR);
     setState(TOKEN_STREAM, CacheState.ERROR);
     recordParseError(exception);
   }
 
   /**
    * Record that an [exception] occurred while attempting to generate errors and
    * warnings for the source represented by this entry. This will set the state
-   * of all verification information as being in error.
-   *
-   * @param librarySource the source of the library in which verification was being performed
-   * @param exception the exception that shows where the error occurred
+   * of all verification information as being in error. The [librarySource] is
+   * the source of the library in which verification was being performed. The
+   * [exception] is the exception that shows where the error occurred.
    */
   void recordVerificationErrorInLibrary(
       Source librarySource, CaughtException exception) {
     this.exception = exception;
     ResolutionState state = _getOrCreateResolutionState(librarySource);
     state.recordVerificationError();
   }
 
   /**
    * Remove the given [library] from the list of libraries that contain this
    * part. This method should only be invoked on entries that represent a part.
-   *
-   * @param librarySource the source of the library to be removed
    */
   void removeContainingLibrary(Source library) {
     _containingLibraries.remove(library);
   }
 
   /**
    * Remove any resolution information associated with this compilation unit
    * being part of the given [library], presumably because it is no longer part
    * of the library.
    */
@@ skipping 14 matching lines @@
             break;
           }
           priorState = state;
           state = state._nextState;
         }
       }
     }
   }
 
   /**
-   * Set the state of the data represented by the given descriptor in the context of the given
-   * library to the given state.
-   *
-   * @param descriptor the descriptor representing the data whose state is to be set
-   * @param librarySource the source of the defining compilation unit of the library that is the
-   *          context for the data
-   * @param cacheState the new state of the data represented by the given descriptor
+   * Set the state of the data represented by the given [descriptor] in the
+   * context of the given [library] to the given [state].
    */
   void setStateInLibrary(
-      DataDescriptor descriptor, Source librarySource, CacheState cacheState) {
+      DataDescriptor descriptor, Source library, CacheState state) {
     if (!_isValidLibraryDescriptor(descriptor)) {
       throw new ArgumentError("Invalid descriptor: $descriptor");
     }
-    ResolutionState state = _getOrCreateResolutionState(librarySource);
-    state.setState(descriptor, cacheState);
+    ResolutionState resolutionState = _getOrCreateResolutionState(library);
+    resolutionState.setState(descriptor, state);
   }
 
   /**
-   * Set the value of the data represented by the given descriptor in the context of the given
-   * library to the given value, and set the state of that data to [CacheState.VALID].
-   *
-   * @param descriptor the descriptor representing which data is to have its value set
-   * @param librarySource the source of the defining compilation unit of the library that is the
-   *          context for the data
-   * @param value the new value of the data represented by the given descriptor and library
+   * Set the value of the data represented by the given [descriptor] in the
+   * context of the given [library] to the given [value], and set the state of
+   * that data to [CacheState.VALID].
    */
   void setValueInLibrary(
-      DataDescriptor descriptor, Source librarySource, Object value) {
+      DataDescriptor descriptor, Source library, Object value) {
     if (!_isValidLibraryDescriptor(descriptor)) {
       throw new ArgumentError("Invalid descriptor: $descriptor");
     }
-    ResolutionState state = _getOrCreateResolutionState(librarySource);
+    ResolutionState state = _getOrCreateResolutionState(library);
     state.setValue(descriptor, value);
   }
 
   /**
-   * Invalidate all of the resolution information associated with the compilation unit.
-   *
-   * @param invalidateUris true if the cached results of converting URIs to source files should also
-   *          be invalidated.
+   * Invalidate all of the resolution information associated with the
+   * compilation unit. The flag [invalidateUris] should be `true` if the cached
+   * results of converting URIs to source files should also be invalidated.
    */
   void _discardCachedResolutionInformation(bool invalidateUris) {
     setState(ELEMENT, CacheState.INVALID);
     setState(IS_CLIENT, CacheState.INVALID);
     setState(IS_LAUNCHABLE, CacheState.INVALID);
     setState(PUBLIC_NAMESPACE, CacheState.INVALID);
     _resolutionState.invalidateAllResolutionInformation();
     if (invalidateUris) {
       setState(EXPORTED_LIBRARIES, CacheState.INVALID);
       setState(IMPORTED_LIBRARIES, CacheState.INVALID);
       setState(INCLUDED_PARTS, CacheState.INVALID);
     }
   }
 
   /**
-   * Return a resolution state for the specified library, creating one as necessary.
-   *
-   * @param librarySource the library source (not `null`)
-   * @return the resolution state (not `null`)
+   * Return a resolution state for the specified [library], creating one as
+   * necessary.
    */
-  ResolutionState _getOrCreateResolutionState(Source librarySource) {
+  ResolutionState _getOrCreateResolutionState(Source library) {
     ResolutionState state = _resolutionState;
     if (state._librarySource == null) {
-      state._librarySource = librarySource;
+      state._librarySource = library;
       return state;
     }
-    while (state._librarySource != librarySource) {
+    while (state._librarySource != library) {
       if (state._nextState == null) {
         ResolutionState newState = new ResolutionState();
-        newState._librarySource = librarySource;
+        newState._librarySource = library;
         state._nextState = newState;
         return newState;
       }
       state = state._nextState;
     }
     return state;
   }
 
   @override
   bool _isValidDescriptor(DataDescriptor descriptor) {
@@ skipping 133 matching lines @@
     _writeStateOn(buffer, "includedParts", INCLUDED_PARTS);
     _writeStateOn(buffer, "element", ELEMENT);
     _writeStateOn(buffer, "publicNamespace", PUBLIC_NAMESPACE);
     _writeStateOn(buffer, "clientServer", IS_CLIENT);
     _writeStateOn(buffer, "launchable", IS_LAUNCHABLE);
     _resolutionState._writeOn(buffer);
   }
 }
 
 /**
- * Instances of the class `DataDescriptor` are immutable constants representing data that can
- * be stored in the cache.
+ * An immutable constant representing data that can be stored in the cache.
  */
 class DataDescriptor<E> {
   /**
    * The next artificial hash code.
    */
   static int _NEXT_HASH_CODE = 0;
 
   /**
    * The artifitial hash code for this object.
    */
@@ skipping 16 matching lines @@
   DataDescriptor(this._name, [this.defaultValue = null]);
 
   @override
   int get hashCode => _hashCode;
 
   @override
   String toString() => _name;
 }
 
 /**
- * Instances of the class `DefaultRetentionPolicy` implement a retention policy that will keep
- * AST's in the cache if there is analysis information that needs to be computed for a source, where
- * the computation is dependent on having the AST.
+ * A retention policy that will keep AST's in the cache if there is analysis
+ * information that needs to be computed for a source, where the computation is
+ * dependent on having the AST.
  */
 class DefaultRetentionPolicy implements CacheRetentionPolicy {
   /**
    * An instance of this class that can be shared.
    */
   static DefaultRetentionPolicy POLICY = new DefaultRetentionPolicy();
 
   /**
-   * Return `true` if there is analysis information in the given entry that needs to be
-   * computed, where the computation is dependent on having the AST.
-   *
-   * @param dartEntry the entry being tested
-   * @return `true` if there is analysis information that needs to be computed from the AST
+   * Return `true` if there is analysis information in the given [dartEntry]
+   * that needs to be computed, where the computation is dependent on having the
+   * AST.
    */
   bool astIsNeeded(DartEntry dartEntry) =>
       dartEntry.hasInvalidData(DartEntry.HINTS) ||
           dartEntry.hasInvalidData(DartEntry.LINTS) ||
           dartEntry.hasInvalidData(DartEntry.VERIFICATION_ERRORS) ||
           dartEntry.hasInvalidData(DartEntry.RESOLUTION_ERRORS);
 
   @override
   RetentionPriority getAstPriority(Source source, SourceEntry sourceEntry) {
     if (sourceEntry is DartEntry) {
@@ skipping 137 matching lines @@
         CompileTimeErrorCode.URI_DOES_NOT_EXIST, [directive.uriContent]));
   }
 }
 
 /**
  * Instances of the class `GenerateDartHintsTask` generate hints for a single Dart library.
  */
 class GenerateDartHintsTask extends AnalysisTask {
   /**
    * The compilation units that comprise the library, with the defining compilation unit appearing
-   * first in the array.
+   * first in the list.
    */
   final List<TimestampedData<CompilationUnit>> _units;
 
   /**
    * The element model for the library being analyzed.
    */
   final LibraryElement libraryElement;
 
   /**
    * A table mapping the sources that were analyzed to the hints that were
    * generated for the sources.
    */
   HashMap<Source, List<AnalysisError>> _hintMap;
 
   /**
    * Initialize a newly created task to perform analysis within the given context.
    *
    * @param context the context in which the task is to be performed
    * @param units the compilation units that comprise the library, with the defining compilation
-   *          unit appearing first in the array
+   *          unit appearing first in the list
    * @param libraryElement the element model for the library being analyzed
    */
   GenerateDartHintsTask(
       InternalAnalysisContext context, this._units, this.libraryElement)
       : super(context);
 
   /**
    * Return a table mapping the sources that were analyzed to the hints that were generated for the
    * sources, or `null` if the task has not been performed or if the analysis did not complete
    * normally.
@@ skipping 42 matching lines @@
       Source source = _units[i].data.element.source;
       _hintMap[source] = errorListener.getErrorsForSource(source);
     }
   }
 }
 
 /// Generates lint feedback for a single Dart library.
 class GenerateDartLintsTask extends AnalysisTask {
 
   ///The compilation units that comprise the library, with the defining
-  ///compilation unit appearing first in the array.
+  ///compilation unit appearing first in the list.
   final List<TimestampedData<CompilationUnit>> _units;
 
   /// The element model for the library being analyzed.
   final LibraryElement libraryElement;
 
   /// A mapping of analyzed sources to their associated lint warnings.
   /// May be [null] if the task has not been performed or if analysis did not
   /// complete normally.
   HashMap<Source, List<AnalysisError>> lintMap;
 
@@ skipping 119 matching lines @@
     } catch (exception, stackTrace) {
       errors.add(new AnalysisError.con1(
           source, ScannerErrorCode.UNABLE_GET_CONTENT, [exception]));
       throw new AnalysisException("Could not get contents of $source",
           new CaughtException(exception, stackTrace));
     }
   }
 }
 
 /**
- * An `HtmlEntry` maintains the information cached by an analysis context about
- * an individual HTML file.
+ * The information cached by an analysis context about an individual HTML file.
  */
 class HtmlEntry extends SourceEntry {
   /**
    * The data descriptor representing the HTML element.
    */
   static final DataDescriptor<HtmlElement> ELEMENT =
       new DataDescriptor<HtmlElement>("HtmlEntry.ELEMENT");
 
   /**
    * The data descriptor representing the hints resulting from auditing the
@@ skipping 488 matching lines @@
           IncrementalResolver resolver = new IncrementalResolver(
               element, cache.offset, cache.oldLength, cache.newLength);
           resolver.resolve(parser.updatedNode);
         }
       }
     }
   }
 }
 
 /**
- * The interface `InternalAnalysisContext` defines additional behavior for an analysis context
- * that is required by internal users of the context.
+ * Additional behavior for an analysis context that is required by internal
+ * users of the context.
  */
 abstract class InternalAnalysisContext implements AnalysisContext {
   /**
    * Allow the client to supply its own content cache.  This will take the
    * place of the content cache created by default, allowing clients to share
    * the content cache between contexts.
    */
   set contentCache(ContentCache value);
 
   /**
-   * Return an array containing all of the sources that have been marked as priority sources.
-   * Clients must not modify the returned array.
-   *
-   * @return the sources that have been marked as priority sources
+   * Return a list containing all of the sources that have been marked as
+   * priority sources. Clients must not modify the returned list.
    */
   List<Source> get prioritySources;
 
-  /** A factory to override how [ResolverVisitor] is created. */
+  /**
+   * A factory to override how [ResolverVisitor] is created.
+   */
   ResolverVisitorFactory get resolverVisitorFactory;
 
   /**
    * Returns a statistics about this context.
    */
   AnalysisContextStatistics get statistics;
 
   /**
    * Sets the [TypeProvider] for this context.
    */
   void set typeProvider(TypeProvider typeProvider);
 
-  /** A factory to override how [TypeResolverVisitor] is created. */
+  /**
+   * A factory to override how [TypeResolverVisitor] is created.
+   */
   TypeResolverVisitorFactory get typeResolverVisitorFactory;
 
   /**
-   * Add the given source with the given information to this context.
-   *
-   * @param source the source to be added
-   * @param info the information about the source
+   * Add the given [source] with the given [information] to this context.
    */
-  void addSourceInfo(Source source, SourceEntry info);
+  void addSourceInfo(Source source, SourceEntry information);
 
   /**
-   * Return an array containing the sources of the libraries that are exported by the library with
-   * the given source. The array will be empty if the given source is invalid, if the given source
-   * does not represent a library, or if the library does not export any other libraries.
+   * Return a list containing the sources of the libraries that are exported by
+   * the library with the given [source]. The list will be empty if the given
+   * source is invalid, if the given source does not represent a library, or if
+   * the library does not export any other libraries.
    *
-   * @param source the source representing the library whose exports are to be returned
-   * @return the sources of the libraries that are exported by the given library
-   * @throws AnalysisException if the exported libraries could not be computed
+   * Throws an [AnalysisException] if the exported libraries could not be
+   * computed.
    */
   List<Source> computeExportedLibraries(Source source);
 
   /**
-   * Return an array containing the sources of the libraries that are imported by the library with
-   * the given source. The array will be empty if the given source is invalid, if the given source
-   * does not represent a library, or if the library does not import any other libraries.
+   * Return a list containing the sources of the libraries that are imported by
+   * the library with the given [source]. The list will be empty if the given
+   * source is invalid, if the given source does not represent a library, or if
+   * the library does not import any other libraries.
    *
-   * @param source the source representing the library whose imports are to be returned
-   * @return the sources of the libraries that are imported by the given library
-   * @throws AnalysisException if the imported libraries could not be computed
+   * Throws an [AnalysisException] if the imported libraries could not be
+   * computed.
    */
   List<Source> computeImportedLibraries(Source source);
 
   /**
-   * Return an AST structure corresponding to the given source, but ensure that the structure has
-   * not already been resolved and will not be resolved by any other threads or in any other
-   * library.
+   * Return an AST structure corresponding to the given [source], but ensure
+   * that the structure has not already been resolved and will not be resolved
+   * by any other threads or in any other library.
+   *
+   * Throws an [AnalysisException] if the analysis could not be performed.
    *
    * <b>Note:</b> This method cannot be used in an async environment
-   *
-   * @param source the compilation unit for which an AST structure should be returned
-   * @return the AST structure representing the content of the source
-   * @throws AnalysisException if the analysis could not be performed
    */
   CompilationUnit computeResolvableCompilationUnit(Source source);
 
   /**
    * Return all the resolved [CompilationUnit]s for the given [source] if not
    * flushed, otherwise return `null` and ensures that the [CompilationUnit]s
    * will be eventually returned to the client from [performAnalysisTask].
    */
   List<CompilationUnit> ensureResolvedDartUnits(Source source);
 
   /**
-   * Return context that owns the given source.
-   *
-   * @param source the source whose context is to be returned
-   * @return the context that owns the partition that contains the source
+   * Return context that owns the given [source].
    */
   InternalAnalysisContext getContextFor(Source source);
 
   /**
-   * Return a namespace containing mappings for all of the public names defined by the given
-   * library.
-   *
-   * @param library the library whose public namespace is to be returned
-   * @return the public namespace of the given library
+   * Return a namespace containing mappings for all of the public names defined
+   * by the given [library].
    */
   Namespace getPublicNamespace(LibraryElement library);
 
   /**
    * Respond to a change which has been made to the given [source] file.
    * [originalContents] is the former contents of the file, and [newContents]
    * is the updated contents.  If [notify] is true, a source changed event is
    * triggered.
    *
    * Normally it should not be necessary for clients to call this function,
    * since it will be automatically invoked in response to a call to
    * [applyChanges] or [setContents].  However, if this analysis context is
    * sharing its content cache with other contexts, then the client must
    * manually update the content cache and call this function for each context.
    *
    * Return `true` if the change was significant to this context (i.e. [source]
    * is either implicitly or explicitly analyzed by this context, and a change
    * actually occurred).
    */
   bool handleContentsChanged(
       Source source, String originalContents, String newContents, bool notify);
 
   /**
-   * Given a table mapping the source for the libraries represented by the corresponding elements to
-   * the elements representing the libraries, record those mappings.
-   *
-   * @param elementMap a table mapping the source for the libraries represented by the elements to
-   *          the elements representing the libraries
+   * Given an [elementMap] mapping the source for the libraries represented by
+   * the corresponding elements to the elements representing the libraries,
+   * record those mappings.
    */
   void recordLibraryElements(Map<Source, LibraryElement> elementMap);
 
   /**
    * Call the given callback function for eache cache item in the context.
    */
   void visitCacheItems(void callback(Source source, SourceEntry dartEntry,
       DataDescriptor rowDesc, CacheState state));
 }
 
 /**
- * A `Logger` is an object that can be used to receive information about errors
- * within the analysis engine. Implementations usually write this information to
- * a file, but can also record the information for later use (such as during
- * testing) or even ignore the information.
+ * An object that can be used to receive information about errors within the
+ * analysis engine. Implementations usually write this information to a file,
+ * but can also record the information for later use (such as during testing) or
+ * even ignore the information.
  */
 abstract class Logger {
   /**
    * A logger that ignores all logging.
    */
   static final Logger NULL = new NullLogger();
 
   /**
    * Log the given message as an error. The [message] is expected to be an
    * explanation of why the error occurred or what it means. The [exception] is
    * expected to be the reason for the error. At least one argument must be
    * provided.
    */
   void logError(String message, [CaughtException exception]);
 
   /**
-   * Log the given exception as one representing an error.
-   *
-   * @param message an explanation of why the error occurred or what it means
-   * @param exception the exception being logged
+   * Log the given [exception] as one representing an error. The [message] is an
+   * explanation of why the error occurred or what it means.
    */
   @deprecated
   void logError2(String message, Object exception);
 
   /**
    * Log the given informational message. The [message] is expected to be an
    * explanation of why the error occurred or what it means. The [exception] is
    * expected to be the reason for the error.
    */
   void logInformation(String message, [CaughtException exception]);
 
   /**
-   * Log the given exception as one representing an informational message.
-   *
-   * @param message an explanation of why the error occurred or what it means
-   * @param exception the exception being logged
+   * Log the given [exception] as one representing an informational message. The
+   * [message] is an explanation of why the error occurred or what it means.
    */
   @deprecated
   void logInformation2(String message, Object exception);
 }
 
 /**
  * An implementation of [Logger] that does nothing.
  */
 class NullLogger implements Logger {
   @override
   void logError(String message, [CaughtException exception]) {}
 
   @override
   void logError2(String message, Object exception) {}
 
   @override
   void logInformation(String message, [CaughtException exception]) {}
 
   @override
   void logInformation2(String message, Object exception) {}
 }
 
 /**
- * Instances of the class `ObsoleteSourceAnalysisException` represent an analysis attempt that
- * failed because a source was deleted between the time the analysis started and the time the
- * results of the analysis were ready to be recorded.
+ * An exception created when an analysis attempt fails because a source was
+ * deleted between the time the analysis started and the time the results of the
+ * analysis were ready to be recorded.
  */
 class ObsoleteSourceAnalysisException extends AnalysisException {
   /**
    * The source that was removed while it was being analyzed.
    */
   Source _source;
 
   /**
-   * Initialize a newly created exception to represent the removal of the given source.
-   *
-   * @param source the source that was removed while it was being analyzed
+   * Initialize a newly created exception to represent the removal of the given
+   * [source].
    */
   ObsoleteSourceAnalysisException(Source source) : super(
           "The source '${source.fullName}' was removed while it was being analyzed") {
     this._source = source;
   }
 
   /**
    * Return the source that was removed while it was being analyzed.
-   *
-   * @return the source that was removed
    */
   Source get source => _source;
 }
 
 /**
  * Instances of the class `ParseDartTask` parse a specific source as a Dart file.
  */
 class ParseDartTask extends AnalysisTask {
   /**
    * The source to be parsed.
@@ skipping 59 matching lines @@
 
   /**
    * Return the compilation unit that was produced by parsing the source, or `null` if the
    * task has not yet been performed or if an exception occurred.
    *
    * @return the compilation unit that was produced by parsing the source
    */
   CompilationUnit get compilationUnit => _unit;
 
   /**
-   * Return the errors that were produced by scanning and parsing the source, or an empty array if
+   * Return the errors that were produced by scanning and parsing the source, or an empty list if
    * the task has not yet been performed or if an exception occurred.
    *
    * @return the errors that were produced by scanning and parsing the source
    */
   List<AnalysisError> get errors => _errors;
 
   /**
-   * Return an array containing the sources referenced by 'export' directives, or an empty array if
+   * Return a list containing the sources referenced by 'export' directives, or an empty list if
    * the task has not yet been performed or if an exception occurred.
    *
-   * @return an array containing the sources referenced by 'export' directives
+   * @return an list containing the sources referenced by 'export' directives
    */
   List<Source> get exportedSources => _toArray(_exportedSources);
 
   /**
    * Return `true` if the source contains any directive other than a 'part of' directive, or
    * `false` if the task has not yet been performed or if an exception occurred.
    *
    * @return `true` if the source contains any directive other than a 'part of' directive
    */
   bool get hasNonPartOfDirective => _containsNonPartOfDirective;
 
   /**
    * Return `true` if the source contains a 'part of' directive, or `false` if the task
    * has not yet been performed or if an exception occurred.
    *
    * @return `true` if the source contains a 'part of' directive
    */
   bool get hasPartOfDirective => _containsPartOfDirective;
 
   /**
-   * Return an array containing the sources referenced by 'import' directives, or an empty array if
+   * Return a list containing the sources referenced by 'import' directives, or an empty list if
    * the task has not yet been performed or if an exception occurred.
    *
-   * @return an array containing the sources referenced by 'import' directives
+   * @return a list containing the sources referenced by 'import' directives
    */
   List<Source> get importedSources => _toArray(_importedSources);
 
   /**
-   * Return an array containing the sources referenced by 'part' directives, or an empty array if
+   * Return a list containing the sources referenced by 'part' directives, or an empty list if
    * the task has not yet been performed or if an exception occurred.
    *
-   * @return an array containing the sources referenced by 'part' directives
+   * @return a list containing the sources referenced by 'part' directives
    */
   List<Source> get includedSources => _toArray(_includedSources);
 
   @override
   String get taskDescription {
     if (source == null) {
       return "parse as dart null source";
     }
     return "parse as dart ${source.fullName}";
   }
@@ skipping 38 matching lines @@
               }
             }
           }
         }
       }
       _errors = errorListener.getErrorsForSource(source);
     });
   }
 
   /**
-   * Efficiently convert the given set of sources to an array.
-   *
-   * @param sources the set to be converted
-   * @return an array containing all of the sources in the given set
+   * Efficiently convert the given set of [sources] to a list.
    */
   List<Source> _toArray(HashSet<Source> sources) {
     int size = sources.length;
     if (size == 0) {
       return Source.EMPTY_ARRAY;
     }
     return new List.from(sources);
   }
 
   /**
@@ skipping 75 matching lines @@
    * The HTML unit that was produced by parsing the source.
    */
   ht.HtmlUnit _unit;
 
   /**
    * The errors that were produced by scanning and parsing the source.
    */
   List<AnalysisError> _errors = AnalysisError.NO_ERRORS;
 
   /**
-   * An array containing the sources of the libraries that are referenced within the HTML.
+   * A list containing the sources of the libraries that are referenced within the HTML.
    */
   List<Source> _referencedLibraries = Source.EMPTY_ARRAY;
 
   /**
    * Initialize a newly created task to perform analysis within the given context.
    *
    * @param context the context in which the task is to be performed
    * @param source the source to be parsed
    * @param content the contents of the source
    */
@@ skipping 31 matching lines @@
 
   /**
    * Return the line information that was produced, or `null` if the task has not yet been
    * performed or if an exception occurred.
    *
    * @return the line information that was produced
    */
   LineInfo get lineInfo => _lineInfo;
 
   /**
-   * Return an array containing the sources of the libraries that are referenced within the HTML.
+   * Return a list containing the sources of the libraries that are referenced within the HTML.
    *
    * @return the sources of the libraries that are referenced within the HTML
    */
   List<Source> get referencedLibraries => _referencedLibraries;
 
   @override
   String get taskDescription {
     if (source == null) {
       return "parse as html null source";
     }
@@ skipping 67 matching lines @@
         }
       } on FormatException {
         // ignored - invalid URI reported during resolution phase
       }
     }
     return super.visitHtmlScriptTagNode(node);
   }
 }
 
 /**
- * Instances of the class `PartitionManager` manage the partitions that can be shared between
- * analysis contexts.
+ * An object that manages the partitions that can be shared between analysis
+ * contexts.
  */
 class PartitionManager {
   /**
    * The default cache size for a Dart SDK partition.
    */
   static int _DEFAULT_SDK_CACHE_SIZE = 256;
 
   /**
    * A table mapping SDK's to the partitions used for those SDK's.
    */
   HashMap<DartSdk, SdkCachePartition> _sdkPartitions =
       new HashMap<DartSdk, SdkCachePartition>();
 
   /**
    * Clear any cached data being maintained by this manager.
    */
   void clearCache() {
     _sdkPartitions.clear();
   }
 
   /**
-   * Return the partition being used for the given SDK, creating the partition
+   * Return the partition being used for the given [sdk], creating the partition
    * if necessary.
-   *
-   * [sdk] - the SDK for which a partition is being requested.
    */
   SdkCachePartition forSdk(DartSdk sdk) {
     // Call sdk.context now, because when it creates a new
     // InternalAnalysisContext instance, it calls forSdk() again, so creates an
     // SdkCachePartition instance.
     // So, if we initialize context after "partition == null", we end up
     // with two SdkCachePartition instances.
     InternalAnalysisContext sdkContext = sdk.context;
     // Check cache for an existing partition.
     SdkCachePartition partition = _sdkPartitions[sdk];
@@ skipping 150 matching lines @@
 
   /**
    * The [PerformanceTag] for time spent during otherwise not accounted parts
    * incremental of analysis.
    */
   static PerformanceTag incrementalAnalysis =
       new PerformanceTag('incrementalAnalysis');
 }
 
 /**
- * Instances of the class `RecordingErrorListener` implement an error listener that will
- * record the errors that are reported to it in a way that is appropriate for caching those errors
- * within an analysis context.
+ * An error listener that will record the errors that are reported to it in a
+ * way that is appropriate for caching those errors within an analysis context.
  */
 class RecordingErrorListener implements AnalysisErrorListener {
   /**
-   * A HashMap of lists containing the errors that were collected, keyed by each [Source].
+   * A map of sets containing the errors that were collected, keyed by each
+   * source.
    */
   Map<Source, HashSet<AnalysisError>> _errors =
       new HashMap<Source, HashSet<AnalysisError>>();
 
   /**
-   * Answer the errors collected by the listener.
-   *
-   * @return an array of errors (not `null`, contains no `null`s)
+   * Return the errors collected by the listener.
    */
   List<AnalysisError> get errors {
     int numEntries = _errors.length;
     if (numEntries == 0) {
       return AnalysisError.NO_ERRORS;
     }
     List<AnalysisError> resultList = new List<AnalysisError>();
     for (HashSet<AnalysisError> errors in _errors.values) {
       resultList.addAll(errors);
     }
     return resultList;
   }
 
   /**
-   * Add all of the errors recorded by the given listener to this listener.
-   *
-   * @param listener the listener that has recorded the errors to be added
+   * Add all of the errors recorded by the given [listener] to this listener.
    */
   void addAll(RecordingErrorListener listener) {
     for (AnalysisError error in listener.errors) {
       onError(error);
     }
   }
 
   /**
-   * Answer the errors collected by the listener for some passed [Source].
-   *
-   * @param source some [Source] for which the caller wants the set of [AnalysisError]s
-   *          collected by this listener
-   * @return the errors collected by the listener for the passed [Source]
+   * Return the errors collected by the listener for the given [source].
    */
   List<AnalysisError> getErrorsForSource(Source source) {
     HashSet<AnalysisError> errorsForSource = _errors[source];
     if (errorsForSource == null) {
       return AnalysisError.NO_ERRORS;
     } else {
       return new List.from(errorsForSource);
     }
   }
 
@@ skipping 41 matching lines @@
     CompilationUnit script = node.script;
     if (script != null) {
       GenerateDartErrorsTask.validateDirectives(ResolveHtmlTask_this.context,
           ResolveHtmlTask_this.source, script, errorListener);
     }
     return null;
   }
 }
 
 /**
- * A `ResolutionEraser` removes any resolution information from an AST
- * structure when used to visit that structure.
+ * An visitor that removes any resolution information from an AST structure when
+ * used to visit that structure.
  */
 class ResolutionEraser extends GeneralizingAstVisitor<Object> {
   @override
   Object visitAssignmentExpression(AssignmentExpression node) {
     node.staticElement = null;
     node.propagatedElement = null;
     return super.visitAssignmentExpression(node);
   }
 
   @override
@@ skipping 108 matching lines @@
 
   /**
    * Remove any resolution information from the given AST structure.
    */
   static void erase(AstNode node) {
     node.accept(new ResolutionEraser());
   }
 }
 
 /**
- * A `ResolutionState` maintains the information produced by resolving a
- * compilation unit as part of a specific library.
+ * The information produced by resolving a compilation unit as part of a
+ * specific library.
  */
 class ResolutionState {
   /**
    * The next resolution state or `null` if none.
    */
   ResolutionState _nextState;
 
   /**
-   * The source for the defining compilation unit of the library that contains this unit. If this
-   * unit is the defining compilation unit for it's library, then this will be the source for this
-   * unit.
+   * The source for the defining compilation unit of the library that contains
+   * this unit. If this unit is the defining compilation unit for it's library,
+   * then this will be the source for this unit.
    */
   Source _librarySource;
 
   /**
    * A table mapping descriptors to the cached results for those descriptors.
    * If there is no entry for a given descriptor then the state is implicitly
    * [CacheState.INVALID] and the value is implicitly the default value.
    */
   Map<DataDescriptor, CachedResult> resultMap =
       new HashMap<DataDescriptor, CachedResult>();
@@ skipping 160 matching lines @@
    */
   void _flush(DataDescriptor descriptor) {
     CachedResult result = resultMap[descriptor];
     if (result != null && result.state == CacheState.VALID) {
       result.state = CacheState.FLUSHED;
       result.value = descriptor.defaultValue;
     }
   }
 
   /**
-   * Write a textual representation of the difference between the old entry and this entry to the
-   * given string builder.
-   *
-   * @param builder the string builder to which the difference is to be written
-   * @param oldEntry the entry that was replaced by this entry
-   * @return `true` if some difference was written
+   * Write a textual representation of the difference between the old entry and
+   * this entry to the given string [buffer]. A separator will be written before
+   * the first difference if [needsSeparator] is `true`. The [oldEntry] is the
+   * entry that was replaced by this entry. Return `true` is a separator is
+   * needed before writing any subsequent differences.
    */
   bool _writeDiffOn(
       StringBuffer buffer, bool needsSeparator, DartEntry oldEntry) {
     needsSeparator = _writeStateDiffOn(buffer, needsSeparator, "resolvedUnit",
         DartEntry.RESOLVED_UNIT, oldEntry);
     needsSeparator = _writeStateDiffOn(buffer, needsSeparator,
         "resolutionErrors", DartEntry.RESOLUTION_ERRORS, oldEntry);
     needsSeparator = _writeStateDiffOn(buffer, needsSeparator,
         "verificationErrors", DartEntry.VERIFICATION_ERRORS, oldEntry);
     needsSeparator = _writeStateDiffOn(
         buffer, needsSeparator, "hints", DartEntry.HINTS, oldEntry);
     needsSeparator = _writeStateDiffOn(
         buffer, needsSeparator, "lints", DartEntry.LINTS, oldEntry);
     return needsSeparator;
   }
 
   /**
-   * Write a textual representation of this state to the given builder. The result will only be
-   * used for debugging purposes.
-   *
-   * @param builder the builder to which the text should be written
+   * Write a textual representation of this state to the given [buffer]. The
+   * result will only be used for debugging purposes.
    */
   void _writeOn(StringBuffer buffer) {
     if (_librarySource != null) {
       _writeStateOn(buffer, "builtElement", DartEntry.BUILT_ELEMENT);
       _writeStateOn(buffer, "builtUnit", DartEntry.BUILT_UNIT);
       _writeStateOn(buffer, "resolvedUnit", DartEntry.RESOLVED_UNIT);
       _writeStateOn(buffer, "resolutionErrors", DartEntry.RESOLUTION_ERRORS);
       _writeStateOn(
           buffer, "verificationErrors", DartEntry.VERIFICATION_ERRORS);
       _writeStateOn(buffer, "hints", DartEntry.HINTS);
@@ skipping 36 matching lines @@
       StringBuffer buffer, String label, DataDescriptor descriptor) {
     CachedResult result = resultMap[descriptor];
     buffer.write("; ");
     buffer.write(label);
     buffer.write(" = ");
     buffer.write(result == null ? CacheState.INVALID : result.state);
   }
 }
 
 /**
- * A `ResolvableCompilationUnit` is a compilation unit that is not referenced by
- * any other objects. It is used by the [LibraryResolver] to resolve a library.
+ * A compilation unit that is not referenced by any other objects. It is used by
+ * the [LibraryResolver] to resolve a library.
  */
 class ResolvableCompilationUnit {
   /**
    * The source of the compilation unit.
    */
   final Source source;
 
   /**
    * The compilation unit.
    */
   final CompilationUnit compilationUnit;
 
   /**
-   * Initialize a newly created holder to hold the given values.
-   *
-   * @param source the source of the compilation unit
-   * @param unit the AST that was created from the source
+   * Initialize a newly created holder to hold the given [source] and
+   * [compilationUnit].
    */
   ResolvableCompilationUnit(this.source, this.compilationUnit);
 }
 
 /**
  * Instances of the class `ResolveDartLibraryTask` resolve a specific Dart library.
  */
 class ResolveDartLibraryCycleTask extends AnalysisTask {
   /**
    * The source representing the file whose compilation unit is to be returned. TODO(brianwilkerson)
@@ skipping 326 matching lines @@
     //
     _resolutionErrors = errorListener.getErrorsForSource(source);
     //
     // Remember the resolved unit.
     //
     _resolvedUnit = _unit;
   }
 }
 
 /**
- * The enumerated type `RetentionPriority` represents the priority of data in the cache in
- * terms of the desirability of retaining some specified data about a specified source.
+ * The priority of data in the cache in terms of the desirability of retaining
+ * some specified data about a specified source.
  */
 class RetentionPriority extends Enum<RetentionPriority> {
   /**
-   * A priority indicating that a given piece of data can be removed from the cache without
-   * reservation.
+   * A priority indicating that a given piece of data can be removed from the
+   * cache without reservation.
    */
   static const RetentionPriority LOW = const RetentionPriority('LOW', 0);
 
   /**
-   * A priority indicating that a given piece of data should not be removed from the cache unless
-   * there are no sources for which the corresponding data has a lower priority. Currently used for
-   * data that is needed in order to finish some outstanding analysis task.
+   * A priority indicating that a given piece of data should not be removed from
+   * the cache unless there are no sources for which the corresponding data has
+   * a lower priority. Currently used for data that is needed in order to finish
+   * some outstanding analysis task.
    */
   static const RetentionPriority MEDIUM = const RetentionPriority('MEDIUM', 1);
 
   /**
-   * A priority indicating that a given piece of data should not be removed from the cache.
-   * Currently used for data related to a priority source.
+   * A priority indicating that a given piece of data should not be removed from
+   * the cache. Currently used for data related to a priority source.
    */
   static const RetentionPriority HIGH = const RetentionPriority('HIGH', 2);
 
   static const List<RetentionPriority> values = const [LOW, MEDIUM, HIGH];
 
   const RetentionPriority(String name, int ordinal) : super(name, ordinal);
 }
 
 /**
  * Instances of the class `ScanDartTask` scan a specific source as a Dart file.
@@ skipping 82 matching lines @@
         _errors = errorListener.getErrorsForSource(source);
       } catch (exception, stackTrace) {
         throw new AnalysisException(
             "Exception", new CaughtException(exception, stackTrace));
       }
     });
   }
 }
 
 /**
- * Instances of the class `SdkAnalysisContext` implement an [AnalysisContext] that only
- * contains sources for a Dart SDK.
+ * An [AnalysisContext] that only contains sources for a Dart SDK.
  */
 class SdkAnalysisContext extends AnalysisContextImpl {
   @override
   AnalysisCache createCacheFromSourceFactory(SourceFactory factory) {
     if (factory == null) {
       return super.createCacheFromSourceFactory(factory);
     }
     DartSdk sdk = factory.dartSdk;
     if (sdk == null) {
       throw new IllegalArgumentException(
           "The source factory for an SDK analysis context must have a DartUriResolver");
     }
     return new AnalysisCache(
         <CachePartition>[AnalysisEngine.instance.partitionManager.forSdk(sdk)]);
   }
 }
 
 /**
- * Instances of the class `SdkCachePartition` implement a cache partition that contains all of
- * the sources in the SDK.
+ * A cache partition that contains all of the sources in the SDK.
  */
 class SdkCachePartition extends CachePartition {
   /**
-   * Initialize a newly created partition.
-   *
-   * @param context the context that owns this partition
-   * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
-   *          the cache
+   * Initialize a newly created partition. The [context] is the context that
+   * owns this partition. The [maxCacheSize] is the maximum number of sources
+   * for which AST structures should be kept in the cache.
    */
   SdkCachePartition(InternalAnalysisContext context, int maxCacheSize)
       : super(context, maxCacheSize, DefaultRetentionPolicy.POLICY);
 
   @override
   bool contains(Source source) => source.isInSystemLibrary;
 }
 
 /**
- * A `SourceEntry` maintains the information cached by an analysis context about
- * an individual source, no matter what kind of source it is.
+ * The information cached by an analysis context about an individual source, no
+ * matter what kind of source it is.
  */
 abstract class SourceEntry {
   /**
    * The data descriptor representing the contents of the source.
    */
   static final DataDescriptor<String> CONTENT =
       new DataDescriptor<String>("SourceEntry.CONTENT");
 
   /**
    * The data descriptor representing the errors resulting from reading the
@@ skipping 380 matching lines @@
    */
   static void countTransition(DataDescriptor descriptor, CachedResult result) {
     Map<CacheState, int> countMap = transitionMap.putIfAbsent(
         descriptor, () => new HashMap<CacheState, int>());
     int count = countMap[result.state];
     countMap[result.state] = count == null ? 1 : count + 1;
   }
 }
 
 /**
- * The enumerated type `Priority` defines the priority levels used to return sources in an
- * optimal order. A smaller ordinal value equates to a higher priority.
+ * The priority levels used to return sources in an optimal order. A smaller
+ * ordinal value equates to a higher priority.
  */
 class SourcePriority extends Enum<SourcePriority> {
   /**
-   * Used for a Dart source that is known to be a part contained in a library that was recently
-   * resolved. These parts are given a higher priority because there is a high probability that
-   * their AST structure is still in the cache and therefore would not need to be re-created.
+   * Used for a Dart source that is known to be a part contained in a library
+   * that was recently resolved. These parts are given a higher priority because
+   * there is a high probability that their AST structure is still in the cache
+   * and therefore would not need to be re-created.
    */
   static const SourcePriority PRIORITY_PART =
       const SourcePriority('PRIORITY_PART', 0);
 
   /**
    * Used for a Dart source that is known to be a library.
    */
   static const SourcePriority LIBRARY = const SourcePriority('LIBRARY', 1);
 
   /**
    * Used for a Dart source whose kind is unknown.
    */
   static const SourcePriority UNKNOWN = const SourcePriority('UNKNOWN', 2);
 
   /**
-   * Used for a Dart source that is known to be a part but whose library has not yet been resolved.
+   * Used for a Dart source that is known to be a part but whose library has not
+   * yet been resolved.
    */
   static const SourcePriority NORMAL_PART =
       const SourcePriority('NORMAL_PART', 3);
 
   /**
    * Used for an HTML source.
    */
   static const SourcePriority HTML = const SourcePriority('HTML', 4);
 
   static const List<SourcePriority> values = const [
     PRIORITY_PART,
     LIBRARY,
     UNKNOWN,
     NORMAL_PART,
     HTML
   ];
 
   const SourcePriority(String name, int ordinal) : super(name, ordinal);
 }
 
 /**
  * [SourcesChangedEvent] indicates which sources have been added, removed,
  * or whose contents have changed.
  */
 class SourcesChangedEvent {
-
   /**
-   * The internal representation of what has changed.
-   * Clients should not access this field directly.
+   * The internal representation of what has changed. Clients should not access
+   * this field directly.
    */
   final ChangeSet _changeSet;
 
   /**
    * Construct an instance representing the given changes.
    */
   SourcesChangedEvent(ChangeSet changeSet) : _changeSet = changeSet;
 
   /**
    * Construct an instance representing a source content change.
@@ skipping 32 matching lines @@
   /**
    * Return `true` if any sources were removed or deleted.
    */
   bool get wereSourcesRemovedOrDeleted =>
       _changeSet.removedSources.length > 0 ||
           _changeSet.removedContainers.length > 0 ||
           _changeSet.deletedSources.length > 0;
 }
 
 /**
- * Instances of the class `TimestampedData` represent analysis data for which we have a
- * modification time.
+ * Analysis data for which we have a modification time.
  */
 class TimestampedData<E> {
   /**
    * The modification time of the source from which the data was created.
    */
   final int modificationTime;
 
   /**
    * The data that was created from the source.
    */
   final E data;
 
   /**
-   * Initialize a newly created holder to hold the given values.
-   *
-   * @param modificationTime the modification time of the source from which the data was created
-   * @param unit the data that was created from the source
+   * Initialize a newly created holder to associate the given [data] with the
+   * given [modificationTime].
    */
   TimestampedData(this.modificationTime, this.data);
 }
 
 /**
- * Instances of the class `UniversalCachePartition` implement a cache partition that contains
- * all sources not contained in other partitions.
+ * A cache partition that contains all sources not contained in other
+ * partitions.
  */
 class UniversalCachePartition extends CachePartition {
   /**
-   * Initialize a newly created partition.
-   *
-   * @param context the context that owns this partition
-   * @param maxCacheSize the maximum number of sources for which AST structures should be kept in
-   *          the cache
-   * @param retentionPolicy the policy used to determine which pieces of data to remove from the
-   *          cache
+   * Initialize a newly created partition. The [context] is the context that
+   * owns this partition. The [maxCacheSize] is the maximum number of sources
+   * for which AST structures should be kept in the cache. The [retentionPolicy]
+   * is the policy used to determine which pieces of data to remove from the
+   * cache.
    */
   UniversalCachePartition(InternalAnalysisContext context, int maxCacheSize,
       CacheRetentionPolicy retentionPolicy)
       : super(context, maxCacheSize, retentionPolicy);
 
   @override
   bool contains(Source source) => true;
 }
 
 /**
@@ skipping 25 matching lines @@
   @override
   accept(AnalysisTaskVisitor visitor) => null;
 
   @override
   void internalPerform() {
     // There is no work to be done.
   }
 }
 
 /**
- * Instances of the class `WorkManager` manage a list of sources that need to have analysis
- * work performed on them.
+ * An object that manages a list of sources that need to have analysis work
+ * performed on them.
  */
 class WorkManager {
   /**
-   * An array containing the various queues is priority order.
+   * A list containing the various queues is priority order.
    */
   List<List<Source>> _workQueues;
 
   /**
    * Initialize a newly created manager to have no work queued up.
    */
   WorkManager() {
     int queueCount = SourcePriority.values.length;
     _workQueues = new List<List>(queueCount);
     for (int i = 0; i < queueCount; i++) {
       _workQueues[i] = new List<Source>();
     }
   }
 
   /**
-   * Record that the given source needs to be analyzed. The priority level is used to control when
-   * the source will be analyzed with respect to other sources. If the source was previously added
-   * then it's priority is updated. If it was previously added with the same priority then it's
-   * position in the queue is unchanged.
-   *
-   * @param source the source that needs to be analyzed
-   * @param priority the priority level of the source
+   * Record that the given [source] needs to be analyzed. The [priority] level
+   * is used to control when the source will be analyzed with respect to other
+   * sources. If the source was previously added then it's priority is updated.
+   * If it was previously added with the same priority then it's position in the
+   * queue is unchanged.
    */
   void add(Source source, SourcePriority priority) {
     int queueCount = _workQueues.length;
     int ordinal = priority.ordinal;
     for (int i = 0; i < queueCount; i++) {
       List<Source> queue = _workQueues[i];
       if (i == ordinal) {
         if (!queue.contains(source)) {
           queue.add(source);
         }
       } else {
         queue.remove(source);
       }
     }
   }
 
   /**
-   * Record that the given source needs to be analyzed. The priority level is used to control when
-   * the source will be analyzed with respect to other sources. If the source was previously added
-   * then it's priority is updated. In either case, it will be analyzed before other sources of the
-   * same priority.
-   *
-   * @param source the source that needs to be analyzed
-   * @param priority the priority level of the source
+   * Record that the given [source] needs to be analyzed. The [priority] level
+   * is used to control when the source will be analyzed with respect to other
+   * sources. If the source was previously added then it's priority is updated.
+   * In either case, it will be analyzed before other sources of the same
+   * priority.
    */
   void addFirst(Source source, SourcePriority priority) {
     int queueCount = _workQueues.length;
     int ordinal = priority.ordinal;
     for (int i = 0; i < queueCount; i++) {
       List<Source> queue = _workQueues[i];
       if (i == ordinal) {
         queue.remove(source);
         queue.insert(0, source);
       } else {
         queue.remove(source);
       }
     }
   }
 
   /**
-   * Return an iterator that can be used to access the sources to be analyzed in the order in which
-   * they should be analyzed.
+   * Return an iterator that can be used to access the sources to be analyzed in
+   * the order in which they should be analyzed.
    *
-   * <b>Note:</b> As with other iterators, no sources can be added or removed from this work manager
-   * while the iterator is being used. Unlike some implementations, however, the iterator will not
-   * detect when this requirement has been violated; it might work correctly, it might return the
+   * <b>Note:</b> As with other iterators, no sources can be added or removed
+   * from this work manager while the iterator is being used. Unlike some
+   * implementations, however, the iterator will not detect when this
+   * requirement has been violated; it might work correctly, it might return the
    * wrong source, or it might throw an exception.
-   *
-   * @return an iterator that can be used to access the next source to be analyzed
    */
   WorkManager_WorkIterator iterator() => new WorkManager_WorkIterator(this);
 
   /**
    * Record that the given source is fully analyzed.
-   *
-   * @param source the source that is fully analyzed
    */
   void remove(Source source) {
     int queueCount = _workQueues.length;
     for (int i = 0; i < queueCount; i++) {
       _workQueues[i].remove(source);
     }
   }
 
   @override
   String toString() {
@@ skipping 17 matching lines @@
           buffer.write(queue[j].fullName);
         }
         needsSeparator = true;
       }
     }
     return buffer.toString();
   }
 }
 
 /**
- * Instances of the class `WorkIterator` implement an iterator that returns the sources in a
- * work manager in the order in which they are to be analyzed.
+ * An iterator that returns the sources in a work manager in the order in which
+ * they are to be analyzed.
  */
 class WorkManager_WorkIterator {
   final WorkManager _manager;
 
   /**
    * The index of the work queue through which we are currently iterating.
    */
   int _queueIndex = 0;
 
   /**
    * The index of the next element of the work queue to be returned.
    */
   int _index = -1;
 
   /**
-   * Initialize a newly created iterator to be ready to return the first element in the iteration.
+   * Initialize a newly created iterator to be ready to return the first element
+   * in the iteration.
    */
   WorkManager_WorkIterator(this._manager) {
     _advance();
   }
 
   /**
    * Return `true` if there is another [Source] available for processing.
-   *
-   * @return `true` if there is another [Source] available for processing
    */
   bool get hasNext => _queueIndex < _manager._workQueues.length;
 
   /**
-   * Return the next [Source] available for processing and advance so that the returned
-   * source will not be returned again.
-   *
-   * @return the next [Source] available for processing
+   * Return the next [Source] available for processing and advance so that the
+   * returned source will not be returned again.
    */
   Source next() {
     if (!hasNext) {
       throw new NoSuchElementException();
     }
     Source source = _manager._workQueues[_queueIndex][_index];
     _advance();
     return source;
   }
 
   /**
-   * Increment the [index] and [queueIndex] so that they are either indicating the
-   * next source to be returned or are indicating that there are no more sources to be returned.
+   * Increment the [index] and [queueIndex] so that they are either indicating
+   * the next source to be returned or are indicating that there are no more
+   * sources to be returned.
    */
   void _advance() {
     _index++;
     if (_index >= _manager._workQueues[_queueIndex].length) {
       _index = 0;
       _queueIndex++;
       while (_queueIndex < _manager._workQueues.length &&
           _manager._workQueues[_queueIndex].isEmpty) {
         _queueIndex++;
       }
     }
   }
 }
 
 /**
- * Helper class used to create futures for AnalysisContextImpl.  Using a helper
+ * A helper class used to create futures for AnalysisContextImpl. Using a helper
  * class allows us to preserve the generic parameter T.
  */
 class _AnalysisFutureHelper<T> {
   final AnalysisContextImpl _context;
 
   _AnalysisFutureHelper(this._context);
 
   /**
    * Return a future that will be completed with the result of calling
    * [computeValue].  If [computeValue] returns non-null, the future will be
@@ skipping 42 matching lines @@
   visitElement(Element element) {
     if (element.id == _id) {
       result = element;
       throw new _ElementByIdFinderException();
     }
     super.visitElement(element);
   }
 }
 
 class _ElementByIdFinderException {}