Also, add some scripts to generate the analyzer_testing API, and checkin
the api.txt file for analyzer_testing.
In order to avoid a private analyzer import, I add `isExperimental` and
`hasExperimental` support for `@experimental` annotation, and switch
to using public APIs in `_dumpElement`.
Change-Id: I44319270d4e6083b80973b45933268c472876232
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/426282
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Paul Berry <paulberry@google.com>
Work towards https://github.com/dart-lang/sdk/issues/60635
* `AnalysisError._contextMessages` unnecessarily backed the public
`contextMessages` getter; the field is final so it can be public
itself.
* `AnalysisError._correctionMessage` unnecessarily backed the public
`correctionMessage` getter; the field is final so it can be public
itself.
Change-Id: If269d4ed590ef7df81d9b9e3be03766601526d7f
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/425620
Commit-Queue: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Paul Berry <paulberry@google.com>
It occurred to me that it might make it easier to code review changes
to `api.txt` if it included annotations of when an API was marked
`@experimental` or `@deprecated`.
Change-Id: If52eebe2e5086e92491d53bd9d63d3b18c79901e
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/413243
Commit-Queue: Paul Berry <paulberry@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
The summary is checked into source control in
`pkg/analyzer/api.txt`. It contains an entry for each type
declaration, extension, function, method, getter, or setter that is
part of the analyzer API, as well as the types of all functions,
methods, getters, and setters, and all type declarations referenced by
those types.
The tool `pkg/analyzer/tool/api/generate.dart` regenerates
`api.txt`. The test `pkg/analyzer/tool/api/generate_test.dart` checks
that generation of `api.txt` is up to date.
The intention is that `api.txt` will serve as an audit trail to (a)
detect unintentional changes to the analyzer public API, and (b) help
ensure that the developer experience team reviews intentional changes
to the analyzer public API. Once an appropriate OWNERS file has been
set up for the developer experience team, I intend to add an ownership
rule to require developer experience team review for this file.
The structure of the file is hierarchical, with top level nodes
representing libraries URIs, children of those nodes representing top
level elements declared or exported by those libraries, and
grandchildren of those nodes representing members of type
declarations.
If a type is considered part of the API, but it isn't exported by an
analyzer public API library (e.g., the type `Namespace`, which is
declared in `package:analyzer/src/dart/resolver/scope.dart`, but part
of the analyzer API due being exposed by
`LibraryElement.exportNamespace`, `LibraryElement.publicNamespace`,
`LibraryImportElement.namespace`, and so on), then it is listed under
the URI of the library that declares it.
If a type is not considered part of the API, but it is declared inside
`package:analyzer` and it is referenced by something in the API (e.g.,
`Workspace`, which is a private analyzer class but is the type of
`ContextRoot.workspace`), then instead of listing the members of the
type declaration, `api.txt` simply says `(non-public)` after the entry
for the type.
If a type is not considered part of the API, and it is not declared
inside `package:analyzer`, but it is referenced by something in the
API (e.g., `WatchEvent`, which comes from `package:watcher` but is
used in the type of `ResourceWatcher.changes`), then instead of
listing the members of the type declaration, `api.txt` simply says
`(referenced)` after the entry for the type.
If there are two distinct declarations in `api.txt` with the same name
(e.g., the two declarations of `AnalysisContext` from
`package:analyzer/dart/analysis/analysis_context.dart` and
`package:analyzer/src/generated/engine.dart`), then they are
disambiguated by appending an `@` symbol followed by an integer.
Change-Id: Ia2c856e79feebabb74aeb26f57c0a1eea7c63f68
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/409862
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
Sam Rawlins