[tools] gopls/internal/protocol: tease CodeLens and Command apart

1 view

Skip to first unread message

Gopher Robot (Gerrit)

unread,

May 17, 2024, 5:14:42 PMMay 17

to Alan Donovan, goph...@pubsubhelper.golang.org, golang-...@googlegroups.com, Go LUCI, Robert Findley, golang-co...@googlegroups.com

Gopher Robot submitted the change with unreviewed changes

Unreviewed changes

8 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:

```
The name of the file: gopls/internal/cache/snapshot.go
Insertions: 2, Deletions: 2.

@@ -2285,6 +2285,6 @@
 	return ok
 }
 
-// A LensFunc is a function that reports CodeLenses (range-associated
+// A CodeLensSourceFunc is a function that reports CodeLenses (range-associated
 // commands) for a given file.
-type LensFunc func(context.Context, *Snapshot, file.Handle) ([]protocol.CodeLens, error)
+type CodeLensSourceFunc func(context.Context, *Snapshot, file.Handle) ([]protocol.CodeLens, error)
```
```
The name of the file: gopls/internal/mod/code_lens.go
Insertions: 3, Deletions: 3.

@@ -17,9 +17,9 @@
 	"golang.org/x/tools/gopls/internal/protocol/command"
 )
 
-// LensFuncs returns the supported LensFuncs for go.mod files.
-func LensFuncs() map[protocol.CodeLensKind]cache.LensFunc {
-	return map[protocol.CodeLensKind]cache.LensFunc{
+// CodeLensSources returns the sources of code lenses for go.mod files.
+func CodeLensSources() map[protocol.CodeLensSource]cache.CodeLensSourceFunc {
+	return map[protocol.CodeLensSource]cache.CodeLensSourceFunc{
 		protocol.CodeLensUpgradeDependency: upgradeLenses,   // commands: CheckUpgrades, UpgradeDependency
 		protocol.CodeLensTidy:              tidyLens,        // commands: Tidy
 		protocol.CodeLensVendor:            vendorLens,      // commands: Vendor
```
```
The name of the file: gopls/internal/settings/default.go
Insertions: 1, Deletions: 1.

@@ -99,7 +99,7 @@
 						ExperimentalPostfixCompletions: true,
 						CompleteFunctionCalls:          true,
 					},
-					Codelenses: map[protocol.CodeLensKind]bool{
+					Codelenses: map[protocol.CodeLensSource]bool{
 						protocol.CodeLensGenerate:          true,
 						protocol.CodeLensRegenerateCgo:     true,
 						protocol.CodeLensTidy:              true,
```
```
The name of the file: gopls/internal/server/code_lens.go
Insertions: 3, Deletions: 3.

@@ -30,12 +30,12 @@
 	}
 	defer release()
 
-	var lensFuncs map[protocol.CodeLensKind]cache.LensFunc
+	var lensFuncs map[protocol.CodeLensSource]cache.CodeLensSourceFunc
 	switch snapshot.FileKind(fh) {
 	case file.Mod:
-		lensFuncs = mod.LensFuncs()
+		lensFuncs = mod.CodeLensSources()
 	case file.Go:
-		lensFuncs = golang.LensFuncs()
+		lensFuncs = golang.CodeLensSources()
 	default:
 		// Unsupported file kind for a code lens.
 		return nil, nil
```
```
The name of the file: gopls/internal/golang/code_lens.go
Insertions: 7, Deletions: 7.

@@ -19,13 +19,13 @@
 	"golang.org/x/tools/gopls/internal/protocol/command"
 )
 
-// LensFuncs returns the supported lensFuncs for Go files.
-func LensFuncs() map[protocol.CodeLensKind]cache.LensFunc {
-	return map[protocol.CodeLensKind]cache.LensFunc{
-		protocol.CodeLensGenerate:      goGenerateCodeLens,
-		protocol.CodeLensTest:          runTestCodeLens,
-		protocol.CodeLensRegenerateCgo: regenerateCgoLens,
-		protocol.CodeLensGCDetails:     toggleDetailsCodeLens,
+// CodeLensSources returns the supported sources of code lenses for Go files.
+func CodeLensSources() map[protocol.CodeLensSource]cache.CodeLensSourceFunc {
+	return map[protocol.CodeLensSource]cache.CodeLensSourceFunc{
+		protocol.CodeLensGenerate:      goGenerateCodeLens,    // commands: Generate
+		protocol.CodeLensTest:          runTestCodeLens,       // commands: Test
+		protocol.CodeLensRegenerateCgo: regenerateCgoLens,     // commands: RegenerateCgo
+		protocol.CodeLensGCDetails:     toggleDetailsCodeLens, // commands: GCDetails
 	}
 }
 
```
```
The name of the file: gopls/internal/protocol/codeactionkind.go
Insertions: 35, Deletions: 34.

@@ -25,9 +25,10 @@
 	GoDoc  CodeActionKind = "source.doc"
 )
 
-type CodeLensKind string
+// A CodeLensSource identifies an (algorithmic) source of code lenses.
+type CodeLensSource string
 
-// CodeLens kinds
+// CodeLens sources
 //
 // These identifiers appear in the "codelenses" configuration setting,
 // and in the user documentation thereof, which is generated by
@@ -36,97 +37,97 @@
 // Doc comments should use GitHub Markdown.
 // The first line becomes the title.
 //
-// (For historical reasons, each code lens identifier typically
-// matches the name of one of the command.Commands returned by the
-// code lens, but that isn't essential.)
+// (For historical reasons, each code lens source identifier typically
+// matches the name of one of the command.Commands returned by it,
+// but that isn't essential.)
 const (
 	// Toggle display of Go compiler optimization decisions
 	//
-	// This codelens 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.
+	// 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 lens is off by default because the
+	// 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...").
-	CodeLensGCDetails CodeLensKind = "gc_details"
+	CodeLensGCDetails CodeLensSource = "gc_details"
 
 	// Run `go generate`
 	//
-	// This codelens annotates any `//go:generate` comments with
-	// commands to run `go generate` in this directory,
-	// on all directories recursively beneath this one.
+	// 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.
-	CodeLensGenerate CodeLensKind = "generate"
+	CodeLensGenerate CodeLensSource = "generate"
 
 	// Re-generate cgo declarations
 	//
