From 70a59b2f224b125b843a948e205c0792dbff4f22 Mon Sep 17 00:00:00 2001 From: Alan Donovan Date: Fri, 28 Jun 2024 14:29:32 -0400 Subject: [PATCH] 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 Reviewed-by: Robert Findley Auto-Submit: Alan Donovan --- gopls/doc/advanced.md | 2 +- gopls/doc/analyzers.md | 2 +- gopls/doc/contributing.md | 14 +++++++++ gopls/doc/features/README.md | 46 +++++++++++++++------------- gopls/doc/features/diagnostics.md | 27 ++++++++-------- gopls/doc/features/navigation.md | 18 +++++------ gopls/doc/features/passive.md | 21 ++++++++----- gopls/doc/features/transformation.md | 15 ++++----- gopls/doc/features/web.md | 8 ++--- gopls/doc/inlayHints.md | 2 +- 10 files changed, 87 insertions(+), 68 deletions(-) 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. ![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. 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. ![After: the new file is based on the first symbol name](../assets/extract-to-new-file-after.png) - + ## 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`.