Update the API documentations with Paul review comments.

Update the API documentations with Paul review comments.

TBR

R=brianwilkerson@google.com, paulberry@google.com
BUG=

Committed: https://github.com/dart-lang/sdk/commit/46aa3ced6f8469d6bfd1829777eb15b05eb3c377

[scheglov, 2016-10-23 20:56:01]

Description was changed from

==========
Update the API documentations with Paul review comments.

TBR

R=brianwilkerson@google.com, paulberry@google.com
BUG=
==========

to

==========
Update the API documentations with Paul review comments.

TBR

R=brianwilkerson@google.com, paulberry@google.com
BUG=

Committed:
https://github.com/dart-lang/sdk/commit/46aa3ced6f8469d6bfd1829777eb15b05eb3c377
==========

[scheglov, 2016-10-23 20:56:03]

Committed patchset #1 (id:1) manually as
46aa3ced6f8469d6bfd1829777eb15b05eb3c377 (presubmit successful).

[Paul Berry, 2016-10-23 21:10:18]

lgtm

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
File pkg/analyzer/lib/src/dart/analysis/byte_store.dart (right):

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/byte_store.dart:11: * `[0-9]`, `.` and `_`
characters. It cannot have the sequence `..` in it.
Two other constraints:
- the key can't be the literal string "."
- the key can't be the empty string

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

lgtm

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
File pkg/analyzer/lib/src/dart/analysis/driver.dart (right):

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:44: * [changeFile] any time the
contents of a file on the file system have changed.
I assume a call to removeFile could transition the driver from analyzing to
idle. Do we need to mention that?

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:148: * Causes the analysis state
to transition to "analyzing" (if it is not in
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:32]

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
File pkg/analyzer/lib/src/dart/analysis/driver.dart (right):

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:44: * [changeFile] any time the
contents of a file on the file system have changed.
On 2016/10/25 17:34:16, Brian Wilkerson wrote:
> I assume a call to removeFile could transition the driver from analyzing to
> idle. Do we need to mention that?

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

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:148: * Causes the analysis state
to transition to "analyzing" (if it is not in
On 2016/10/25 17:34:16, Brian Wilkerson wrote:
> 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?

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.

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

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
File pkg/analyzer/lib/src/dart/analysis/driver.dart (right):

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:44: * [changeFile] any time the
contents of a file on the file system have changed.
> I'd like to have the only place where we switch from "analyzing" to "idle" -
in
> the "result" stream cycle.

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]

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
File pkg/analyzer/lib/src/dart/analysis/driver.dart (right):

https://codereview.chromium.org/2443013002/diff/1/pkg/analyzer/lib/src/dart/a...
pkg/analyzer/lib/src/dart/analysis/driver.dart:44: * [changeFile] any time the
contents of a file on the file system have changed.
On 2016/10/26 06:49:14, Brian Wilkerson wrote:
> > I'd like to have the only place where we switch from "analyzing" to "idle" -
> in
> > the "result" stream cycle.
> 
> 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?

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.