Add documentation for code completion

Change-Id: Ic2954ff86e4fa36ea12e96ffebef6d5621137eb5
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/404522
Reviewed-by: Samuel Rawlins <[email protected]>
Commit-Queue: Brian Wilkerson <[email protected]>

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.

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

pkg/analysis_server/doc/introduction.md

@@ -1,14 +1,21 @@
 # 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:
 
 - [implementation](implementation/overview.md), which describes the
   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.
+- [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.