Update the API documentations with Paul review comments.

pkg/analyzer/lib/src/dart/analysis/driver.dart

 // Copyright (c) 2016, 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.
 
 import 'dart:async';
 
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/error/error.dart';
-import 'package:analyzer/file_system/file_system.dart';
 import 'package:analyzer/src/dart/analysis/byte_store.dart';
 import 'package:analyzer/src/generated/source.dart';
 
 /**
  * This class computes [AnalysisResult]s for Dart files.
+ *
+ * Let the set of "explicitly analyzed files" denote the set of paths that have
+ * been passed to [addFile] but not subsequently passed to [removeFile]. Let
+ * the "current analysis results" denote the map from the set of explicitly
+ * analyzed files to the most recent [AnalysisResult] delivered to [results]
+ * for each file. Let the "current file state" represent a map from file path
+ * to the file contents most recently read from that file, or fetched from the
+ * content cache (considering all possible possible file paths, regardless of
+ * whether they're in the set of explicitly analyzed files). Let the
+ * "analysis state" be either "analyzing" or "idle".
+ *
+ * (These are theoretical constructs; they may not necessarily reflect data
+ * structures maintained explicitly by the driver).
+ *
+ * Then we make the following guarantees:
+ *
+ *    - Whenever the analysis state is idle, the current analysis results are
+ *      consistent with the current file state.
+ *
+ *    - A call to [addFile] or [changeFile] causes the analysis state to
+ *      transition to "analyzing", and schedules the contents of the given
+ *      files to be read into the current file state prior to the next time
+ *      the analysis state transitions back to "idle".
+ *
+ *    - If at any time the client stops making calls to [addFile], [changeFile],
+ *      and [removeFile], the analysis state will eventually transition back to
+ *      "idle" after a finite amount of processing.
+ *
+ * As a result of these guarantees, a client may ensure that the analysis
+ * results are "eventually consistent" with the file system by simply calling
+ * [changeFile] any time the contents of a file on the file system have changed.

[Brian Wilkerson, 2016/10/25 17:34:16]

I assume a call to removeFile could transition the driver from analyzing to
idle. Do we need to mention that?

[scheglov, 2016/10/25 18:53:31]

I'd like to have the only place where we switch from "analyzing" to "idle" - in
the "result" stream cycle.

[Brian Wilkerson, 2016/10/26 06:49:14]

That would be nice, but if we add a file, schedule it for analysis, then remove
it before analysis completes, wouldn't that transition the driver to idle?

[scheglov, 2016/10/26 16:39:59]

The driver will transition to idle when there is nothing to do.

Yes, if [removeFile] is called, we might not produce the result for the removed
file.
I will update the [results] documentation.

+ *
+ *
+ * TODO(scheglov) Clean up the list of implicitly analyzed files.
  */
 class AnalysisDriver {
   /**
    * The byte storage to get and put serialized data.
    *
-   * It can be shared between other [AnalysisDriver]s.
+   * It can be shared with other [AnalysisDriver]s.
    */
   final ByteStore _byteStore;
 
   /**
    * The [SourceFactory] is used to resolve URIs to paths and restore URIs
    * from file paths.
    */
   final SourceFactory _sourceFactory;
 
   /**
    * This [ContentCache] is consulted for a file content before reading
    * the content from the file.
    */
   final ContentCache _contentCache;
 
   AnalysisDriver(this._byteStore, this._sourceFactory, this._contentCache);
 
   /**
    * Set the list of files that the driver should try to analyze sooner.
    *
    * Every path in the list must be absolute and normalized.
    *
    * The driver will produce the results through the [results] stream. The
    * exact order in which results are produced is not defined, neither
-   * between priority files, not between them and not priority files.
+   * between priority files, nor between priority and non-priority files.
    */
   void set priorityFiles(List<String> priorityPaths) {
     // TODO(scheglov) implement
   }
 
   /**
    * Return the [Stream] that produces [AnalysisResult]s for added files.
    *
    * Analysis starts when the client starts listening to the stream, and stops
    * when the client cancels the subscription.
    *
-   * Analysis is eventual, the driver will try to produce results that are at
-   * some point more consistent with the state of the files, but does not
-   * guarantee that this will ever happen.
+   * When the client starts listening, the analysis state transitions to
+   * "analyzing" and an analysis result is produced for every added file prior
+   * to the next time the analysis state transitions to "idle".
+   *
+   * Invocation of [addFile] or [changeFile] might result in producing more
+   * analysis results that reflect the new current file state.
    *
    * More than one result might be produced for the same file, even if the
    * client does not change the state of the files.
    *
    * Results might be produced even for files that have never been added
    * using [addFile], for example when [getResult] was called for a file.
    */
   Stream<AnalysisResult> get results async* {
     // TODO(scheglov) implement
   }
 
   /**
    * Add the file with the given [path] to the set of files to analyze.
    *
    * The [path] must be absolute and normalized.
    *
    * The results of analysis are eventually produced by the [results] stream.
    */
   void addFile(String path) {
     // TODO(scheglov) implement
   }
 
   /**
    * The file with the given [path] might have changed - updated, added or
    * removed. Or not, we don't know. Or it might have, but then changed back.
    *
    * The [path] must be absolute and normalized.
    *
-   * The driver might use this information to decide that new analysis results
-   * should be produced, but does not guarantee this, nor for the given file,
-   * nor for any other file.
+   * The [path] can be any file - explicitly or implicitly analyzed, or neither.
+   *
+   * Causes the analysis state to transition to "analyzing" (if it is not in
+   * that state already). Schedules the file contents for [path] to be read
+   * into the current file state prior to the next time the analysis state
+   * transitions to "idle".
    *
    * Invocation of this method will not prevent a [Future] returned from
-   * [getResult] from completing with a result, and does not guarantee that the
-   * result will reflect the state of the file at the moment before, at or
-   * after the invocation of [changeFile].
+   * [getResult] from completing with a result, but the result is not
+   * guaranteed to be consistent with the new current file state after this
+   * [changeFile] invocation.
    */
   void changeFile(String path) {
     // TODO(scheglov) implement
   }
 
   /**
    * Return the [Future] that completes with a [AnalysisResult] for the file
    * with the given [path].
    *
    * The [path] must be absolute and normalized.
    *
-   * The result is not guaranteed to be produced for the state of the file
-   * which is closest to the moment of the invocation. But if the client
-   * continues invoking this method, eventually one of the invocations will
-   * return a [Future] that completes with the result that is closer to the
-   * state of the files.
+   * The [path] can be any file - explicitly or implicitly analyzed, or neither.
+   *
+   * Causes the analysis state to transition to "analyzing" (if it is not in

[Brian Wilkerson, 2016/10/25 17:34:16]

Will it always transition, or is there room here for having the results cached
from the last analysis and for us to just return the cached result?

[scheglov, 2016/10/25 18:53:31]

As I see getResult(), it always returns the resolved CompilationUnit.
And I would like to avoid caching anything as heavy as CompilationUnit(s).

We could have a fast decaying cache, which keeps, e.g. 5 units for 5 seconds.
Or such caching could be up to the client.

+   * that state already), the driver will read the file and produce the analysis
+   * result for it, which is consistent with the current file state (including
+   * the new state of the file), prior to the next time the analysis state
+   * transitions to "idle".
    */
   Future<AnalysisResult> getResult(String path) {
     // TODO(scheglov) implement
     throw new UnimplementedError();
   }
 
   /**
    * Remove the file with the given [path] from the list of files to analyze.
    *
    * The [path] must be absolute and normalized.
@@ skipping 47 matching lines @@
   final CompilationUnit unit;
 
   /**
    * The full list of computed analysis errors, both syntactic and semantic.
    */
   final List<AnalysisError> errors;
 
   AnalysisResult(this.path, this.uri, this.content, this.contentHash, this.unit,
       this.errors);
 }