-	// This codelens annotates an `import "C"` declaration with a
-	// command to re-run the [cgo
+	// 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.
-	CodeLensRegenerateCgo CodeLensKind = "regenerate_cgo"
+	CodeLensRegenerateCgo CodeLensSource = "regenerate_cgo"
 
 	// Run govulncheck
 	//
-	// This codelens annotates the `module` directive in a go.mod
-	// file with a command to 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.
-	CodeLensRunGovulncheck CodeLensKind = "run_govulncheck"
+	CodeLensRunGovulncheck CodeLensSource = "run_govulncheck"
 
 	// Run tests and benchmarks
 	//
-	// This codelens annotates each `Test` and `Benchmark`
+	// This codelens source annotates each `Test` and `Benchmark`
 	// function in a `*_test.go` file with a command to run it.
 	//
-	// This codelens is off by default because VS Code has
+	// 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.
-	CodeLensTest CodeLensKind = "test"
+	CodeLensTest CodeLensSource = "test"
 
 	// Tidy go.mod file
 	//
-	// This codelens annotates the `module` directive in a go.mod
-	// file with a command to run [`go mod
+	// 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.
-	CodeLensTidy CodeLensKind = "tidy"
+	CodeLensTidy CodeLensSource = "tidy"
 
 	// Update dependencies
 	//
-	// This codelens annotates the `module` directive in a go.mod
-	// file with commands to:
+	// 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.
-	CodeLensUpgradeDependency CodeLensKind = "upgrade_dependency"
+	CodeLensUpgradeDependency CodeLensSource = "upgrade_dependency"
 
 	// Update vendor directory
 	//
