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 change splits the file `pkg/analyzer_utilities/lib/tool/api.dart`
into several files:
- `api_description.dart`, which contains the `ApiDescription` class
that does the bulk of the work.
- `extensions.dart`, which contains utility extensions.
- `member_sorting.dart`, which encapsulates information about how to
sort members.
- `node.dart`, which defines the tree data structure that is used to
build the output.
- `unique_namer.dart`, which defines the logic for disambiguating
elements that have the same name.
- `uri_sorting.dart`, which encapsulates information about how to sort
URIs.
- `summarize_package.dart`, which contains the code for driving the
`ApiDescription` class.
This is in preparation for extracting this logic from
`analyzer_utilities` and releasing them as a separate pub package
called `api_summary`, so that they can be used by other
projects. Accordingly, I've placed all of these files in their own
directory, `pkg/analyzer_utilities/lib/src/api_summary`. The files
that will eventually wind up in `package:api_summary/src` are in
`pkg/analyzer_utilities/lib/src/api_summary/src`.
(Under ordinary circumstances it would be strange to have a `src`
directory nested inside another `src` directory, but I believe that in
this case it's justified, since it allows us to see which files will
eventually end up in the public API of the `api_summary` package and
which will not.)
I still want to do some final polishing of the tool before publishing
it as its own package:
- Adding unit tests
- Fixing a few bugs
- Generalizing some behaviors that currently only make sense when
analyzing the `analyzer` package.
I intend to do this polishing in follow-up CLs. Then, once the
`api_summary` package is published, I will import the package into the
SDK and remove all the files in
`pkg/analyzer_utilities/lib/src/api_summary`.
Change-Id: I6a6a6964a5f71a732bbee0bfcdcec9458737d703
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/482101
Commit-Queue: Paul Berry <paulberry@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
When generating `api.txt` files, it's important to verify that the
`AnalysisContextCollection` contains just a single analysis context,
otherwise `publicApi.build` won't see all the files in the package,
and some parts of the API will be left out.
This change switches to `collection.contexts.single` instead of
`collection.contexts.first`, so that if something goes wrong and the
collection contains more than one analysis context, an error will
occur rather than silent misbehavior.
Change-Id: I6a6a69647f5cd957a1a04bbb54940f48eefce3f8
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/444860
Auto-Submit: Paul Berry <paulberry@google.com>
Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
When I added `deprecated` annotations to `api.txt`, I forgot that
function parameters could be deprecated too. This change fixes the
omission and regenerates `api.txt`.
There is no actual API change.
Change-Id: I27620d9faaa834299a1b7158b66424065e7bfda7
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/443634
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Reviewed-by: Phil Quitslund <pquitslund@google.com>
Commit-Queue: Paul Berry <paulberry@google.com>
The null assert in `PropertyAccessorElementImpl.variable` is safe
because `ElementBuilder` always creates synthetic
`TopLevelVariableFragmentImpl` or `FieldElementImpl` for a getter or
setter. And the other way around, non-synthetic
`TopLevelVariableFragmentImpl` or `FieldElementImpl` when created
associate itself with synthetic getter / setter.
Change-Id: I40e4ce866edffab6c8bcdf6e408bd1bbfbba6581
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/442246
Reviewed-by: Samuel Rawlins <srawlins@google.com>
Reviewed-by: Paul Berry <paulberry@google.com>
Commit-Queue: Konstantin Shcheglov <scheglov@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>
kevmoo