gopls/doc: respond to Hana's review of CL 583316

Also:
- contributor notes on keeping docs up to date;
- add "Added in v0.17" on "Extract to new file".
- various other fixes and tweaks.

Change-Id: I23666654a55190e99109b11cc65ca175a77de65e
Reviewed-on: https://go-review.googlesource.com/c/tools/+/595835
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Robert Findley <rfindley@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>

Author: adonovan

gopls/doc/advanced.md

@@ -9,7 +9,7 @@ To get a specific version of `gopls` (for example, to test a prerelease
 version), run:
 
 ```sh
-GO111MODULE=on go install golang.org/x/tools/gopls@vX.Y.Z
+$ go install golang.org/x/tools/gopls@vX.Y.Z
 ```
 
 Where `vX.Y.Z` is the desired version.

gopls/doc/analyzers.md

@@ -15,7 +15,7 @@ before you run your tests, or even before you save your files.
 This document describes the suite of analyzers available in gopls,
 which aggregates analyzers from a variety of sources:
 
-- all the usual bug-finding analyzers from the `go vet` suite (e.g. `printf`; run `go tool vet help` for the complete list);
+- all the usual bug-finding analyzers from the `go vet` suite (e.g. `printf`; see [`go tool vet help`](https://pkg.go.dev/cmd/vet) for the complete list);
 - a number of analyzers with more substantial dependencies that prevent them from being used in `go vet` (e.g. `nilness`);
 - analyzers that augment compilation errors by suggesting quick fixes to common mistakes (e.g. `fillreturns`); and
 - a handful of analyzers that suggest possible style improvements (e.g. `simplifyrange`).

gopls/doc/contributing.md

@@ -165,3 +165,17 @@ telemetry.-->
 
 [issue-gopls]: https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Agopls "gopls issues"
 [issue-wanted]: https://github.com/golang/go/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Agopls+label%3A"help+wanted" "help wanted"
+
+## Documentation
+
+Each CL that adds or changes a feature should include, in addition to
+a test that exercises the new behavior:
+
+- a **release note** that briefly explains the change, and
+- **comprehensive documentation** in the [index of features](features/README.md).
+
+The release note should go in the file named for the forthcoming
+release, for example [release/v0.16.0.md](release/v0.16.0.md). (Create
+the file if your feature is the first to be added after a release.)
+
+

gopls/doc/features/README.md

@@ -21,33 +21,35 @@ briefly mention whether each feature is supported in other popular
 clients, and if so, how to find it. We welcome contributions, edits,
 and updates from users of any editor.
 
+Contributors should [update this documentation](../contributing.md#documentation)
+when making significant changes to existing features or when adding new ones.
+
 - [Passive](passive.md): features that are always on and require no special action
-  - [Hover](passive.md#Hover): information about the symbol under the cursor
-  - [SignatureHelp](passive.md#SignatureHelp): type information about the enclosing function call
-  - [DocumentHighlight](passive.md#DocumentHighlight): highlight identifiers referring to the same symbol
-  - [InlayHint](passive.md#InlayHint): show implicit names of struct fields and parameter names
-  - [SemanticTokens](passive.md#SemanticTokens): report syntax information used by editors to color the text
-  - [FoldingRange](passive.md#FoldingRange): report text regions that can be "folded" (expanded/collapsed) in an editor
-  - [DocumentLink](passive.md#DocumentLink): extracts URLs from doc comments, strings in current file so client can linkify
+  - [Hover](passive.md#hover): information about the symbol under the cursor
+  - [Signature Help](passive.md#signature-help): type information about the enclosing function call
+  - [Document Highlight](passive.md#document-highlight): highlight identifiers referring to the same symbol
+  - [Inlay Hint](passive.md#inlay-hint): show implicit names of struct fields and parameter names
+  - [Semantic Tokens](passive.md#semantic-tokens): report syntax information used by editors to color the text
+  - [Folding Range](passive.md#folding-range): report text regions that can be "folded" (expanded/collapsed) in an editor
+  - [Document Link](passive.md#document-link): extracts URLs from doc comments, strings in current file so client can linkify
 - [Diagnostics](diagnostics.md): compile errors and static analysis findings
-  - TODO: expand subindex
 - [Navigation](navigation.md): navigation of cross-references, types, and symbols
-  - [Definition](navigation.md#Definition): go to definition of selected symbol
-  - [TypeDefinition](navigation.md#TypeDefinition): go to definition of type of selected symbol
-  - [References](navigation.md#References): list references to selected symbol
-  - [Implementation](navigation.md#Implementation): show "implements" relationships of selected type
-  - [DocumentSymbol](passive.md#DocumentSymbol): outline of symbols defined in current file
-  - [Symbol](navigation.md#Symbol): fuzzy search for symbol by name
-  - [SelectionRange](navigation.md#SelectionRange): select enclosing unit of syntax
-  - [CallHierarchy](navigation.md#CallHierarchy): show outgoing/incoming calls to the current function
+  - [Definition](navigation.md#definition): go to definition of selected symbol
+  - [Type Definition](navigation.md#type-definition): go to definition of type of selected symbol
+  - [References](navigation.md#references): list references to selected symbol
+  - [Implementation](navigation.md#implementation): show "implements" relationships of selected type
+  - [Document Symbol](passive.md#document-symbol): outline of symbols defined in current file
+  - [Symbol](navigation.md#symbol): fuzzy search for symbol by name
+  - [Selection Range](navigation.md#selection-range): select enclosing unit of syntax
+  - [Call Hierarchy](navigation.md#call-hierarchy): show outgoing/incoming calls to the current function
 - [Completion](completion.md): context-aware completion of identifiers, statements
 - [Code transformation](transformation.md): fixes and refactorings
-  - [Formatting](transformation.md#Formatting): format the source code
-  - [Rename](transformation.md#Rename): rename a symbol or package
-  - [Organize imports](transformation.md#OrganizeImports): organize the import declaration
-  - [Extract](transformation.md#Extract): extract selection to a new file/function/variable
-  - [Inline](transformation.md#Inline): inline a call to a function or method
-  - [Miscellaneous rewrites](transformation.md#Rewrite): various Go-specific refactorings
+  - [Formatting](transformation.md#formatting): format the source code
+  - [Rename](transformation.md#rename): rename a symbol or package
+  - [Organize imports](transformation.md#organize-imports): organize the import declaration
+  - [Extract](transformation.md#extract): extract selection to a new file/function/variable
+  - [Inline](transformation.md#inline): inline a call to a function or method
+  - [Miscellaneous rewrites](transformation.md#miscellaneous-rewrites): various Go-specific refactorings
 - [Web-based queries](web.md): commands that open a browser page
   - [Package documentation](web.md#doc): browse documentation for current Go package
   - [Free symbols](web.md#freesymbols): show symbols used by a selected block of code

gopls/doc/features/diagnostics.md

@@ -8,12 +8,12 @@ diagnostics and sends them to the client using the LSP
 notification, giving you real-time feedback that reduces the cost of
 common mistakes.
 
-Diagnostics come from two main sources: build errors and analysis findings.
+Diagnostics come from two main sources: compilation errors and analysis findings.
 
-- **Build errors** are those that you would obtain from running `go
+- **Compilation errors** are those that you would obtain from running `go
   build`. Gopls doesn't actually run the compiler; that would be too
   slow. Instead it runs `go list` (when needed) to compute the
-  metadata of the build, then processes those packages in a similar
+  metadata of the compilation, then processes those packages in a similar
   manner to the compiler front-end: reading, scanning, and parsing the
   source files, then type-checking them. Each of these steps can
   produce errors that gopls will surface as a diagnostic.
@@ -54,13 +54,14 @@ Diagnostics come from two main sources: build errors and analysis findings.
 Diagnostics are automatically recomputed each time the source files
 are edited.
 
-Build errors are updated immediately after each file is edited,
-potentially after every keystroke. This ensures rapid feedback of
-syntax and type errors while editing.
+Compilation errors in open files are updated after a very short delay
+(tens of milliseconds) after each file change, potentially after every keystroke.
+This ensures rapid feedback of syntax and type errors while editing.
+
+Compilation and analysis diagnostics for the whole workspace are much
+more expensive to compute, so they are usually recomputed after a
+short idle period (around 1s) following an edit.
 
-Analysis diagnostics can be more expensive to compute than type
-checking, so they are usually recomputed after a short idle period
-following an edit.
 The [`diagnosticsDelay`](../settings.md#diagnosticsDelay) setting determines
 this period.
 Alternatively, diagnostics may be triggered only after an edited file
@@ -78,7 +79,7 @@ ways to fix the problem by editing the code.
 For example, when a `return` statement has too few operands,
 the [`fillreturns`](../analyzers.md#fillreturns) analyzer
 suggests a fix that heuristically fills in the missing ones
-with suitable values. Applying the fix eliminates the build error.
+with suitable values. Applying the fix eliminates the compilation error.
 
 ![An analyzer diagnostic with two alternative fixes](../assets/remove-unusedparam-before.png)
 
@@ -104,9 +105,9 @@ Settings:
   the base URI for Go package links in the Diagnostic.CodeDescription field.
 
 Client support:
-- **VS Code**: Diagnostics appear as a red squiggly underline.
+- **VS Code**: Diagnostics appear as a squiggly underline.
   Hovering reveals the details, along with any suggested fixes.
-- **Emacs + eglot**: Diagnostics appear as a red squiggly underline.
+- **Emacs + eglot**: Diagnostics appear as a squiggly underline.
   Hovering reveals the details. Use `M-x eglot-code-action-quickfix`
   to apply available fixes; it will prompt if there are more than one.
 - **Vim + coc.nvim**: ??
@@ -118,7 +119,7 @@ dorky details and deletia:
 
 - The **vet suite**, of about thirty analyzers
   designed to catch likely mistakes in your code.
- 
+
 - **Type-error fixers**. These are gopls-specific analyzers that
   enrich diagnostics from the type checker by suggesting fixes for
   simple problems.

gopls/doc/features/navigation.md

@@ -17,7 +17,7 @@ A definition query also works in these unexpected places:
 - On a symbol in a **[`go:linkname` directive](https://pkg.go.dev/cmd/compile)**,
   it returns the location of that symbol's declaration.
 - On a **[doc link](https://tip.golang.org/doc/comment#doclinks)**, it returns
-  (like [`hover`](passive.md#Hover)) the location of the linked symbol.
+  (like [`hover`](passive.md#hover)) the location of the linked symbol.
 - On a file name in a **[`go:embed` directive](https://pkg.go.dev/embed)**,
   it returns the location of the embedded file.
 
@@ -40,7 +40,7 @@ request returns the locations of all identifiers that refers to the symbol under
 The references algorithm handles various parts of syntax as follows:
 
 - The references to a **symbol** report all uses of that symbol.
-  In the case of exported this may include locations in other packages.
+  In the case of exported symbols this may include locations in other packages.
 - The references to a **package declaration** are all the
   direct imports of the package, along with all the other package
   declarations in the same package.
@@ -112,7 +112,7 @@ Client support:
 - **CLI**: `gopls implementation file.go:#offset`
 
 
-## TypeDefinition
+## Type Definition
 
 The LSP
 [`textDocument/typeDefinition`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_typeDefinition)
@@ -141,17 +141,17 @@ Client support:
 - **Vim + coc.nvim**: ??
 - **CLI**: not supported
 
-## DocumentSymbol
+## Document Symbol
 
 The `textDocument/documentSymbol` LSP query reports the list of
 top-level declarations in this file. Clients may use this information
 to present an overview of the file, and an index for faster navigation.
 
-Gopls responds with the newer
+Gopls responds with the
 [`DocumentSymbol`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#documentSymbol)
 type if the client indicates
 [`hierarchicalDocumentSymbolSupport`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#documentSymbolClientCapabilities);
-otherwise it returns the older
+otherwise it returns a
 [`SymbolInformation`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#symbolInformation).
 
 Client support:
@@ -182,7 +182,7 @@ It also supports the following special characters within queries:
 | `$`       | `printf$` | exact suffix |
 
 However, VS Code does its own fuzzy matching afterward, so these
-aren't effective in that client.
+aren't effective in that client; see golang/vscode-go#647.
 -->
 
 TODO: screenshot
@@ -200,7 +200,7 @@ Client support:
 - **CLI**: `gopls links file.go`
 
 
-## SelectionRange
+## Selection Range
 
 The
 [`textDocument/selectionRange`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification#textDocument_selectionRange)
@@ -215,7 +215,7 @@ Client support:
 - **Vim + coc.nvim**: ??
 - **CLI**: not supported
 
-## CallHierarchy
+## Call Hierarchy
 
 The LSP CallHierarchy mechanism consists of three queries that
 together enable clients to present a hierarchical view of a portion of

gopls/doc/features/passive.md

@@ -27,7 +27,7 @@ plus any methods promoted from embedded fields.
 
 **Doc links**: A doc comment may refer to another symbol using square
 brackets, for example `[fmt.Printf]`. Hovering over one of these
-[doc links](https://tip.golang.org/doc/comment#doclinks) reveals
+[doc links](https://go.dev/doc/comment#doclinks) reveals
 information about the referenced symbol.
 
 <img src='../assets/hover-doclink.png'>
@@ -71,6 +71,9 @@ Hovering over the directive shows information about the other symbol.
 
 <img src='../assets/hover-linkname.png'>
 
+The hover information for symbols from the standard library added
+after Go 1.0 states the Go release that added the symbol.
+
 Settings:
 - The [`hoverKind`](../settings.md#hoverKind) setting controls the verbosity of documentation.
 - The [`linkTarget`](../settings.md#linkTarget) setting specifies
@@ -91,7 +94,7 @@ Client support:
 - **CLI**: `gopls definition file.go:#start-#end` includes information from a Hover query.
 
 
-## SignatureHelp
+## Signature Help
 
 The LSP [`textDocument/signatureHelp`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_signatureHelp)
 query returns information about the innermost function call enclosing
@@ -105,13 +108,15 @@ function call.
 <img src='../assets/signature-help.png'>
 
 Client support:
-- **VS Code**: enabled by default. Displays signature and doc comment alongside Hover information.
+- **VS Code**: enabled by default.
+  Also known as "[parameter hints](https://code.visualstudio.com/api/references/vscode-api#SignatureHelpProvider)" in the [IntelliSense settings](https://code.visualstudio.com/docs/editor/intellisense#_settings).
+  Displays signature and doc comment alongside Hover information.
 - **Emacs + eglot**: enabled by default. Displays signature in the echo area.
 - **Vim + coc.nvim**: ??
 - **CLI**: `gopls signature file.go:#start-#end`
 
 
-## DocumentHighlight
+## Document Highlight
 
 The LSP [`textDocument/documentHighlight`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_documentHighlight)
 query reports a set of source ranges that should be highlighted based
@@ -140,7 +145,7 @@ Client support:
 - **CLI**: `gopls signature file.go:#start-#end`
 
 
-## InlayHint
+## Inlay Hint
 
 The LSP [`textDocument/inlayHint`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_inlayHint)
 query returns a set of annotations to be spliced into the current file
@@ -189,7 +194,7 @@ Client  support:
 - **Vim + coc.nvim**: ??
 - **CLI**: not supported
 
-## SemanticTokens
+## Semantic Tokens
 
 The LSP [`textDocument/semanticTokens`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_semanticTokens)
 query reports information about all the tokens in the current file, or
@@ -220,7 +225,7 @@ Client Support:
 For internal details of gopls' implementation of semantic tokens,
 see [semantic tokens](../semantictokens.md).
 
-## FoldingRange
+## Folding Range
 
 The LSP [`textDocument/foldingRange`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_foldingRange)
 query reports the list of regions in the current file that may be
@@ -240,7 +245,7 @@ Client support:
 - **Vim + coc.nvim**: ??
 - **CLI**: `gopls folding_ranges file.go`
 
-## DocumentLink
+## Document Link
 
 The LSP [`textDocument/documentLink`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_documentLink)
 query uses heuristics to extracts URLs from doc comments and string

gopls/doc/features/transformation.md

@@ -13,7 +13,6 @@ Code transformations are not a single category in the LSP:
   <!-- Generate, RegenerateCgo (Go); Tidy, UpgradeDependency, Vendor (go.mod) -->
 - most are defined as *code actions*.
 
-<a id='code-actions'></a>
 ## Code Actions
 
 A **code action** is an action associated with a portion of the file.
@@ -241,10 +240,11 @@ in the latter half of this 2015 GothamGo talk:
 Client support:
 - **VS Code**: Use "[Rename symbol](https://code.visualstudio.com/docs/editor/editingevolved#_rename-symbol)" menu item (`F2`).
 - **Emacs + eglot**: Use `M-x eglot-rename`, or `M-x go-rename` from [go-mode](https://github.com/dominikh/go-mode.el).
+- **Vim + coc.nvim**: Use the `coc-rename` command.
 - **CLI**: `gopls rename file.go:#offset newname`
 
 
-<a id='Extract'></a>
+<a name='extract'></a>
 ## Extract function/method/variable
 
 The `refactor.extract` family of code actions all return commands that
@@ -296,9 +296,6 @@ The following Extract features are planned for 2024 but not yet supported:
 
 - **Extract constant** is a variant of "Extract variable" to be
   offered when the expression is constant; see golang/go#37170.
-- **Extract to new file** will extract one or more top-level
-  declarations into a new file in the same package; see golang/go#65707.
-  <!-- TODO(adonovan): update when https://go.dev/cl/565895 lands. -->
 - **Extract parameter struct** will replace two or more parameters of a
   function by a struct type with one field per parameter; see golang/go#65552.
   <!-- TODO(adonovan): review and land https://go.dev/cl/563235. -->
@@ -308,9 +305,11 @@ The following Extract features are planned for 2024 but not yet supported:
   see golang/go#65721 and golang/go#46665.
 
 
-<a id='extract-to-new-file'></a>
+<a name='extract-to-new-file'></a>
 ## Extract declarations to new file
 
+(Available from gopls/v0.17.0)
+
 If you select one or more top-level declarations, gopls will offer an
 "Extract declarations to new file" code action that moves the selected
 declarations into a new file whose name is based on the first declared
@@ -323,7 +322,7 @@ Import declarations are created as needed.
 ![After: the new file is based on the first symbol name](../assets/extract-to-new-file-after.png)
 
 
-<a id='Inline'></a>
+<a name='inline'></a>
 ## Inline call to function
 
 For a `codeActions` request where the selection is (or is within) a
@@ -478,7 +477,6 @@ more detail. All of this is to say, it's a complex problem, and we aim
 for correctness first of all. We've already implemented a number of
 important "tidiness optimizations" and we expect more to follow.
 
-<a id='Rewrite'></a>
 ## Miscellaneous rewrites
 
 This section covers a number of transformations that are accessible as
@@ -487,7 +485,6 @@ code actions of kind `refactor.rewrite`.
 <!-- See TODO comments in settings/codeactionkind.go about splitting
      up "refactor.extract" into finer grained categories. -->
 
-<a id='remove-unused-parameter'></a>
 ### Remove unused parameter
 
 The [`unusedparams` analyzer](../analyzers.md#unusedparams) reports a