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]>

Author: adonovan

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>