Brian Wilkerson
2556d0155c
Change-Id: Ic2954ff86e4fa36ea12e96ffebef6d5621137eb5 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/404522 Reviewed-by: Samuel Rawlins <srawlins@google.com> Commit-Queue: Brian Wilkerson <brianwilkerson@google.com>
54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# Code completion
|
|
|
|
This document describes how code completion is implemented and how to fix bugs
|
|
and extend it.
|
|
|
|
## Basic operation
|
|
|
|
Code completion begins with the receipt of either a `completion.getSuggestions2`
|
|
request (from the legacy protocol) or a `textDocument/completion` request (from
|
|
LSP). When the request is received the appropriate handler is invoked. The
|
|
handler will compute a list of completion suggestions and will then translate
|
|
the suggestions into the form required by the protocol.
|
|
|
|
Code completion is supported in `.dart` files as well as in the `pubspec.yaml`,
|
|
`analysis_options.yaml`, and `fix_data.yaml` files.
|
|
|
|
Dart completion suggestions are computed using the `DartCompletionManager` by
|
|
invoking either the method `computeSuggestions` (for the legacy protocol) or
|
|
`computeFinalizedCandidateSuggestions`. (The legacy protocol will be changed to
|
|
use `computeFinalizedCandidateSuggestions` in the near future.)
|
|
|
|
The completion manager computes suggestions in two "passes".
|
|
|
|
- The `InScopeCompletionPass` computes suggestions for every appropriate element
|
|
whose name is visible in the name scope surrounding the completion location.
|
|
|
|
- The `NotImportedCompletionPass` computes suggestions for elements that are not
|
|
yet visible in the name scope surrounding the completion location. This pass
|
|
is skipped if there isn't time left in the `budget` or if there are already
|
|
enough suggestions that the not-yet-imported elements wouldn't be sent anyway.
|
|
|
|
## Maintaining and improving
|
|
|
|
The easiest way to fix bugs or add support for new features is to start by
|
|
writing a test in the directory `test/services/completion/dart/location`. These
|
|
tests are grouped based on the location in the grammar at which completion is
|
|
being requested.
|
|
|
|
When you have a test that's failing, add a breakpoint to
|
|
`InScopeCompletionPass.computeSuggestions`. When the debugger stops at the
|
|
breakpoint, hover over `_completionNode` to see what kind of node will be
|
|
visited. Add a breakpoint in the corresponding visit method and resume
|
|
execution. (If the visit method if it doesn't already exist, then add it and
|
|
restart the debugger).
|
|
|
|
## New language features
|
|
|
|
If a new language feature is being introduced that adds new syntax, then code
|
|
completion support will need to be updated. If the changes are limited to
|
|
updating an existing node then you should be able to use the method above to
|
|
update the corresponding visit method. If the changes required the addition of
|
|
some new subclasses of `AstNode`, then you'll likely need to add a new visit
|
|
method for the added nodes.
|