gopls/doc: document all of gopls' features

This CL enumerates and documents each LSP feature
supported by gopls so that users can find out:
- what the tool is capable of,
- how to use it,
- what settings affect the feature, and
- whether their LSP client supports a given feature.

We plan to provide Code Actions to open the relevant
section of the manual, e.g. "Refactor > Describe refactorings..."

To review the markdown, cherrypick this CL then
run this command from x/tools:

 $ go run rsc.io/cmd/mdweb@latest -a localhost:9876 &
   open http://localhost:9876/gopls/doc/features/README.md

The topic of completion is left for another day,
as is support for go.mod files.

Updates golang/go#54115

Change-Id: I8f7de7571bfe0355b3597487efbc0d7aae7a12d6
Reviewed-on: https://go-review.googlesource.com/c/tools/+/583316
Auto-Submit: Alan Donovan <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Robert Findley <[email protected]>

gopls/README.md

@@ -3,19 +3,26 @@
 [![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools/gopls)](https://pkg.go.dev/golang.org/x/tools/gopls)
 
 `gopls` (pronounced "Go please") is the official Go [language server] developed
-by the Go team. It provides IDE features to any [LSP]-compatible editor.
+by the Go team.
+It provides a wide variety of [IDE features](doc/features/README.md)
+to any [LSP]-compatible editor.
 
 <!--TODO(rfindley): Add gifs here.-->
 
 You should not need to interact with `gopls` directly--it will be automatically
 integrated into your editor. The specific features and settings vary slightly
 by editor, so we recommend that you proceed to the
 [documentation for your editor](#editors) below.
+Also, the gopls documentation for each feature describes whether it is
+supported in each client editor.
 
 ## Editors
 
 To get started with `gopls`, install an LSP plugin in your editor of choice.
 
+TODO: ensure that each editor has a local page (and move these to doc/clients/$EDITOR.md).
+TODO: also, be more consistent about editor (e.g. Emacs) vs. client (e.g. eglot).
+
 * [VS Code](https://github.com/golang/vscode-go/blob/master/README.md)
 * [Vim / Neovim](doc/vim.md)
 * [Emacs](doc/emacs.md)
@@ -137,8 +144,9 @@ If you are having issues with `gopls`, please follow the steps described in the
 
 ## Additional information
 
-* [Features](doc/features.md)
+* [Index of features](doc/features/README.md)
 * [Command-line interface](doc/command-line.md)
+* [Configuration settings](doc/settings.md)
 * [Advanced topics](doc/advanced.md)
 * [Contributing to `gopls`](doc/contributing.md)
 * [Integrating `gopls` with an editor](doc/design/integrating.md)

gopls/doc/advanced.md

@@ -1,4 +1,4 @@
-# Advanced topics
+# Gopls: Advanced topics
 
 This documentation is for advanced `gopls` users, who may want to test
 unreleased versions or try out special features.
@@ -54,27 +54,4 @@ Note that you must work inside the `GOROOT/src` subdirectory, as the `go`
 command does not recognize `go.work` files in a parent of `GOROOT/src`
 (https://go.dev/issue/59429).
 
-## Working with generic code
-
-Gopls has support for editing generic Go code. To enable this support, you need
-to **install gopls using Go 1.18 or later**. The easiest way to do this is by
-[installing Go 1.18+](https://go.dev/dl) and then using this Go version to
-install gopls:
-
-```
-$ go install golang.org/x/tools/gopls@latest
-```
-
-It is strongly recommended that you install the latest version of `gopls`, or
-the latest **unstable** version as [described above](#installing-unreleased-versions).
-
-The `gopls` built with these instructions understands generic code. See the
-[generics tutorial](https://go.dev/doc/tutorial/generics) for more information
-on how to use generics in Go!
-
-### Known issues
-
-  * [`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

gopls/doc/analyzers.md

@@ -1,4 +1,4 @@
-# Analyzers
+# Gopls: Analyzers
 
 <!-- No Table of Contents: GitHub's Markdown renderer synthesizes it. -->
 
@@ -15,19 +15,20 @@ before you run your tests, or even before you save your files.
 This document describes the suite of analyzers available in gopls,
 which aggregates analyzers from a variety of sources:
 
-- all the usual bug-finding analyzers from the `go vet` suite;
-- a number of analyzers with more substantial dependencies that prevent them from being used in `go vet`;
-- analyzers that augment compilation errors by suggesting quick fixes to common mistakes; and
-- a handful of analyzers that suggest possible style improvements.
+- all the usual bug-finding analyzers from the `go vet` suite (e.g. `printf`; run `go tool vet help` for the complete list);
+- a number of analyzers with more substantial dependencies that prevent them from being used in `go vet` (e.g. `nilness`);
+- analyzers that augment compilation errors by suggesting quick fixes to common mistakes (e.g. `fillreturns`); and
+- a handful of analyzers that suggest possible style improvements (e.g. `simplifyrange`).
 
-More details about how to enable and disable analyzers can be found
-[here](settings.md#analyses).
+To enable or disable analyzers, use the [analyses](settings.md#analyses) setting.
 
 In addition, gopls includes the [`staticcheck` suite](https://staticcheck.dev/docs/checks),
 though these analyzers are off by default.
 Use the [`staticcheck`](settings.md#staticcheck`) setting to enable them,
 and consult staticcheck's documentation for analyzer details.
 
+<!-- When staticcheck=true, we currently use the {S SA ST QF} suites, sans {SA5009, SA5011} -->
+
 
 <!-- BEGIN Analyzers: DO NOT MANUALLY EDIT THIS SECTION -->
 <a id='appends'></a>

gopls/doc/codelenses.md

@@ -1,4 +1,4 @@
-# Code Lenses
+# Gopls: Code lenses
 
 A "code lens" is a command associated with a range of a source file.
 The VS Code manual describes code lenses as
@@ -14,6 +14,13 @@ They can be enabled and disabled using the
 [`codelenses`](settings.md#codelenses) setting.
 Their features are subject to change.
 
+Client support:
+- **VS Code**: Code Lenses appear as small text links above a line of source code.
+- **Emacs + eglot**: Not supported, but prototype exists at https://github.joaotavora/eglot/pull/71.
+- **Vim + coc.nvim**: ??
+- **CLI**: `gopls codelens`. For example, `gopls codelens -exec file.go:123 "run test"` runs the test at the specified line.
+
+
 <!-- 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

gopls/doc/command-line.md

@@ -1,15 +1,35 @@
-# Command line
+# Gopls: Command-line interface
 
-**Note: The `gopls` command-line is still experimental and subject to change at any point.**
+The `gopls` command provides a number of subcommands that expose much
+of the server's functionality. However, the interface is currently
+**experimental** and **subject to change at any point.**
+It is not efficient, complete, flexible, or officially supported.
 
-`gopls` exposes some (but not all) features on the command-line. This can be useful for debugging `gopls` itself.
+Its primary use is as a debugging aid.
+For example, this command reports the location of references to the
+symbol at the specified file/line/column:
 
-<!--TODO(rstambler): Generate this file.-->
+```
+$ gopls references ./gopls/main.go:35:8
+Log: Loading packages...
+Info: Finished loading packages.
+/home/gopher/xtools/go/packages/gopackages/main.go:27:7-11
+/home/gopher/xtools/gopls/internal/cmd/integration_test.go:1062:7-11
+/home/gopher/xtools/gopls/internal/test/integration/bench/bench_test.go:59:8-12
+/home/gopher/xtools/gopls/internal/test/integration/regtest.go:140:8-12
+/home/gopher/xtools/gopls/main.go:35:7-11
+```
 
-Learn about available commands and flags by running `gopls help`.
-
-Much of the functionality of `gopls` is available through a command line interface.
+See golang/go#63693 for a discussion of its future.
 
-There are two main reasons for this. The first is that we do not want users to rely on separate command line tools when they wish to do some task outside of an editor. The second is that the CLI assists in debugging. It is easier to reproduce behavior via single command.
+Learn about available commands and flags by running `gopls help`.
 
-It is not a goal of `gopls` to be a high performance command line tool. Its command line is intended for single file/package user interaction speeds, not bulk processing.
+Positions within files are specified as `file.go:line:column` triples,
+where the line and column start at 1, and columns are measured in
+bytes of the UTF-8 encoding.
+Alternatively, positions may be specified by the byte offset within
+the UTF-8 encoding of the file, starting from zero, for example
+`file.go:#1234`.
+(When working in non-ASCII files, beware that your editor may report a
+position's offset within its file using a different measure such as
+UTF-16 codes, Unicode code points, or graphemes).