gopls/doc: split codelenses out of settings
This CL splits codelenses.md out of settings.md, since
they aren't settings.
This reduces the indentation level of settings by one,
since we can dispense with a heading. Also, don't increase
the <h%d> nesting level for each level of nested dotted options:
ui.foo.bar should not be rendered smaller than ui.foo.
Use only h2 for groupings and h3 for settings.
Also:
- improve the introduction.
- add anchors for groupings.
- delete handwritten .md doc for obsolete newDiff setting.
- add TODOs for some existing bugs in the generator.
Change-Id: If6e7fff028b2c372e0d766d3d092bd0e41d61486
Reviewed-on: https://go-review.googlesource.com/c/tools/+/586879
Reviewed-by: Robert Findley <rfindley@google.com>
Auto-Submit: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
diff --git a/gopls/doc/advanced.md b/gopls/doc/advanced.md
index 1f70143..7159626 100644
--- a/gopls/doc/advanced.md
+++ b/gopls/doc/advanced.md
@@ -74,7 +74,7 @@
### Known issues
- * [`staticcheck`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#staticcheck-bool)
+ * [`staticcheck`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#staticcheck)
on generic code is not supported yet.
[Go project]: https://go.googlesource.com/go
diff --git a/gopls/doc/codelenses.md b/gopls/doc/codelenses.md
new file mode 100644
index 0000000..378a3db
--- /dev/null
+++ b/gopls/doc/codelenses.md
@@ -0,0 +1,153 @@
+# Code Lenses
+
+A "code lens" is a command associated with a range of a source file.
+The VS Code manual describes code lenses as
+"[actionable, contextual information, interspersed in your source
+code](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup)".
+The LSP [`textDocument/codeLens`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_codeLens) operation requests the
+current set of code lenses for a file.
+
+Gopls generates code lenses from a number of sources.
+This document describes them.
+
+They can be enabled and disabled using the
+[`codelenses`](settings.md#codelenses) setting.
+Their features are subject to change.
+
+<!-- This portion is generated by doc/generate from the ../internal/settings package. -->
+<!-- BEGIN Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
+## ⬤ `gc_details`: Toggle display of Go compiler optimization decisions
+
+
+This codelens source causes the `package` declaration of
+each file to be annotated with a command to toggle the
+state of the per-session variable that controls whether
+optimization decisions from the Go compiler (formerly known
+as "gc") should be displayed as diagnostics.
+
+Optimization decisions include:
+- whether a variable escapes, and how escape is inferred;
+- whether a nil-pointer check is implied or eliminated;
+- whether a function can be inlined.
+
+TODO(adonovan): this source is off by default because the
+annotation is annoying and because VS Code has a separate
+"Toggle gc details" command. Replace it with a Code Action
+("Source action...").
+
+
+Default: off
+
+File type: Go
+
+## ⬤ `generate`: Run `go generate`
+
+
+This codelens source annotates any `//go:generate` comments
+with commands to run `go generate` in this directory, on
+all directories recursively beneath this one.
+
+See [Generating code](https://go.dev/blog/generate) for
+more details.
+
+
+Default: on
+
+File type: Go
+
+## ⬤ `regenerate_cgo`: Re-generate cgo declarations
+
+
+This codelens source annotates an `import "C"` declaration
+with a command to re-run the [cgo
+command](https://pkg.go.dev/cmd/cgo) to regenerate the
+corresponding Go declarations.
+
+Use this after editing the C code in comments attached to
+the import, or in C header files included by it.
+
+
+Default: on
+
+File type: Go
+
+## ⬤ `test`: Run tests and benchmarks
+
+
+This codelens source annotates each `Test` and `Benchmark`
+function in a `*_test.go` file with a command to run it.
+
+This source is off by default because VS Code has
+a client-side custom UI for testing, and because progress
+notifications are not a great UX for streamed test output.
+See:
+- golang/go#67400 for a discussion of this feature.
+- https://github.com/joaotavora/eglot/discussions/1402
+ for an alternative approach.
+
+
+Default: off
+
+File type: Go
+
+## ⬤ `run_govulncheck`: Run govulncheck
+
+
+This codelens source annotates the `module` directive in a
+go.mod file with a command to run Govulncheck.
+
+[Govulncheck](https://go.dev/blog/vuln) is a static
+analysis tool that computes the set of functions reachable
+within your application, including dependencies;
+queries a database of known security vulnerabilities; and
+reports any potential problems it finds.
+
+
+Default: off
+
+File type: go.mod
+
+## ⬤ `tidy`: Tidy go.mod file
+
+
+This codelens source annotates the `module` directive in a
+go.mod file with a command to run [`go mod
+tidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures
+that the go.mod file matches the source code in the module.
+
+
+Default: on
+
+File type: go.mod
+
+## ⬤ `upgrade_dependency`: Update dependencies
+
+
+This codelens source annotates the `module` directive in a
+go.mod file with commands to:
+
+- check for available upgrades,
+- upgrade direct dependencies, and
+- upgrade all dependencies transitively.
+
+
+Default: on
+
+File type: go.mod
+
+## ⬤ `vendor`: Update vendor directory
+
+
+This codelens source annotates the `module` directive in a
+go.mod file with a command to run [`go mod
+vendor`](https://go.dev/ref/mod#go-mod-vendor), which
+creates or updates the directory named `vendor` in the
+module root so that it contains an up-to-date copy of all
+necessary package dependencies.
+
+
+Default: on
+
+File type: go.mod
+
+<!-- END Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
diff --git a/gopls/doc/features.md b/gopls/doc/features.md
index dce6719..70a734e 100644
--- a/gopls/doc/features.md
+++ b/gopls/doc/features.md
@@ -27,7 +27,7 @@
are parsed by `text/template` or `html/template`.
Gopls recognizes template files based on their file extension, which may be
configured by the
-[`templateExtensions`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#templateextensions-string) setting.
+[`templateExtensions`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#templateextensions) setting.
Making this list empty turns off template support.
In template files, template support works inside
diff --git a/gopls/doc/generate/generate.go b/gopls/doc/generate/generate.go
index ba3d497..f49a787 100644
--- a/gopls/doc/generate/generate.go
+++ b/gopls/doc/generate/generate.go
@@ -87,6 +87,7 @@
}{
{"internal/doc/api.json", rewriteAPI},
{"doc/settings.md", rewriteSettings},
+ {"doc/codelenses.md", rewriteCodeLenses},
{"doc/commands.md", rewriteCommands},
{"doc/analyzers.md", rewriteAnalyzers},
{"doc/inlayHints.md", rewriteInlayHints},
@@ -660,7 +661,7 @@
type optionsGroup struct {
title string // dotted path (e.g. "ui.documentation")
- final string // finals segment of title (e.g. "documentation")
+ final string // final segment of title (e.g. "documentation")
level int
options []*doc.Option
}
@@ -684,17 +685,18 @@
}
}
- // Currently, the settings document has a title and a subtitle, so
- // start at level 3 for a header beginning with "###".
+ // Section titles are h2, options are h3.
+ // This is independent of the option hierarchy.
+ // (Nested options should not be smaller!)
fmt.Fprintln(&buf)
- baseLevel := 3
for _, h := range groups {
- level := baseLevel + h.level
title := h.final
if title != "" {
- fmt.Fprintf(&buf, "%s %s\n\n",
- strings.Repeat("#", level),
- capitalize(title))
+ // Emit HTML anchor as GitHub markdown doesn't support
+ // "# Heading {#anchor}" syntax.
+ fmt.Fprintf(&buf, "<a id='%s'></a>\n", strings.ToLower(title))
+
+ fmt.Fprintf(&buf, "## %s\n\n", capitalize(title))
}
for _, opt := range h.options {
// Emit HTML anchor as GitHub markdown doesn't support
@@ -707,10 +709,18 @@
// heading
// (The blob helps the reader see the start of each item,
// which is otherwise hard to discern in GitHub markdown.)
- fmt.Fprintf(&buf, "%s ⬤ **%v** *%v*\n\n",
- strings.Repeat("#", level+1),
- opt.Name,
- opt.Type)
+ //
+ // TODO(adonovan): We should display not the Go type (e.g.
+ // `time.Duration`, `map[Enum]bool`) for each setting,
+ // but its JSON type, since that's the actual interface.
+ // We need a better way to derive accurate JSON type descriptions
+ // from Go types. eg. "a string parsed as if by
+ // `time.Duration.Parse`". (`time.Duration` is an integer, not
+ // a string!)
+ //
+ // We do not display the undocumented dotted-path alias
+ // (h.title + "." + opt.Name) used by VS Code only.
+ fmt.Fprintf(&buf, "### ⬤ `%s` *%v*\n\n", opt.Name, opt.Type)
// status
switch opt.Status {
@@ -729,6 +739,10 @@
buf.WriteString(opt.Doc)
// enums
+ //
+ // TODO(adonovan): `CodeLensSource` should be treated as an enum,
+ // but loadEnums considers only the `settings` package,
+ // not `protocol`.
write := func(name, doc string) {
if doc != "" {
unbroken := parBreakRE.ReplaceAllString(doc, "\\\n")
@@ -759,16 +773,7 @@
}
content = newContent
}
-
- // Replace the lenses section.
- var buf bytes.Buffer
- for _, lens := range api.Lenses {
- fmt.Fprintf(&buf, "### ⬤ `%s`: %s\n\n", lens.Lens, lens.Title)
- fmt.Fprintf(&buf, "%s\n\n", lens.Doc)
- fmt.Fprintf(&buf, "Default: %v\n\n", onOff(lens.Default))
- fmt.Fprintf(&buf, "File type: %s\n\n", lens.FileType)
- }
- return replaceSection(content, "Lenses", buf.Bytes())
+ return content, nil
}
var parBreakRE = regexp.MustCompile("\n{2,}")
@@ -840,6 +845,17 @@
return string(unicode.ToUpper(rune(s[0]))) + s[1:]
}
+func rewriteCodeLenses(prevContent []byte, api *doc.API) ([]byte, error) {
+ var buf bytes.Buffer
+ for _, lens := range api.Lenses {
+ fmt.Fprintf(&buf, "## ⬤ `%s`: %s\n\n", lens.Lens, lens.Title)
+ fmt.Fprintf(&buf, "%s\n\n", lens.Doc)
+ fmt.Fprintf(&buf, "Default: %v\n\n", onOff(lens.Default))
+ fmt.Fprintf(&buf, "File type: %s\n\n", lens.FileType)
+ }
+ return replaceSection(prevContent, "Lenses", buf.Bytes())
+}
+
func rewriteCommands(prevContent []byte, api *doc.API) ([]byte, error) {
var buf bytes.Buffer
for _, command := range api.Commands {
diff --git a/gopls/doc/settings.md b/gopls/doc/settings.md
index 00a9188..34bb5b0 100644
--- a/gopls/doc/settings.md
+++ b/gopls/doc/settings.md
@@ -1,29 +1,36 @@
# Settings
-This document describes the global settings for `gopls` inside the editor.
-The settings block will be called `"gopls"` and contains a collection of
-controls for `gopls` that the editor is not expected to understand or control.
-These settings can also be configured differently per workspace folder.
+This document describes gopls' configuration settings.
-In VSCode, this would be a section in your `settings.json` file that might look
-like this:
+Gopls settings are defined by an JSON object whose valid fields are
+described below. These fields are gopls-specific, and generic LSP
+clients have no knowledge of them.
-```json5
- "gopls": {
- "ui.completion.usePlaceholders": true,
- ...
- },
-```
+Different clients present configuration settings in their user
+interfaces in a wide variety of ways.
+For example, some expect the user to edit the raw JSON object while
+others use a data structure in the editor's configuration language;
+still others (such as VS Code) have a graphical configuration system.
+Be sure to consult the documentation for how to express configuration
+settings in your client.
+Some clients also permit settings to be configured differently for
+each workspace folder.
-## Officially supported
+Any settings that are experimental or for debugging purposes are
+marked as such. To enable all experimental features, use
+**allExperiments: `true`**. You will still be able to independently
+override specific experimental features.
-Below is the list of settings that are officially supported for `gopls`.
-
-Any settings that are experimental or for debugging purposes are marked as
-such.
-
-To enable all experimental features, use **allExperiments: `true`**. You will
-still be able to independently override specific experimental features.
+<!--
+All settings are uniquely identified by name such as `semanticTokens`
+or `templateExtensions`.
+However, for convenience of VS Code, each setting also has an
+undocumented alias whose form is a dotted path such as
+`ui.semanticTokens` or `build.templateExtensions`.
+However, only the final segment is actually significant, so
+`build.templateExtensions` is equivalent to `templateExtensions`.
+All clients but VS Code should use the short form.
+-->
<!-- This portion is generated by doc/generate from the ../internal/settings package. -->
<!-- BEGIN User: DO NOT MANUALLY EDIT THIS SECTION -->
@@ -37,10 +44,11 @@
* [Inlayhint](#inlayhint)
* [Navigation](#navigation)
-### Build
+<a id='build'></a>
+## Build
<a id='buildFlags'></a>
-#### ⬤ **buildFlags** *[]string*
+### ⬤ `buildFlags` *[]string*
buildFlags is the set of flags passed on to the build system when invoked.
It is applied to queries like `go list`, which is used when discovering files.
@@ -49,14 +57,14 @@
Default: `[]`.
<a id='env'></a>
-#### ⬤ **env** *map[string]string*
+### ⬤ `env` *map[string]string*
env adds environment variables to external commands run by `gopls`, most notably `go list`.
Default: `{}`.
<a id='directoryFilters'></a>
-#### ⬤ **directoryFilters** *[]string*
+### ⬤ `directoryFilters` *[]string*
directoryFilters can be used to exclude unwanted directories from the
workspace. By default, all directories are included. Filters are an
@@ -80,7 +88,7 @@
Default: `["-**/node_modules"]`.
<a id='templateExtensions'></a>
-#### ⬤ **templateExtensions** *[]string*
+### ⬤ `templateExtensions` *[]string*
templateExtensions gives the extensions of file names that are treateed
as template files. (The extension
@@ -89,7 +97,7 @@
Default: `[]`.
<a id='memoryMode'></a>
-#### ⬤ **memoryMode** *string*
+### ⬤ `memoryMode` *string*
**This setting is experimental and may be deleted.**
@@ -98,7 +106,7 @@
Default: `""`.
<a id='expandWorkspaceToModule'></a>
-#### ⬤ **expandWorkspaceToModule** *bool*
+### ⬤ `expandWorkspaceToModule` *bool*
**This setting is experimental and may be deleted.**
@@ -114,7 +122,7 @@
Default: `true`.
<a id='allowImplicitNetworkAccess'></a>
-#### ⬤ **allowImplicitNetworkAccess** *bool*
+### ⬤ `allowImplicitNetworkAccess` *bool*
**This setting is experimental and may be deleted.**
@@ -125,7 +133,7 @@
Default: `false`.
<a id='standaloneTags'></a>
-#### ⬤ **standaloneTags** *[]string*
+### ⬤ `standaloneTags` *[]string*
standaloneTags specifies a set of build constraints that identify
individual Go source files that make up the entire main package of an
@@ -148,10 +156,11 @@
Default: `["ignore"]`.
-### Formatting
+<a id='formatting'></a>
+## Formatting
<a id='local'></a>
-#### ⬤ **local** *string*
+### ⬤ `local` *string*
local is the equivalent of the `goimports -local` flag, which puts
imports beginning with this string after third-party packages. It should
@@ -161,21 +170,20 @@
Default: `""`.
<a id='gofumpt'></a>
-#### ⬤ **gofumpt** *bool*
+### ⬤ `gofumpt` *bool*
gofumpt indicates if we should run gofumpt formatting.
Default: `false`.
-### UI
+<a id='ui'></a>
+## UI
<a id='codelenses'></a>
-#### ⬤ **codelenses** *map[golang.org/x/tools/gopls/internal/protocol.CodeLensSource]bool*
+### ⬤ `codelenses` *map[golang.org/x/tools/gopls/internal/protocol.CodeLensSource]bool*
-codelenses overrides the enabled/disabled state of code lenses. See the
-"Code Lenses" section of the
-[Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#code-lenses)
-for the list of supported lenses.
+codelenses overrides the enabled/disabled state of each of gopls'
+sources of [Code Lenses](codelenses.md).
Example Usage:
@@ -193,7 +201,7 @@
Default: `{"gc_details":false,"generate":true,"regenerate_cgo":true,"run_govulncheck":false,"tidy":true,"upgrade_dependency":true,"vendor":true}`.
<a id='semanticTokens'></a>
-#### ⬤ **semanticTokens** *bool*
+### ⬤ `semanticTokens` *bool*
**This setting is experimental and may be deleted.**
@@ -204,7 +212,7 @@
Default: `true`.
<a id='noSemanticString'></a>
-#### ⬤ **noSemanticString** *bool*
+### ⬤ `noSemanticString` *bool*
**This setting is experimental and may be deleted.**
@@ -213,7 +221,7 @@
Default: `false`.
<a id='noSemanticNumber'></a>
-#### ⬤ **noSemanticNumber** *bool*
+### ⬤ `noSemanticNumber` *bool*
**This setting is experimental and may be deleted.**
@@ -221,10 +229,11 @@
Default: `false`.
-#### Completion
+<a id='completion'></a>
+## Completion
<a id='usePlaceholders'></a>
-##### ⬤ **usePlaceholders** *bool*
+### ⬤ `usePlaceholders` *bool*
placeholders enables placeholders for function parameters or struct
fields in completion responses.
@@ -232,7 +241,7 @@
Default: `false`.
<a id='completionBudget'></a>
-##### ⬤ **completionBudget** *time.Duration*
+### ⬤ `completionBudget` *time.Duration*
**This setting is for debugging purposes only.**
@@ -245,7 +254,7 @@
Default: `"100ms"`.
<a id='matcher'></a>
-##### ⬤ **matcher** *enum*
+### ⬤ `matcher` *enum*
**This is an advanced setting and should not be configured by most `gopls` users.**
@@ -261,7 +270,7 @@
Default: `"Fuzzy"`.
<a id='experimentalPostfixCompletions'></a>
-##### ⬤ **experimentalPostfixCompletions** *bool*
+### ⬤ `experimentalPostfixCompletions` *bool*
**This setting is experimental and may be deleted.**
@@ -271,7 +280,7 @@
Default: `true`.
<a id='completeFunctionCalls'></a>
-##### ⬤ **completeFunctionCalls** *bool*
+### ⬤ `completeFunctionCalls` *bool*
completeFunctionCalls enables function call completion.
@@ -281,10 +290,11 @@
Default: `true`.
-#### Diagnostic
+<a id='diagnostic'></a>
+## Diagnostic
<a id='analyses'></a>
-##### ⬤ **analyses** *map[string]bool*
+### ⬤ `analyses` *map[string]bool*
analyses specify analyses that the user would like to enable or disable.
A map of the names of analysis passes that should be enabled/disabled.
@@ -305,7 +315,7 @@
Default: `{}`.
<a id='staticcheck'></a>
-##### ⬤ **staticcheck** *bool*
+### ⬤ `staticcheck` *bool*
**This setting is experimental and may be deleted.**
@@ -316,7 +326,7 @@
Default: `false`.
<a id='annotations'></a>
-##### ⬤ **annotations** *map[string]bool*
+### ⬤ `annotations` *map[string]bool*
**This setting is experimental and may be deleted.**
@@ -333,7 +343,7 @@
Default: `{"bounds":true,"escape":true,"inline":true,"nil":true}`.
<a id='vulncheck'></a>
-##### ⬤ **vulncheck** *enum*
+### ⬤ `vulncheck` *enum*
**This setting is experimental and may be deleted.**
@@ -348,7 +358,7 @@
Default: `"Off"`.
<a id='diagnosticsDelay'></a>
-##### ⬤ **diagnosticsDelay** *time.Duration*
+### ⬤ `diagnosticsDelay` *time.Duration*
**This is an advanced setting and should not be configured by most `gopls` users.**
@@ -362,7 +372,7 @@
Default: `"1s"`.
<a id='diagnosticsTrigger'></a>
-##### ⬤ **diagnosticsTrigger** *enum*
+### ⬤ `diagnosticsTrigger` *enum*
**This setting is experimental and may be deleted.**
@@ -377,7 +387,7 @@
Default: `"Edit"`.
<a id='analysisProgressReporting'></a>
-##### ⬤ **analysisProgressReporting** *bool*
+### ⬤ `analysisProgressReporting` *bool*
analysisProgressReporting controls whether gopls sends progress
notifications when construction of its index of analysis facts is taking a
@@ -391,10 +401,11 @@
Default: `true`.
-#### Documentation
+<a id='documentation'></a>
+## Documentation
<a id='hoverKind'></a>
-##### ⬤ **hoverKind** *enum*
+### ⬤ `hoverKind` *enum*
hoverKind controls the information that appears in the hover text.
SingleLine and Structured are intended for use only by authors of editor plugins.
@@ -413,7 +424,7 @@
Default: `"FullDocumentation"`.
<a id='linkTarget'></a>
-##### ⬤ **linkTarget** *string*
+### ⬤ `linkTarget` *string*
linkTarget controls where documentation links go.
It might be one of:
@@ -429,16 +440,17 @@
Default: `"pkg.go.dev"`.
<a id='linksInHover'></a>
-##### ⬤ **linksInHover** *bool*
+### ⬤ `linksInHover` *bool*
linksInHover toggles the presence of links to documentation in hover.
Default: `true`.
-#### Inlayhint
+<a id='inlayhint'></a>
+## Inlayhint
<a id='hints'></a>
-##### ⬤ **hints** *map[string]bool*
+### ⬤ `hints` *map[string]bool*
**This setting is experimental and may be deleted.**
@@ -448,10 +460,11 @@
Default: `{}`.
-#### Navigation
+<a id='navigation'></a>
+## Navigation
<a id='importShortcut'></a>
-##### ⬤ **importShortcut** *enum*
+### ⬤ `importShortcut` *enum*
importShortcut specifies whether import statements should link to
documentation or go to definitions.
@@ -465,7 +478,7 @@
Default: `"Both"`.
<a id='symbolMatcher'></a>
-##### ⬤ **symbolMatcher** *enum*
+### ⬤ `symbolMatcher` *enum*
**This is an advanced setting and should not be configured by most `gopls` users.**
@@ -481,7 +494,7 @@
Default: `"FastFuzzy"`.
<a id='symbolStyle'></a>
-##### ⬤ **symbolStyle** *enum*
+### ⬤ `symbolStyle` *enum*
**This is an advanced setting and should not be configured by most `gopls` users.**
@@ -511,7 +524,7 @@
Default: `"Dynamic"`.
<a id='symbolScope'></a>
-##### ⬤ **symbolScope** *enum*
+### ⬤ `symbolScope` *enum*
symbolScope controls which packages are searched for workspace/symbol
requests. When the scope is "workspace", gopls searches only workspace
@@ -527,7 +540,7 @@
Default: `"all"`.
<a id='verboseOutput'></a>
-#### ⬤ **verboseOutput** *bool*
+### ⬤ `verboseOutput` *bool*
**This setting is for debugging purposes only.**
@@ -536,163 +549,3 @@
Default: `false`.
<!-- END User: DO NOT MANUALLY EDIT THIS SECTION -->
-
-#### **newDiff** *string*
-
-newDiff enables the new diff implementation. If this is "both", for now both
-diffs will be run and statistics will be generated in a file in $TMPDIR. This
-is a risky setting; help in trying it is appreciated. If it is "old" the old
-implementation is used, and if it is "new", just the new implementation is
-used. This setting will eventually be deleted, once gopls has fully migrated to
-the new diff algorithm.
-
-Default: 'both'.
-
-## Code Lenses
-
-A "code lens" is a command associated with a range of a source file.
-(They are so named because VS Code displays them with a magnifying
-glass icon in the margin.) The VS Code manual describes code lenses as
-"[actionable, contextual information, interspersed in your source
-code](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup)".
-The LSP `CodeLens` operation requests the
-current set of code lenses for a file.
-
-Gopls generates code lenses from a number of sources.
-They are described below.
-
-They can be enabled and disabled using the `codelenses` setting,
-documented above. Their names and features are subject to change.
-
-<!-- BEGIN Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
-### ⬤ `gc_details`: Toggle display of Go compiler optimization decisions
-
-
-This codelens source causes the `package` declaration of
-each file to be annotated with a command to toggle the
-state of the per-session variable that controls whether
-optimization decisions from the Go compiler (formerly known
-as "gc") should be displayed as diagnostics.
-
-Optimization decisions include:
-- whether a variable escapes, and how escape is inferred;
-- whether a nil-pointer check is implied or eliminated;
-- whether a function can be inlined.
-
-TODO(adonovan): this source is off by default because the
-annotation is annoying and because VS Code has a separate
-"Toggle gc details" command. Replace it with a Code Action
-("Source action...").
-
-
-Default: off
-
-File type: Go
-
-### ⬤ `generate`: Run `go generate`
-
-
-This codelens source annotates any `//go:generate` comments
-with commands to run `go generate` in this directory, on
-all directories recursively beneath this one.
-
-See [Generating code](https://go.dev/blog/generate) for
-more details.
-
-
-Default: on
-
-File type: Go
-
-### ⬤ `regenerate_cgo`: Re-generate cgo declarations
-
-
-This codelens source annotates an `import "C"` declaration
-with a command to re-run the [cgo
-command](https://pkg.go.dev/cmd/cgo) to regenerate the
-corresponding Go declarations.
-
-Use this after editing the C code in comments attached to
-the import, or in C header files included by it.
-
-
-Default: on
-
-File type: Go
-
-### ⬤ `test`: Run tests and benchmarks
-
-
-This codelens source annotates each `Test` and `Benchmark`
-function in a `*_test.go` file with a command to run it.
-
-This source is off by default because VS Code has
-a more sophisticated client-side Test Explorer.
-See golang/go#67400 for a discussion of this feature.
-
-
-Default: off
-
-File type: Go
-
-### ⬤ `run_govulncheck`: Run govulncheck
-
-
-This codelens source annotates the `module` directive in a
-go.mod file with a command to run Govulncheck.
-
-[Govulncheck](https://go.dev/blog/vuln) is a static
-analysis tool that computes the set of functions reachable
-within your application, including dependencies;
-queries a database of known security vulnerabilities; and
-reports any potential problems it finds.
-
-
-Default: off
-
-File type: go.mod
-
-### ⬤ `tidy`: Tidy go.mod file
-
-
-This codelens source annotates the `module` directive in a
-go.mod file with a command to run [`go mod
-tidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures
-that the go.mod file matches the source code in the module.
-
-
-Default: on
-
-File type: go.mod
-
-### ⬤ `upgrade_dependency`: Update dependencies
-
-
-This codelens source annotates the `module` directive in a
-go.mod file with commands to:
-
-- check for available upgrades,
-- upgrade direct dependencies, and
-- upgrade all dependencies transitively.
-
-
-Default: on
-
-File type: go.mod
-
-### ⬤ `vendor`: Update vendor directory
-
-
-This codelens source annotates the `module` directive in a
-go.mod file with a command to run [`go mod
-vendor`](https://go.dev/ref/mod#go-mod-vendor), which
-creates or updates the directory named `vendor` in the
-module root so that it contains an up-to-date copy of all
-necessary package dependencies.
-
-
-Default: on
-
-File type: go.mod
-
-<!-- END Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
diff --git a/gopls/doc/workspace.md b/gopls/doc/workspace.md
index cb26b3d..94f83fb 100644
--- a/gopls/doc/workspace.md
+++ b/gopls/doc/workspace.md
@@ -121,9 +121,9 @@
However, per the caveats listed in that section, this automatic behavior comes
with limitations. Customize your gopls environment by setting `GOOS` or
`GOARCH` in your
-[`"build.env"`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#env-mapstringstring)
+[`"build.env"`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#env)
or `-tags=...` in your"
-["build.buildFlags"](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#buildflags-string)
+["build.buildFlags"](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#buildflags)
when:
- You want to modify the default build environment.
diff --git a/gopls/internal/cache/snapshot.go b/gopls/internal/cache/snapshot.go
index dd868dc..1e8db10 100644
--- a/gopls/internal/cache/snapshot.go
+++ b/gopls/internal/cache/snapshot.go
@@ -1523,7 +1523,7 @@
if hasConstraint {
fix = `This file may be excluded due to its build tags; try adding "-tags=<build tag>" to your gopls "buildFlags" configuration
See the documentation for more information on working with build tags:
-https://github.com/golang/tools/blob/master/gopls/doc/settings.md#buildflags-string.`
+https://github.com/golang/tools/blob/master/gopls/doc/settings.md#buildflags.`
} else if strings.Contains(filepath.Base(fh.URI().Path()), "_") {
fix = `This file may be excluded due to its GOOS/GOARCH, or other build constraints.`
} else {
diff --git a/gopls/internal/doc/api.json b/gopls/internal/doc/api.json
index 143d4e3..a06bc44 100644
--- a/gopls/internal/doc/api.json
+++ b/gopls/internal/doc/api.json
@@ -800,7 +800,7 @@
{
"Name": "codelenses",
"Type": "map[golang.org/x/tools/gopls/internal/protocol.CodeLensSource]bool",
- "Doc": "codelenses overrides the enabled/disabled state of code lenses. See the\n\"Code Lenses\" section of the\n[Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#code-lenses)\nfor the list of supported lenses.\n\nExample Usage:\n\n```json5\n\"gopls\": {\n...\n \"codelenses\": {\n \"generate\": false, // Don't show the `go generate` lens.\n \"gc_details\": true // Show a code lens toggling the display of gc's choices.\n }\n...\n}\n```\n",
+ "Doc": "codelenses overrides the enabled/disabled state of each of gopls'\nsources of [Code Lenses](codelenses.md).\n\nExample Usage:\n\n```json5\n\"gopls\": {\n...\n \"codelenses\": {\n \"generate\": false, // Don't show the `go generate` lens.\n \"gc_details\": true // Show a code lens toggling the display of gc's choices.\n }\n...\n}\n```\n",
"EnumKeys": {
"ValueType": "bool",
"Keys": [
@@ -821,7 +821,7 @@
},
{
"Name": "\"test\"",
- "Doc": "\nThis codelens source annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis source is off by default because VS Code has\na more sophisticated client-side Test Explorer.\nSee golang/go#67400 for a discussion of this feature.\n",
+ "Doc": "\nThis codelens source annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis source is off by default because VS Code has\na client-side custom UI for testing, and because progress\nnotifications are not a great UX for streamed test output.\nSee:\n- golang/go#67400 for a discussion of this feature.\n- https://github.com/joaotavora/eglot/discussions/1402\n for an alternative approach.\n",
"Default": "false"
},
{
@@ -1204,7 +1204,7 @@
"FileType": "Go",
"Lens": "test",
"Title": "Run tests and benchmarks",
- "Doc": "\nThis codelens source annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis source is off by default because VS Code has\na more sophisticated client-side Test Explorer.\nSee golang/go#67400 for a discussion of this feature.\n",
+ "Doc": "\nThis codelens source annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis source is off by default because VS Code has\na client-side custom UI for testing, and because progress\nnotifications are not a great UX for streamed test output.\nSee:\n- golang/go#67400 for a discussion of this feature.\n- https://github.com/joaotavora/eglot/discussions/1402\n for an alternative approach.\n",
"Default": false
},
{
diff --git a/gopls/internal/protocol/codeactionkind.go b/gopls/internal/protocol/codeactionkind.go
index 6359cc7..268b25a 100644
--- a/gopls/internal/protocol/codeactionkind.go
+++ b/gopls/internal/protocol/codeactionkind.go
@@ -100,8 +100,12 @@
// function in a `*_test.go` file with a command to run it.
//
// This source is off by default because VS Code has
- // a more sophisticated client-side Test Explorer.
- // See golang/go#67400 for a discussion of this feature.
+ // a client-side custom UI for testing, and because progress
+ // notifications are not a great UX for streamed test output.
+ // See:
+ // - golang/go#67400 for a discussion of this feature.
+ // - https://github.com/joaotavora/eglot/discussions/1402
+ // for an alternative approach.
CodeLensTest CodeLensSource = "test"
// Tidy go.mod file
diff --git a/gopls/internal/settings/settings.go b/gopls/internal/settings/settings.go
index 9a800ed..d62c3c7 100644
--- a/gopls/internal/settings/settings.go
+++ b/gopls/internal/settings/settings.go
@@ -168,10 +168,8 @@
DiagnosticOptions
InlayHintOptions
- // Codelenses overrides the enabled/disabled state of code lenses. See the
- // "Code Lenses" section of the
- // [Settings page](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#code-lenses)
- // for the list of supported lenses.
+ // Codelenses overrides the enabled/disabled state of each of gopls'
+ // sources of [Code Lenses](codelenses.md).
//
// Example Usage:
//
@@ -722,7 +720,11 @@
}
func (o *Options) set(name string, value any, seen map[string]struct{}) OptionResult {
- // Flatten the name in case we get options with a hierarchy.
+ // Use only the last segment of a dotted name such as
+ // ui.navigation.symbolMatcher. The other segments
+ // are discarded, even without validation (!).
+ // (They are supported to enable hierarchical names
+ // in the VS Code graphical configuration UI.)
split := strings.Split(name, ".")
name = split[len(split)-1]
