gopls/doc: delete commands.md

This change deletes the public documentation of gopls'
command set, which is an internal implementation detail.
Adventurous users can read the source of command.Interface.

Also, delete the Commands portion of the JSON API,
which is not used.

Change-Id: Ib2e2e8fcee880805c6556ee40fcbe1891712af5a
Reviewed-on: https://go-review.googlesource.com/c/tools/+/597276
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

gopls/doc/features/README.md

@@ -58,7 +58,6 @@ when making significant changes to existing features or when adding new ones.
   - [Template files](templates.md): files parsed by `text/template` and `html/template`
   - [go.mod and go.work files](modfiles.md): Go module and workspace manifests
 - [Command-line interface](../command-line.md): CLI for debugging and scripting (unstable)
-- [Non-standard commands](../commands.md): gopls-specific RPC protocol extensions (unstable)
 
 You can find this page from within your editor by executing the
 `gopls.doc.features` [code action](transformation.md#code-actions),

gopls/doc/features/transformation.md

@@ -6,12 +6,15 @@ formatting, simplifications), code repair (fixes), and editing support
 (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
-  protocol;
-- some are [commands](../commands.md) exposed through [Code
-  Lenses](../codelenses.md) (though none of these are transformations of Go syntax);
+- A few, such as Formatting and Rename, are primary operations in the
+  protocol.
+- Some transformations are exposed through [Code Lenses](../codelenses.md),
+  which return _commands_, arbitrary server
+  operations invoked for their side effects through a
+  [`workspace/executeCommand`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_executeCommand) request;
+  however, no current code lenses are transformations of Go syntax.
   <!-- Generate, RegenerateCgo (Go); Tidy, UpgradeDependency, Vendor (go.mod) -->
-- most are defined as *code actions*.
+- Most transformations are defined as *code actions*.
 
 ## Code Actions
 
@@ -27,9 +30,8 @@ A `codeAction` request delivers the menu, so to speak, but it does
 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)
-to be sent back to the server for its side effects,
-just as with the command associated with a Code Lens.
+But in most cases the action contains a command,
+similar to the command associated with a code lens.
 This allows the work of computing the patch to be done lazily, only
 when actually needed. (Most aren't.)
 The server may then compute the edit and send the client a

gopls/doc/features/web.md

@@ -49,10 +49,10 @@ your source code has been modified but not saved.
 like your editor to raise its window when handling this event.)
 
 <a name='doc'></a>
-## View package documentation
+## Browse package documentation
 
 In any Go source file, a code action request returns a command to
-"View package documentation". This command opens a browser window
+"Browse package documentation". This command opens a browser window
 showing the documentation for the current Go package, presented using
 a similar design to https://pkg.go.dev.
 
@@ -61,21 +61,21 @@ internal ones that may be unpublished externally. Reloading the page
 updates the documentation to reflect your changes. It is not necessary
 to save modified Go source files.
 
-<img title="View package documentation" src="../assets/browse-pkg-doc.png" width='80%'>
+<img title="Browse package documentation" src="../assets/browse-pkg-doc.png" width='80%'>
 
 Clicking on the link for a package-level symbol or method, which in
 `pkg.go.dev` would ordinarily take you to a source-code viewer such as
 GitHub or Google Code Search, causes your editor to navigate to the
 relevant source file and line.
 
 Client support:
-- **VS Code**: Use the "Source Action... > View package documentation" menu.
+- **VS Code**: Use the "Source Action... > Browse documentation for package P" menu.
 - **Emacs + eglot**: Use `M-x go-browse-doc` in [go-mode](https://github.com/dominikh/go-mode.el).
 - **Vim + coc.nvim**: ??
 
 
 <a name='freesymbols'></a>
-## View free symbols
+## Browse free symbols
 
 When studying code, either to understand it or to evaluate a different
 organization or factoring, it is common to need to know what the
@@ -84,14 +84,14 @@ considering extracting it into its own function and want to know what
 parameters it would take, or just to understand how one piece of a long
 function relates to the preceding pieces.
 
-If you select a chunk of code, and apply the "[View free
-symbols](../commands.md#gopls.free_symbols)" command, your editor will
+If you select a chunk of code, and invoke the "Browse free symbols"
+[code action](transformation.md#code-actions), your editor will
 open a browser displaying a report on the free symbols of the
 selection. A symbol is "free" if it is referenced from within the
 selection but defined outside of it. In essence, these are the inputs
 to the selected chunk.
 
-<img title="View free symbols" src="../assets/browse-free-symbols.png" width='80%'>
+<img title="Browse free symbols" src="../assets/browse-free-symbols.png" width='80%'>
 
 The report classifies the symbols into imported, local, and
 package-level symbols. The imported symbols are grouped by package,
@@ -102,23 +102,22 @@ editor to navigate to its declaration.
 TODO: explain dotted paths.
 
 Client support:
-- **VS Code**: Use the "Source Action... > View free symbols" menu.
+- **VS Code**: Use the "Source Action... > Browse free symbols" menu.
 - **Emacs + eglot**: Use `M-x go-browse-freesymbols` in [go-mode](https://github.com/dominikh/go-mode.el).
 - **Vim + coc.nvim**: ??
 
 
 <a name='assembly'></a>
-## View assembly
+## Browsse assembly
 
 When you're optimizing the performance of your code or investigating
 an unexpected crash, it may sometimes be helpful to inspect the
 assembly code produced by the compiler for a given Go function.
 
-If you position the cursor or selection within a function f, a code
-action will offer the "[View assembly for
-f](../commands.md#gopls.assembly)" command. This opens a web-based
-listing of the assembly for the function, plus any functions nested
-within it.
+If you position the cursor or selection within a function f,
+gopls offers the "Browse assembly for f" [code action](transformation.md#code-actions).
+This opens a web-based listing of the assembly for the function, plus
+any functions nested within it.
 
 Each time you edit your source and reload the page, the current
 package is recompiled and the listing is updated. It is not necessary
@@ -134,19 +133,19 @@ Each instruction is displayed with a link that causes your editor to
 navigate to the source line responsible for the instruction, according
 to the debug information.
 
-<img title="View assembly" src="../assets/browse-assembly.png" width="80%">
+<img title="Browse assembly" src="../assets/browse-assembly.png" width="80%">
 
 The example above shows the arm64 assembly listing of
 [`time.NewTimer`](https://pkg.go.dev/time#NewTimer).
 Observe that the indicated instruction links to a source location
 inside a different function, `syncTimer`, because the compiler
 inlined the call from `NewTimer` to `syncTimer`.
 
-Viewing assembly is not yet supported for generic functions, package
+Browsing assembly is not yet supported for generic functions, package
 initializers (`func init`), or functions in test packages.
 (Contributions welcome!)
 
 Client support:
-- **VS Code**: Use the "Source Action... > View GOARCH assembly for f" menu.
+- **VS Code**: Use the "Source Action... > Browse GOARCH assembly for f" menu.
 - **Emacs + eglot**: Use `M-x go-browse-assembly` in [go-mode](https://github.com/dominikh/go-mode.el).
 - **Vim + coc.nvim**: ??

gopls/doc/generate/generate.go

@@ -5,7 +5,6 @@
 // The generate command updates the following files of documentation:
 //
 //	gopls/doc/settings.md   -- from linking gopls/internal/settings.DefaultOptions
-//	gopls/doc/commands.md   -- from loading gopls/internal/protocol/command
 //	gopls/doc/analyzers.md  -- from linking gopls/internal/settings.DefaultAnalyzers
 //	gopls/doc/inlayHints.md -- from loading gopls/internal/settings.InlayHint
 //	gopls/internal/doc/api.json -- all of the above in a single value, for 'gopls api-json'
@@ -41,7 +40,6 @@ import (
 	"golang.org/x/tools/gopls/internal/doc"
 	"golang.org/x/tools/gopls/internal/golang"
 	"golang.org/x/tools/gopls/internal/mod"
-	"golang.org/x/tools/gopls/internal/protocol/command/commandmeta"
 	"golang.org/x/tools/gopls/internal/settings"
 	"golang.org/x/tools/gopls/internal/util/maps"
 	"golang.org/x/tools/gopls/internal/util/safetoken"
@@ -88,7 +86,6 @@ func doMain(write bool) (bool, error) {
 		{"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},
 	} {
@@ -150,10 +147,6 @@ func loadAPI() (*doc.API, error) {
 		Analyzers: loadAnalyzers(settings.DefaultAnalyzers), // no staticcheck analyzers
 	}
 
-	api.Commands, err = loadCommands()
-	if err != nil {
-		return nil, err
-	}
 	api.Lenses, err = loadLenses(settingsPkg, defaults.Codelenses)
 	if err != nil {
 		return nil, err
@@ -441,84 +434,6 @@ func valueDoc(name, value, doc string) string {
 	return fmt.Sprintf("`%s`: %s", value, doc)
 }
 
-func loadCommands() ([]*doc.Command, error) {
-	var commands []*doc.Command
-
-	cmds, err := commandmeta.Load()
-	if err != nil {
-		return nil, err
-	}
-	// Parse the objects it contains.
-	for _, cmd := range cmds {
-		cmdjson := &doc.Command{
-			Command: cmd.Name,
-			Title:   cmd.Title,
-			Doc:     cmd.Doc,
-			ArgDoc:  argsDoc(cmd.Args),
-		}
-		if cmd.Result != nil {
-			cmdjson.ResultDoc = typeDoc(cmd.Result, 0)
-		}
-		commands = append(commands, cmdjson)
-	}
-	return commands, nil
-}
-
-func argsDoc(args []*commandmeta.Field) string {
-	var b strings.Builder
-	for i, arg := range args {
-		b.WriteString(typeDoc(arg, 0))
-		if i != len(args)-1 {
-			b.WriteString(",\n")
-		}
-	}
-	return b.String()
-}
-
-func typeDoc(arg *commandmeta.Field, level int) string {
-	// Max level to expand struct fields.
-	const maxLevel = 3
-	if len(arg.Fields) > 0 {
-		if level < maxLevel {
-			return arg.FieldMod + structDoc(arg.Fields, level)
-		}
-		return "{ ... }"
-	}
-	under := arg.Type.Underlying()
-	switch u := under.(type) {
-	case *types.Slice:
-		return fmt.Sprintf("[]%s", u.Elem().Underlying().String())
-	}
-	// TODO(adonovan): use (*types.Package).Name qualifier.
-	return types.TypeString(under, nil)
-}
-
-// TODO(adonovan): this format is strange; it's not Go, nor JSON, nor LSP. Rethink.
-func structDoc(fields []*commandmeta.Field, level int) string {
-	var b strings.Builder
-	b.WriteString("{\n")
-	indent := strings.Repeat("\t", level)
-	for _, fld := range fields {
-		if fld.Doc != "" && level == 0 {
-			doclines := strings.Split(fld.Doc, "\n")
-			for _, line := range doclines {
-				text := ""
-				if line != "" {
-					text = " " + line
-				}
-				fmt.Fprintf(&b, "%s\t//%s\n", indent, text)
-			}
-		}
-		tag := strings.Split(fld.JSONTag, ",")[0]
-		if tag == "" {
-			tag = fld.Name
-		}
-		fmt.Fprintf(&b, "%s\t%q: %s,\n", indent, tag, typeDoc(fld, level+1))
-	}
-	fmt.Fprintf(&b, "%s}", indent)
-	return b.String()
-}
-
 // loadLenses combines the syntactic comments from the settings
 // package with the default values from settings.DefaultOptions(), and
 // returns a list of Code Lens descriptors.
@@ -828,23 +743,6 @@ func rewriteCodeLenses(prevContent []byte, api *doc.API) ([]byte, error) {
 	return replaceSection(prevContent, "Lenses", buf.Bytes())
 }
 
-func rewriteCommands(prevContent []byte, api *doc.API) ([]byte, error) {
-	var buf bytes.Buffer
-	for _, command := range api.Commands {
-		// Emit HTML anchor as GitHub markdown doesn't support
-		// "# Heading {#anchor}" syntax.
-		fmt.Fprintf(&buf, "<a id='%s'></a>\n", command.Command)
-		fmt.Fprintf(&buf, "## `%s`: **%s**\n\n%v\n\n", command.Command, command.Title, command.Doc)
-		if command.ArgDoc != "" {
-			fmt.Fprintf(&buf, "Args:\n\n```\n%s\n```\n\n", command.ArgDoc)
-		}
-		if command.ResultDoc != "" {
-			fmt.Fprintf(&buf, "Result:\n\n```\n%s\n```\n\n", command.ResultDoc)
-		}
-	}
-	return replaceSection(prevContent, "Commands", buf.Bytes())
-}
-
 func rewriteAnalyzers(prevContent []byte, api *doc.API) ([]byte, error) {
 	var buf bytes.Buffer
 	for _, analyzer := range api.Analyzers {

gopls/internal/cmd/execute.go

@@ -35,11 +35,9 @@ The execute command sends an LSP ExecuteCommand request to gopls,
 with a set of optional JSON argument values.
 Some commands return a result, also JSON.
 
-Available commands are documented at:
-
-	https://github.com/golang/tools/blob/master/gopls/doc/commands.md
-
-This interface is experimental and commands may change or disappear without notice.
+Gopls' command set is defined by the command.Interface type; see
+https://pkg.go.dev/golang.org/x/tools/gopls/internal/protocol/command#Interface.
+It is not a stable interface: commands may change or disappear without notice.
 
 Examples:
 

gopls/internal/cmd/usage/execute.hlp

@@ -7,11 +7,9 @@ The execute command sends an LSP ExecuteCommand request to gopls,
 with a set of optional JSON argument values.
 Some commands return a result, also JSON.
 
-Available commands are documented at:
-
-	https://github.com/golang/tools/blob/master/gopls/doc/commands.md
-
-This interface is experimental and commands may change or disappear without notice.
+Gopls' command set is defined by the command.Interface type; see
+https://pkg.go.dev/golang.org/x/tools/gopls/internal/protocol/command#Interface.
+It is not a stable interface: commands may change or disappear without notice.
 
 Examples:
 

gopls/internal/doc/api.go

@@ -21,7 +21,6 @@ var JSON string
 // TODO(adonovan): document these data types.
 type API struct {
 	Options   map[string][]*Option
-	Commands  []*Command
 	Lenses    []*Lens
 	Analyzers []*Analyzer
 	Hints     []*Hint
@@ -54,14 +53,6 @@ type EnumValue struct {
 	Doc   string // doc comment; always starts with `Value`
 }
 
-type Command struct {
-	Command   string // e.g. "gopls.run_tests"
-	Title     string
-	Doc       string
-	ArgDoc    string
-	ResultDoc string
-}
-
 type Lens struct {
 	FileType string // e.g. "Go", "go.mod"
 	Lens     string