-	// This codelens annotates the `module` directive in a go.mod
-	// file with a command to run [`go mod
+	// 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.
-	CodeLensVendor CodeLensKind = "vendor"
+	CodeLensVendor CodeLensSource = "vendor"
 )
```
```
The name of the file: gopls/internal/cmd/codelens.go
Insertions: 1, Deletions: 1.

@@ -78,7 +78,7 @@
 			origOptions(opts)
 		}
 		if opts.Codelenses == nil {
-			opts.Codelenses = make(map[protocol.CodeLensKind]bool)
+			opts.Codelenses = make(map[protocol.CodeLensSource]bool)
 		}
 		opts.Codelenses[protocol.CodeLensTest] = true
 	}
```
```
The name of the file: gopls/doc/generate/generate.go
Insertions: 15, Deletions: 15.

@@ -536,8 +536,8 @@
 // loadLenses combines the syntactic comments from the protocol
 // package with the default values from settings.DefaultOptions(), and
 // returns a list of Code Lens descriptors.
-func loadLenses(protocolPkg *packages.Package, defaults map[protocol.CodeLensKind]bool) ([]*doc.Lens, error) {
-	// Find the CodeLensKind enums among the files of the protocol package.
+func loadLenses(protocolPkg *packages.Package, defaults map[protocol.CodeLensSource]bool) ([]*doc.Lens, error) {
+	// Find the CodeLensSource enums among the files of the protocol package.
 	// Map each enum value to its doc comment.
 	enumDoc := make(map[string]string)
 	for _, f := range protocolPkg.Syntax {
@@ -546,13 +546,13 @@
 				for _, spec := range decl.Specs {
 					spec := spec.(*ast.ValueSpec)
 					posn := safetoken.StartPosition(protocolPkg.Fset, spec.Pos())
-					if id, ok := spec.Type.(*ast.Ident); ok && id.Name == "CodeLensKind" {
+					if id, ok := spec.Type.(*ast.Ident); ok && id.Name == "CodeLensSource" {
 						if len(spec.Names) != 1 || len(spec.Values) != 1 {
-							return nil, fmt.Errorf("%s: declare one CodeLensKind per line", posn)
+							return nil, fmt.Errorf("%s: declare one CodeLensSource per line", posn)
 						}
 						lit, ok := spec.Values[0].(*ast.BasicLit)
 						if !ok && lit.Kind != token.STRING {
-							return nil, fmt.Errorf("%s: CodeLensKind value is not a string literal", posn)
+							return nil, fmt.Errorf("%s: CodeLensSource value is not a string literal", posn)
 						}
 						value, _ := strconv.Unquote(lit.Value) // ignore error: AST is well-formed
 						if spec.Doc == nil {
@@ -565,32 +565,32 @@
 		}
 	}
 	if len(enumDoc) == 0 {
-		return nil, fmt.Errorf("failed to extract any CodeLensKind declarations")
+		return nil, fmt.Errorf("failed to extract any CodeLensSource declarations")
 	}
 
 	// Build list of Lens descriptors.
 	var lenses []*doc.Lens
-	addAll := func(kinds map[protocol.CodeLensKind]cache.LensFunc, fileType string) error {
-		slice := maps.Keys(kinds)
+	addAll := func(sources map[protocol.CodeLensSource]cache.CodeLensSourceFunc, fileType string) error {
+		slice := maps.Keys(sources)
 		sort.Slice(slice, func(i, j int) bool { return slice[i] < slice[j] })
-		for _, kind := range slice {
-			docText, ok := enumDoc[string(kind)]
+		for _, source := range slice {
+			docText, ok := enumDoc[string(source)]
 			if !ok {
-				return fmt.Errorf("missing CodeLensKind declaration for %s", kind)
+				return fmt.Errorf("missing CodeLensSource declaration for %s", source)
 			}
 			title, docText, _ := strings.Cut(docText, "\n") // first line is title
 			lenses = append(lenses, &doc.Lens{
 				FileType: fileType,
-				Lens:     string(kind),
+				Lens:     string(source),
 				Title:    title,
 				Doc:      docText,
-				Default:  defaults[kind],
+				Default:  defaults[source],
 			})
 		}
 		return nil
 	}
-	addAll(golang.LensFuncs(), "Go")
-	addAll(mod.LensFuncs(), "go.mod")
+	addAll(golang.CodeLensSources(), "Go")
+	addAll(mod.CodeLensSources(), "go.mod")
 	return lenses, nil
 }
 
```
```
The name of the file: gopls/internal/doc/api.json
Insertions: 17, Deletions: 17.

@@ -799,49 +799,49 @@
 			},
 			{
 				"Name": "codelenses",
-				"Type": "map[golang.org/x/tools/gopls/internal/protocol.CodeLensKind]bool",
+				"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",
 				"EnumKeys": {
 					"ValueType": "bool",
 					"Keys": [
 						{
 							"Name": "\"gc_details\"",
-							"Doc": "\nThis codelens causes the `package` declaration of each file\nto be annotated with a command to toggle the state of the\nper-session variable that controls whether optimization\ndecisions from the Go compiler (formerly known as \"gc\")\nshould be displayed as diagnostics.\n\nOptimization decisions include:\n- whether a variable escapes, and how escape is inferred;\n- whether a nil-pointer check is implied or eliminated;\n- whether a function can be inlined.\n\nTODO(adonovan): this lens is off by default because the\nannotation is annoying and because VS Code has a separate\n\"Toggle gc details\" command. Replace it with a Code Action\n(\"Source action...\").\n",
+							"Doc": "\nThis codelens source causes the `package` declaration of\neach file to be annotated with a command to toggle the\nstate of the per-session variable that controls whether\noptimization decisions from the Go compiler (formerly known\nas \"gc\") should be displayed as diagnostics.\n\nOptimization decisions include:\n- whether a variable escapes, and how escape is inferred;\n- whether a nil-pointer check is implied or eliminated;\n- whether a function can be inlined.\n\nTODO(adonovan): this source is off by default because the\nannotation is annoying and because VS Code has a separate\n\"Toggle gc details\" command. Replace it with a Code Action\n(\"Source action...\").\n",
 							"Default": "false"
 						},
 						{
 							"Name": "\"generate\"",
-							"Doc": "\nThis codelens annotates any `//go:generate` comments with\ncommands to run `go generate` in this directory,\non all directories recursively beneath this one.\n\nSee [Generating code](https://go.dev/blog/generate) for\nmore details.\n",
+							"Doc": "\nThis codelens source annotates any `//go:generate` comments\nwith commands to run `go generate` in this directory, on\nall directories recursively beneath this one.\n\nSee [Generating code](https://go.dev/blog/generate) for\nmore details.\n",
 							"Default": "true"
 						},
 						{
 							"Name": "\"regenerate_cgo\"",
-							"Doc": "\nThis codelens annotates an `import \"C\"` declaration with a\ncommand to re-run the [cgo\ncommand](https://pkg.go.dev/cmd/cgo) to regenerate the\ncorresponding Go declarations.\n\nUse this after editing the C code in comments attached to\nthe import, or in C header files included by it.\n",
+							"Doc": "\nThis codelens source annotates an `import \"C\"` declaration\nwith a command to re-run the [cgo\ncommand](https://pkg.go.dev/cmd/cgo) to regenerate the\ncorresponding Go declarations.\n\nUse this after editing the C code in comments attached to\nthe import, or in C header files included by it.\n",
 							"Default": "true"
 						},
 						{
 							"Name": "\"test\"",
-							"Doc": "\nThis codelens annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis codelens 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 more sophisticated client-side Test Explorer.\nSee golang/go#67400 for a discussion of this feature.\n",
 							"Default": "false"
 						},
 						{
 							"Name": "\"run_govulncheck\"",
-							"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run Govulncheck.\n\n[Govulncheck](https://go.dev/blog/vuln) is a static\nanalysis tool that computes the set of functions reachable\nwithin your application, including dependencies;\nqueries a database of known security vulnerabilities; and\nreports any potential problems it finds.\n",
+							"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run Govulncheck.\n\n[Govulncheck](https://go.dev/blog/vuln) is a static\nanalysis tool that computes the set of functions reachable\nwithin your application, including dependencies;\nqueries a database of known security vulnerabilities; and\nreports any potential problems it finds.\n",
 							"Default": "false"
 						},
 						{
 							"Name": "\"tidy\"",
-							"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run [`go mod\ntidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures\nthat the go.mod file matches the source code in the module.\n",
+							"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run [`go mod\ntidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures\nthat the go.mod file matches the source code in the module.\n",
 							"Default": "true"
 						},
 						{
 							"Name": "\"upgrade_dependency\"",
-							"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with commands to:\n\n- check for available upgrades,\n- upgrade direct dependencies, and\n- upgrade all dependencies transitively.\n",
+							"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with commands to:\n\n- check for available upgrades,\n- upgrade direct dependencies, and\n- upgrade all dependencies transitively.\n",
 							"Default": "true"
 						},
 						{
 							"Name": "\"vendor\"",
-							"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run [`go mod\nvendor`](https://go.dev/ref/mod#go-mod-vendor), which\ncreates or updates the directory named `vendor` in the\nmodule root so that it contains an up-to-date copy of all\nnecessary package dependencies.\n",
+							"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run [`go mod\nvendor`](https://go.dev/ref/mod#go-mod-vendor), which\ncreates or updates the directory named `vendor` in the\nmodule root so that it contains an up-to-date copy of all\nnecessary package dependencies.\n",
 							"Default": "true"
 						}
 					]
@@ -1176,56 +1176,56 @@
 			"FileType": "Go",
 			"Lens": "gc_details",
 			"Title": "Toggle display of Go compiler optimization decisions",
-			"Doc": "\nThis codelens causes the `package` declaration of each file\nto be annotated with a command to toggle the state of the\nper-session variable that controls whether optimization\ndecisions from the Go compiler (formerly known as \"gc\")\nshould be displayed as diagnostics.\n\nOptimization decisions include:\n- whether a variable escapes, and how escape is inferred;\n- whether a nil-pointer check is implied or eliminated;\n- whether a function can be inlined.\n\nTODO(adonovan): this lens is off by default because the\nannotation is annoying and because VS Code has a separate\n\"Toggle gc details\" command. Replace it with a Code Action\n(\"Source action...\").\n",
+			"Doc": "\nThis codelens source causes the `package` declaration of\neach file to be annotated with a command to toggle the\nstate of the per-session variable that controls whether\noptimization decisions from the Go compiler (formerly known\nas \"gc\") should be displayed as diagnostics.\n\nOptimization decisions include:\n- whether a variable escapes, and how escape is inferred;\n- whether a nil-pointer check is implied or eliminated;\n- whether a function can be inlined.\n\nTODO(adonovan): this source is off by default because the\nannotation is annoying and because VS Code has a separate\n\"Toggle gc details\" command. Replace it with a Code Action\n(\"Source action...\").\n",
 			"Default": false
 		},
 		{
 			"FileType": "Go",
 			"Lens": "generate",
 			"Title": "Run `go generate`",
-			"Doc": "\nThis codelens annotates any `//go:generate` comments with\ncommands to run `go generate` in this directory,\non all directories recursively beneath this one.\n\nSee [Generating code](https://go.dev/blog/generate) for\nmore details.\n",
+			"Doc": "\nThis codelens source annotates any `//go:generate` comments\nwith commands to run `go generate` in this directory, on\nall directories recursively beneath this one.\n\nSee [Generating code](https://go.dev/blog/generate) for\nmore details.\n",
 			"Default": true
 		},
 		{
 			"FileType": "Go",
 			"Lens": "regenerate_cgo",
 			"Title": "Re-generate cgo declarations",
-			"Doc": "\nThis codelens annotates an `import \"C\"` declaration with a\ncommand to re-run the [cgo\ncommand](https://pkg.go.dev/cmd/cgo) to regenerate the\ncorresponding Go declarations.\n\nUse this after editing the C code in comments attached to\nthe import, or in C header files included by it.\n",
+			"Doc": "\nThis codelens source annotates an `import \"C\"` declaration\nwith a command to re-run the [cgo\ncommand](https://pkg.go.dev/cmd/cgo) to regenerate the\ncorresponding Go declarations.\n\nUse this after editing the C code in comments attached to\nthe import, or in C header files included by it.\n",
 			"Default": true
 		},
 		{
 			"FileType": "Go",
 			"Lens": "test",
 			"Title": "Run tests and benchmarks",
-			"Doc": "\nThis codelens annotates each `Test` and `Benchmark`\nfunction in a `*_test.go` file with a command to run it.\n\nThis codelens 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 more sophisticated client-side Test Explorer.\nSee golang/go#67400 for a discussion of this feature.\n",
 			"Default": false
 		},
 		{
 			"FileType": "go.mod",
 			"Lens": "run_govulncheck",
 			"Title": "Run govulncheck",
-			"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run Govulncheck.\n\n[Govulncheck](https://go.dev/blog/vuln) is a static\nanalysis tool that computes the set of functions reachable\nwithin your application, including dependencies;\nqueries a database of known security vulnerabilities; and\nreports any potential problems it finds.\n",
+			"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run Govulncheck.\n\n[Govulncheck](https://go.dev/blog/vuln) is a static\nanalysis tool that computes the set of functions reachable\nwithin your application, including dependencies;\nqueries a database of known security vulnerabilities; and\nreports any potential problems it finds.\n",
 			"Default": false
 		},
 		{
 			"FileType": "go.mod",
 			"Lens": "tidy",
 			"Title": "Tidy go.mod file",
-			"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run [`go mod\ntidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures\nthat the go.mod file matches the source code in the module.\n",
+			"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run [`go mod\ntidy`](https://go.dev/ref/mod#go-mod-tidy), which ensures\nthat the go.mod file matches the source code in the module.\n",
 			"Default": true
 		},
 		{
 			"FileType": "go.mod",
 			"Lens": "upgrade_dependency",
 			"Title": "Update dependencies",
-			"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with commands to:\n\n- check for available upgrades,\n- upgrade direct dependencies, and\n- upgrade all dependencies transitively.\n",
+			"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with commands to:\n\n- check for available upgrades,\n- upgrade direct dependencies, and\n- upgrade all dependencies transitively.\n",
 			"Default": true
 		},
 		{
 			"FileType": "go.mod",
 			"Lens": "vendor",
 			"Title": "Update vendor directory",
-			"Doc": "\nThis codelens annotates the `module` directive in a go.mod\nfile with a command to run [`go mod\nvendor`](https://go.dev/ref/mod#go-mod-vendor), which\ncreates or updates the directory named `vendor` in the\nmodule root so that it contains an up-to-date copy of all\nnecessary package dependencies.\n",
+			"Doc": "\nThis codelens source annotates the `module` directive in a\ngo.mod file with a command to run [`go mod\nvendor`](https://go.dev/ref/mod#go-mod-vendor), which\ncreates or updates the directory named `vendor` in the\nmodule root so that it contains an up-to-date copy of all\nnecessary package dependencies.\n",
 			"Default": true
 		}
 	],
```
```
The name of the file: gopls/internal/settings/settings.go
Insertions: 5, Deletions: 5.

@@ -185,7 +185,7 @@
 	// ...
 	// }
 	// ```
-	Codelenses map[protocol.CodeLensKind]bool
+	Codelenses map[protocol.CodeLensSource]bool
 
 	// SemanticTokens controls whether the LSP server will send
 	// semantic tokens to the client. If false, gopls will send empty semantic
@@ -865,13 +865,13 @@
 		}
 
 	case "codelenses", "codelens":
-		lensOverrides := asBoolMap[protocol.CodeLensKind](result)
+		lensOverrides := asBoolMap[protocol.CodeLensSource](result)
 		if result.Error == nil {
 			if o.Codelenses == nil {
-				o.Codelenses = make(map[protocol.CodeLensKind]bool)
+				o.Codelenses = make(map[protocol.CodeLensSource]bool)
 			}
-			for lens, enabled := range lensOverrides {
-				o.Codelenses[lens] = enabled
+			for source, enabled := range lensOverrides {
+				o.Codelenses[source] = enabled
 			}
 		}
 
```
```
The name of the file: gopls/doc/settings.md
Insertions: 24, Deletions: 25.

@@ -170,7 +170,7 @@
 ### UI
 
 <a id='codelenses'></a>
-#### ⬤ **codelenses** *map[golang.org/x/tools/gopls/internal/protocol.CodeLensKind]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
@@ -558,9 +558,8 @@
 The LSP `CodeLens` operation requests the
 current set of code lenses for a file.
 
-Gopls provides a variety of algorithms for suggesting code lenses.
-(Confusingly, we sometimes refer to these algorithms or features as
-"code lenses" too.) They are described below.
+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.
@@ -569,18 +568,18 @@
 ### ⬤ `gc_details`: Toggle display of Go compiler optimization decisions
 
 
-This codelens 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.
+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 lens is off by default because the
+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...").
@@ -593,9 +592,9 @@
 ### ⬤ `generate`: Run `go generate`
 
 
-This codelens annotates any `//go:generate` comments with
-commands to run `go generate` in this directory,
-on all directories recursively beneath this one.
+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.
@@ -608,8 +607,8 @@
 ### ⬤ `regenerate_cgo`: Re-generate cgo declarations
 
 
-This codelens annotates an `import "C"` declaration with a
-command to re-run the [cgo
+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.
 
@@ -624,10 +623,10 @@
 ### ⬤ `test`: Run tests and benchmarks
 
 
-This codelens annotates each `Test` and `Benchmark`
+This codelens source annotates each `Test` and `Benchmark`
 function in a `*_test.go` file with a command to run it.
 
-This codelens is off by default because VS Code has
+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.
 
@@ -639,8 +638,8 @@
 ### ⬤ `run_govulncheck`: Run govulncheck
 
 
-This codelens annotates the `module` directive in a go.mod
-file with a command to 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
@@ -656,8 +655,8 @@
 ### ⬤ `tidy`: Tidy go.mod file
 
 
-This codelens annotates the `module` directive in a go.mod
-file with a command to run [`go mod
+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.
 
@@ -669,8 +668,8 @@
 ### ⬤ `upgrade_dependency`: Update dependencies
 
 
-This codelens annotates the `module` directive in a go.mod
-file with commands to:
+This codelens source annotates the `module` directive in a
+go.mod file with commands to:
 
 - check for available upgrades,
 - upgrade direct dependencies, and
@@ -684,8 +683,8 @@
 ### ⬤ `vendor`: Update vendor directory
 
 
-This codelens annotates the `module` directive in a go.mod
-file with a command to run [`go mod
+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
```

Change information

Commit message:

gopls/internal/protocol: separate CodeLens from Command; document

Historically, CodeLenses were identified in the UI (LSP, CLI, docs)
by the command.Command that they return, but this is confusing
and potentially ambiguous as a single lens algorithm may offer
many commands, potentially overlapping.

This change establishes a separate CodeLensKind identifier for
them. The actual string values must remain unchanged to avoid
breaking users.

The documentation generator now uses the doc comments attached
to these CodeLensKind enum declarations. I have updated and
elaborated the documentation for each one.

Change-Id: I4a331930ca6a22b85150615e87ee79a66434ebe3

Reviewed-on: https://go-review.googlesource.com/c/tools/+/586175

Auto-Submit: Alan Donovan <adon...@google.com>

Reviewed-by: Robert Findley <rfin...@google.com>

LUCI-TryBot-Result: Go LUCI <golang...@luci-project-accounts.iam.gserviceaccount.com>

Files: