The customization mechanism provides the following pieces of
functionality:
- Allows access to the package name, the analysis context, the list of
public API libraries, and the set of top level public API elements.
- Allows customizing the logic for deciding which top level elements
to show details about.
- Provides hooks to allow additional code to be executed after setup
and after the initial scan.
This customization mechanism is used when generating
`pkg/analyzer/api.txt` to recognize that any element annotated with
`@AnalyzerPublicApi` should have details shown, even if it is not
exported in any analyzer public library.
The class used to perform customization, `ApiSummaryCustomizer`, is
marked `base` so that we can add additional hooks in the future
without breaking clients.
With this change, the API summary tool no longer has any hard-coded
analyzer-specific functionality.
Change-Id: I6a6a6964fcc626db8e8e387c306fc1ff03fbc0a9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/482442
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
This fixes a bootstrapping problem: previously we could get into a
situation where the generated files for analyzer diagnostic messages
were out of date, but the code generator for those messages couldn't
be run, because it imported the analyzer itself, which contained
compiled errors due to the generated files being out of date.
There were two problematic dependencies:
- The `GeneratedContent.check` and `GeneratedContent.checkAll` methods
relied on invoking the Dart formatter as a library (rather than
invoking `dart format` as a subprocess); the Dart formatter library
imports the analyzer. Fortunately, this functionality is not needed
by the code generators themselves. It's only needed by the _tests_
that verify that code generation has run. So I was able to break the
dependency by moving this functionality into a new file,
`package:analyzer_utilities/generated_content_check.dart`, which is
imported only by the code generation tests. The new API is slightly
different: `GeneratedContent.checkAll` has been replaced by an
extension method `check` on `Iterable<GeneratedContent>`.
- The diagnostic message code generator used to have a post-processing
step that made use of the scanner to find error messages used by the
parser that needed to be translated, and issued a warning if it
found any. This check was useful a long time ago, when we were
unifying the analyzer and CFE parsers, and is no longer useful, so
I've removed it.
Change-Id: I509b741faca3b9ae21c23936001105ded731b490
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/442241
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
Modifies `GeneratedDirectory.outputDirPath` and
`GeneratedFile.outputPath` to be relative to the SDK's `pkg` directory
rather than relative to the containing package. Accordingly, modifies
the `GeneratedContent` methods `check`, `checkAll`, `generate`,
`generateAll`, `output`, as well as the `DirectoryContentsComputer`
and `FileContentsComputer` callbacks, so that their first parameter is
the path to the `pkg` directory rather than the path to the containing
package.
Also modifies the `readApi` functions in `pkg/analysis_server` and
`pkg/analyzer_plugin` to accept a path to the `pkg` directory rather
than a path to the containing package, since these functions are
called by code generation callbacks.
These changes should make code generation logic easier to reason
about. They also will make it easier to move the outputs of code
generation from one package to another, which will pave the way for
some follow-up work in which I intend to start sharing error message
representations belonging to `pkg/analyzer`, `pkg/front_end`, and
`pkg/_fe_analyzer_shared`.
Change-Id: Ia9b369b16f2df931c8a472f91400f2c5a0b8be9d
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/438480
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
This change removes the top level variable `allTargets` from
`pkg/analyzer_utilities/lib/tool/api.dart` and replaces it with a
method `allTargetsForPackage`, parameterized by the name of the
package for which an `api.txt` file is generated. The individual code
generators that make use of this function now all have their own top
level variable `allTargets`.
In addition to being conceptually clearer (since we no longer have a
single `allTargets` variable with different meanings depending on
where it's used), this paves the way for a CL I am working on that
will change the `GeneratedContent` based code generators so that they
use paths relative to the `pkg` directory. That in turn should make it
simpler to move some of the code generated files that have to do with
error messages from `pkg/analyzer` to `pkg/_fe_analyzer_shared`.
Change-Id: Id636ddbca27c46ae4242bbf8e4b6f7b8dae4d4e9
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/438481
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Auto-Submit: Paul Berry <paulberry@google.com>
Commit-Queue: Samuel Rawlins <srawlins@google.com>
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>
kevmoo