diff --git a/gopls/doc/advanced.md b/gopls/doc/advanced.md
index d66ce8743a2..4c5e6015fd7 100644
--- a/gopls/doc/advanced.md
+++ b/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.
diff --git a/gopls/doc/analyzers.md b/gopls/doc/analyzers.md
index 04101131353..45db766719f 100644
--- a/gopls/doc/analyzers.md
+++ b/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`).
diff --git a/gopls/doc/contributing.md b/gopls/doc/contributing.md
index 594bcd4f32a..007c5793073 100644
--- a/gopls/doc/contributing.md
+++ b/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.)
+
+
diff --git a/gopls/doc/features/README.md b/gopls/doc/features/README.md
index 6c93b0339c6..fc559fd9ab3 100644
--- a/gopls/doc/features/README.md
+++ b/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
diff --git a/gopls/doc/features/diagnostics.md b/gopls/doc/features/diagnostics.md
index 4bf1138af6c..374c5f97962 100644
--- a/gopls/doc/features/diagnostics.md
+++ b/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.
@@ -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.
diff --git a/gopls/doc/features/navigation.md b/gopls/doc/features/navigation.md
index 2bf4411d292..973507dfc51 100644
--- a/gopls/doc/features/navigation.md
+++ b/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
diff --git a/gopls/doc/features/passive.md b/gopls/doc/features/passive.md
index 39c0ba6bd0e..ec10f509742 100644
--- a/gopls/doc/features/passive.md
+++ b/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.
@@ -71,6 +71,9 @@ Hovering over the directive shows information about the other symbol.
+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.
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
diff --git a/gopls/doc/features/transformation.md b/gopls/doc/features/transformation.md
index 615a59a3093..14de653f346 100644
--- a/gopls/doc/features/transformation.md
+++ b/gopls/doc/features/transformation.md
@@ -13,7 +13,6 @@ Code transformations are not a single category in the LSP:
- most are defined as *code actions*.
-
## 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`
-
+
## 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.
-
- **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.
@@ -308,9 +305,11 @@ The following Extract features are planned for 2024 but not yet supported:
see golang/go#65721 and golang/go#46665.
-
+
## 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.
-
+
## 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.
-
## Miscellaneous rewrites
This section covers a number of transformations that are accessible as
@@ -487,7 +485,6 @@ code actions of kind `refactor.rewrite`.
-
### Remove unused parameter
The [`unusedparams` analyzer](../analyzers.md#unusedparams) reports a
diff --git a/gopls/doc/features/web.md b/gopls/doc/features/web.md
index 682d8e517d3..4940ee199da 100644
--- a/gopls/doc/features/web.md
+++ b/gopls/doc/features/web.md
@@ -40,7 +40,7 @@ indicating that they have become disconnected.
TODO: combine the web server and the debug server; see golang/go#68229.
Gopls supports two-way communication between the web browser and the
-client editor. All of the web-based reports contains links to
+client editor. All of the web-based reports contain links to
declarations in your source code. Clicking on one of these links
causes gopls to send a `showDocument` request to your editor to open
the relevant source file at the appropriate line. This works even when
@@ -48,7 +48,7 @@ your source code has been modified but not saved.
(VS Code users: please upvote microsoft/vscode#208093 if you would
like your editor to raise its window when handling this event.)
-
+
## View package documentation
In any Go source file, a code action request returns a command to
@@ -74,7 +74,7 @@ Client support:
- **Vim + coc.nvim**: ??
-
+
## View free symbols
When studying code, either to understand it or to evaluate a different
@@ -107,7 +107,7 @@ Client support:
- **Vim + coc.nvim**: ??
-
+
## View assembly
When you're optimizing the performance of your code or investigating
diff --git a/gopls/doc/inlayHints.md b/gopls/doc/inlayHints.md
index 3d693baeae1..0e84d43f1da 100644
--- a/gopls/doc/inlayHints.md
+++ b/gopls/doc/inlayHints.md
@@ -1,6 +1,6 @@
# Gopls: Inlay hints
-Inlay Hints are helpful annotations that the editor can optionally
+Inlay hints are helpful annotations that the editor can optionally
display in-line in the source code, such as the names of parameters in
a function call. This document describes the inlay hints available
from `gopls`.