Add documentation for code completion
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>
diff --git a/pkg/analysis_server/doc/implementation/code_completion.md b/pkg/analysis_server/doc/implementation/code_completion.md
new file mode 100644
index 0000000..cff9135
--- /dev/null
+++ b/pkg/analysis_server/doc/implementation/code_completion.md
@@ -0,0 +1,53 @@
+# 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.
diff --git a/pkg/analysis_server/doc/implementation/overview.md b/pkg/analysis_server/doc/implementation/overview.md
index f3a9dd5..851a901 100644
--- a/pkg/analysis_server/doc/implementation/overview.md
+++ b/pkg/analysis_server/doc/implementation/overview.md
@@ -3,31 +3,39 @@
This section of the documentation discusses how the analysis server works and
how to enhance the various features provided by the server.
+## Design
+
+The design of the analysis server beings with [a description of what the server
+does on startup](startup.md)
+
+## Features
+
To learn how the server implements support for a specific feature, read one of
the following feature-specific documents:
-- Call Hierarchy
-- Closing Labels
-- Code Completion
-- Code Folding
+
+- Call hierarchy
+- Closing labels
+- [Code completion](code_completion.md)
+- Code folding
- documentSymbol
-- Flutter Outline
+- Flutter outline
- Hovers
-- Implemented Markers
+- Implemented markers
- [Navigation](navigation.md)
- Occurrences
-- Organize Imports
+- Organize imports
- Outline
-- Overrides Markers
-- [Quick Assists](quick_assist.md)
-- [Quick Fixes](quick_fix.md)
+- Overrides markers
+- [Quick assists](quick_assist.md)
+- [Quick fixes](quick_fix.md)
- Refactorings - legacy
- Refactorings - self describing
-- Search - Find References
-- Search - Member Declarations
-- Search - Member References
-- Search - Top-level Declarations
+- Search - Find references
+- Search - Member declarations
+- Search - Member references
+- Search - Top-level declarations
- selectionRange
-- Semantic Highlights
+- [Semantic highlights](semantic_highlighting.md)
- signatureHelp
-- Sort Members
-- Type Hierarchy
+- Sort members
+- Type hierarchy
diff --git a/pkg/analysis_server/doc/introduction.md b/pkg/analysis_server/doc/introduction.md
index f01f816..9a776ce 100644
--- a/pkg/analysis_server/doc/introduction.md
+++ b/pkg/analysis_server/doc/introduction.md
@@ -1,8 +1,12 @@
# Introduction
-The `analysis_server` package implements the analysis server, which supports
-both the IDE experience and several command-line tools. This directory contains
-documentation related to the`analysis_server` package.
+The `analysis_server` package implements the Dart Analysis Server (sometimes
+referred to as DAS). The analysis server supports both the IDE experience and
+command-line tools such as `dart analyze` and `dart fix`.
+
+This directory contains documentation related to the `analysis_server` package.
+
+## Organization
The documentation is divided into the following sections:
@@ -10,5 +14,8 @@
implementation of the server. It is intended to help you understand how the
server works and how to enhance the various features provided by the server.
-- [process](process/overview.md), which describes the process that should be
- followed when working on the analysis server code base.
\ No newline at end of file
+- [process](process/overview.md), which describes the processes that should be
+ followed when working on the analysis server code base.
+
+- [tutorial](tutorial/instrumentation.md), which provides end-user information
+ about the analysis server.
