gopls/doc/features: more doc tweaks
Change-Id: Ia4f473b9ef7fe10463e7bb768801a63aac84e89a
Reviewed-on: https://go-review.googlesource.com/c/tools/+/596796
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
diff --git a/gopls/doc/features/diagnostics.md b/gopls/doc/features/diagnostics.md
index 374c5f9..f58a646 100644
--- a/gopls/doc/features/diagnostics.md
+++ b/gopls/doc/features/diagnostics.md
@@ -40,7 +40,7 @@
`fmt.Printf("%d", "three")`.
Gopls provides dozens of analyzers aggregated from a variety of
- suites. See [Analyzers](../analyzers.md) for the complete list. The
+ suites; see [Analyzers](../analyzers.md) for the complete list. The
`source` field of each diagnostic produced by an analyzer records
the name of the analyzer that produced it.
@@ -89,8 +89,14 @@
Suggested fixes that are indisputably safe are [code
actions](transformation.md#code-actions) whose kind is
-`"source.fixAll"`. Many client editors have a shortcut to apply all
-such fixes.
+`"source.fixAll"`.
+Many client editors have a shortcut to apply all such fixes.
+<!-- Note: each Code Action has exactly one kind, so a server
+ must offer each "safe" action twice, once with its usual kind
+ and once with kind "source.fixAll".
+ The only ones in gopls are simplify{compositelit,range,slice},
+ which are fixAll + quickfix.
+-->
TODO(adonovan): audit all the analyzers to ensure that their
documentation is up-to-date w.r.t. any fixes they suggest.
@@ -105,9 +111,9 @@
the base URI for Go package links in the Diagnostic.CodeDescription field.
Client support:
-- **VS Code**: Diagnostics appear as a squiggly underline.
+- **VS Code**: Each diagnostic appears as a squiggly underline.
Hovering reveals the details, along with any suggested fixes.
-- **Emacs + eglot**: Diagnostics appear as a squiggly underline.
+- **Emacs + eglot**: Each diagnostic appears 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**: ??
diff --git a/gopls/doc/features/navigation.md b/gopls/doc/features/navigation.md
index 973507d..5daac90 100644
--- a/gopls/doc/features/navigation.md
+++ b/gopls/doc/features/navigation.md
@@ -2,6 +2,8 @@
This page documents gopls features for navigating your source code.
+<!-- TODO: screenshots -->
+
## Definition
The LSP [`textDocument/definition`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_definition)
@@ -35,7 +37,7 @@
## References
The LSP [`textDocument/references`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_references)
-request returns the locations of all identifiers that refers to the symbol under the cursor.
+request returns the locations of all identifiers that refer to the symbol under the cursor.
The references algorithm handles various parts of syntax as follows:
@@ -169,7 +171,7 @@
The default symbol matching algorithm (`fastFuzzy`), inspired by the
popular fuzzy matcher [FZF](https://github.com/junegunn/fzf), attempts
-a variety of inexact matches to correct for misspellings in your
+a variety of inexact matches to correct for misspellings or abbreviations in your
query. For example, it considers `DocSym` a match for `DocumentSymbol`.
<!--
@@ -185,8 +187,6 @@
aren't effective in that client; see golang/vscode-go#647.
-->
-TODO: screenshot
-
Settings:
- The [`symbolMatcher`](../settings.md#symbolMatcher) setting controls the algorithm used for symbol matching.
- The [`symbolStyle`](../settings.md#symbolStyle) setting controls how symbols are qualified in symbol responses.
diff --git a/gopls/doc/features/passive.md b/gopls/doc/features/passive.md
index ec10f50..4d814ac 100644
--- a/gopls/doc/features/passive.md
+++ b/gopls/doc/features/passive.md
@@ -13,15 +13,15 @@
## Hover
The LSP [`textDocument/hover`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover)
-query returns description of the code currently under the cursor, such
+query returns a description of the code currently under the cursor, such
as its name, kind, type, value (for a constant), abbreviated
-declaration (for a type), its doc comment, if any, and a link to the
+declaration (for a type), doc comment (if any), and a link to the
symbol's documentation on `pkg.go.dev`. The client may request either
plain text or Markdown.
<img src='../assets/hover-basic.png'>
-Depending on the selection, it may include additional information.
+Depending on the selection, the response may include additional information.
For example, hovering over a type shows its declared methods,
plus any methods promoted from embedded fields.
@@ -132,8 +132,8 @@
- the `switch` and `break` tokens of the same switch statement;
- the `func` keyword of a function and all of its `return` statements.
-More than one of these rules may be activated by the same selection,
-for example, an identifier that is also a return operand.
+More than one of these rules may be activated by a single selection,
+for example, by an identifier that is also a return operand.
<img src='../assets/document-highlight.png'>
@@ -155,7 +155,7 @@
Examples:
-- In a function call `f(1, 2)`, gopls will provide hints for the
+- In a function call `f(1, 2)`, hints provide the
names of the parameters (`parameterNames`), as in the screenshot above.
- In a call to a generic function, hints provide the type arguments
(`functionTypeParameters`).
@@ -172,10 +172,12 @@
See [Inlay hints](../inlayHints.md) for a complete list with examples.
+<!--
TODO: Do we really need that separate doc? We could put all the
information here with much less fuss. It changes so rarely that a
culture of "update the tests and docs in every CL" should be sufficient.
IIUC, VS Code needs only the api-json representation.
+-->
Settings:
- The [`hints`](../settings.md#hints) setting indicates the desired set of hints.
@@ -202,7 +204,7 @@
The client may use this information to provide syntax highlighting
that conveys semantic distinctions between, for example, functions and
types, constants and variables, or library functions and built-ins.
-The client specifies the sets of types and modifiers they are interested in.
+The client specifies the sets of types and modifiers it is interested in.
Settings:
- The [`semanticTokens`](../settings.md#semanticTokens) setting determines whether
@@ -249,7 +251,7 @@
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
-literals in the current file so that client can present them as
+literals in the current file so that the client can present them as
clickable links.
<img src='../assets/documentlink.png'>
diff --git a/gopls/doc/features/transformation.md b/gopls/doc/features/transformation.md
index 14de653..c65a7ec 100644
--- a/gopls/doc/features/transformation.md
+++ b/gopls/doc/features/transformation.md
@@ -3,7 +3,7 @@
This document describes gopls' features for code transformation, which
include a range of behavior-preserving changes (refactorings,
formatting, simplifications), code repair (fixes), and editing support
-(filling in struct literals, switch statements).
+(filling in struct literals and switch statements).
Code transformations are not a single category in the LSP:
- a few, such as Formatting and Rename, are primary operations in the
@@ -24,7 +24,7 @@
"[Quick fixes + Refactorings](https://code.visualstudio.com/docs/editor/refactoring#_code-actions-quick-fixes-and-refactorings)".
A `codeAction` request delivers the menu, so to speak, but it does
-not order the meal. When an action is chosen, one of two things happens.
+not order the meal. Once the user chooses an action, one of two things happens.
In trivial cases, the action itself contains an edit that the
client can directly apply to the file.
But in most cases, the action contains a [command](../commands.md)
@@ -36,24 +36,33 @@
[`workspace/applyEdit`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_applyEdit)
request to patch the files.
Not all code actions' commands have an `applyEdit` side effect: some
-may change the state of the server, for example, to toggle a
-variable, or cause the server to send other requests to the client,
-such as as a `showDocument` request to open a report in a web browser.
+may change the state of the server, for example to toggle a variable
+or to cause the server to send other requests to the client,
+such as a `showDocument` request to open a report in a web browser.
The main difference between code lenses and code actions is this:
-- `codeLens` requests commands for the entire file.
+- a `codeLens` request obtains commands for the entire file.
Each command specifies its applicable source range,
and typically appears as an annotation on that source range.
-- `codeAction` requests commands only for a particular range: the current selection.
+- a `codeAction` request obtains commands only for a particular range: the current selection.
All the commands are presented together in a menu at that location.
Each action has a _kind_,
which is a hierarchical identifier such as `refactor.inline`.
Clients may filter actions based on their kind.
-For example, VS Code has two menus, "Refactor..." and "Source action...",
-each populated by different kinds of code actions (`refactor.*` and `source.*`),
-plus a lightbulb icon that triggers a menu of "quick fixes" (of kind `quickfix.*`),
-which are commands deemed unambiguously safe to apply.
+For example, VS Code has:
+two menus, "Refactor..." and "Source action...", each populated by
+different kinds of code actions (`refactor.*` and `source.*`);
+a lightbulb icon that triggers a menu of "quick fixes" (of kind `quickfix.*`);
+and a "Fix All" command that executes all code actions of
+kind `source.fixAll`, which are those deemed unambiguously safe to apply.
+
+Gopls reports some code actions twice, with two different kinds, so
+that they appear in multiple UI elements: simplifications,
+for example from `for _ = range m` to `for range m`,
+have kinds `quickfix` and `source.fixAll`,
+so they appear in the "Quick Fix" menu and
+are activated by the "Fix All" command.
<!-- In principle the filter may include the trigger event
e.g. auto (cursor motion) vs. invoked (open a menu)
@@ -71,7 +80,7 @@
Caveats:
- Many of gopls code transformations are limited by Go's syntax tree
- representation, which currently records comments not in the tree,
+ representation, which currently records comments not in the tree
but in a side table; consequently, transformations such as Extract
and Inline are prone to losing comments. This is issue
golang/go#20744, and it is a priority for us to fix in 2024.
@@ -88,6 +97,7 @@
the "Source action..." menu,
the 💡 (light bulb) icon's menu, or
the "Quick fix" (`⌘.`) menu.
+ The "Fix All" command applies all actions of kind `source.fixAll`.
- **Emacs + eglot**: Code actions are invisible.
Use `M-x eglot-code-actions` to select one from those that are
available (if there are multiple) and execute it.
@@ -126,8 +136,8 @@
adding new ones for undefined symbols,
and sorting them into the conventional order.
-The addition of new imports is based on heuristics that depends on
-your workspace and the contents of your GOMODCACHE directory; it may
+The addition of new imports is based on heuristics that depend on
+your workspace and the contents of your GOMODCACHE directory; they may
sometimes make surprising choices.
Many editors automatically organize imports and format the code before
@@ -207,7 +217,7 @@
Renaming should never introduce a compilation error, but it may
introduce dynamic errors. For example, in a method renaming, if there
is no direct conversion of the affected type to the interface type,
-but there is an intermediate conversion to `interface{}` followed by a
+but there is an intermediate conversion to a broader type (such as `any`) followed by a
type assertion to the interface type, then gopls may proceed to rename
the method, causing the type assertion to fail at run time.
Similar problems may arise with packages that use reflection, such as
@@ -275,8 +285,8 @@
If the default name for the new declaration is already in use, gopls
generates a fresh name.
-Extraction is a challenging problem requiring consideration of a
-variety of aspects such as identifier scope and shadowing, control
+Extraction is a challenging problem requiring consideration of
+identifier scope and shadowing, control
flow such as `break`/`continue` in a loop or `return` in a
function, cardinality of variables, and even subtle issues of style.
In each case, the tool will try to update the extracted statements
@@ -314,9 +324,9 @@
"Extract declarations to new file" code action that moves the selected
declarations into a new file whose name is based on the first declared
symbol.
+Import declarations are created as needed.
Gopls also offers this code action when the selection is just the
first token of the declaration, such as `func` or `type`.
-Import declarations are created as needed.
@@ -414,7 +424,7 @@
code, the compiler is improved to recognize more cases, or more rules,
and more exceptions to rules---but this process has no end.
Inlining is similar, except that "better" code means tidier code.
-The most conservative translation provides a simple but (hopefully!)
+The most conservative translation provides a simple but (hopefully)
correct foundation, on top of which endless rules, and exceptions to
rules, can embellish and improve the quality of the output.
@@ -447,7 +457,7 @@
its argument expression, we must ensure that any names in the
argument expression continue to refer to the same thing---not to a
different declaration in the callee function body that happens to
- use the same name! The inliner must replace local references such as
+ use the same name. The inliner must replace local references such as
`Printf` by qualified references such as `fmt.Printf`, and add an
import of package `fmt` as needed.
@@ -468,7 +478,7 @@
and its corresponding parameter is never used, the expression
may be eliminated. However, if the expression contains the last
reference to a local variable at the caller, this may cause a compile
- error because the variable is now unused! So the inliner must be
+ error because the variable is now unused. So the inliner must be
cautious about eliminating references to local variables.
This is just a taste of the problem domain. If you're curious, the
@@ -524,12 +534,12 @@
When the selection is a string literal, gopls offers a code action
to convert the string between raw form (`` `abc` ``) and interpreted
-form (`"abc"`):
+form (`"abc"`) where this is possible:
-Apply the code action a second time to revert back to the original
+Applying the code action a second time reverts back to the original
form.
### Invert 'if' condition
@@ -549,7 +559,7 @@
### Split elements into separate lines
-When the selection is within a bracketed list such as:
+When the selection is within a bracketed list of items such as:
- the **elements** of a composite literal, `[]T{a, b, c}`,
- the **arguments** of a function call, `f(a, b, c)`,
