8000 gopls/doc: document all of gopls' features · golang/tools@799a471 · GitHub
[go: up one dir, main page]
Skip to content

Commit 799a471

Browse files
adonovangopherbot
adonovan
authored and
gopherbot
committed
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 <adonovan@google.com> LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> Reviewed-by: Robert Findley <rfindley@google.com>
1 parent 2e239ad commit 799a471

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+1822
-161
lines changed

‎gopls/README.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,26 @@
33
[![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools/gopls)](https://pkg.go.dev/golang.org/x/tools/gopls)
44

55
`gopls` (pronounced "Go please") is the official Go [language server] developed
6-
by the Go team. It provides IDE features to any [LSP]-compatible editor.
6+
by the Go team.
7+
It provides a wide variety of [IDE features](doc/features/README.md)
8+
to any [LSP]-compatible editor.
79

810
<!--TODO(rfindley): Add gifs here.-->
911

1012
You should not need to interact with `gopls` directly--it will be automatically
1113
integrated into your editor. The specific features and settings vary slightly
1214
by editor, so we recommend that you proceed to the
1315
[documentation for your editor](#editors) below.
16+
Also, the gopls documentation for each feature describes whether it is
17+
supported in each client editor.
1418

1519
## Editors
1620

1721
To get started with `gopls`, install an LSP plugin in your editor of choice.
1822

23+
TODO: ensure that each editor has a local page (and move these to doc/clients/$EDITOR.md).
24+
TODO: also, be more consistent about editor (e.g. Emacs) vs. client (e.g. eglot).
25+
1926
* [VS Code](https://github.com/golang/vscode-go/blob/master/README.md)
2027
* [Vim / Neovim](doc/vim.md)
2128
* [Emacs](doc/emacs.md)
@@ -137,8 +144,9 @@ If you are having issues with `gopls`, please follow the steps described in the
137144

138145
## Additional information
139146

140-
* [Features](doc/features.md)
147+
* [Index of features](doc/features/README.md)
141148
* [Command-line interface](doc/command-line.md)
149+
* [Configuration settings](doc/settings.md)
142150
* [Advanced topics](doc/advanced.md)
143151
* [Contributing to `gopls`](doc/contributing.md)
144152
* [Integrating `gopls` with an editor](doc/design/integrating.md)

‎gopls/doc/advanced.md

Lines changed: 1 addition & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Advanced topics
1+
# Gopls: Advanced topics
22

33
This documentation is for advanced `gopls` users, who may want to test
44
unreleased versions or try out special features.
@@ -54,27 +54,4 @@ Note that you must work inside the `GOROOT/src` subdirectory, as the `go`
5454
command does not recognize `go.work` files in a parent of `GOROOT/src`
5555
(https://go.dev/issue/59429).
5656

57-
## Working with generic code
58-
59-
Gopls has support for editing generic Go code. To enable this support, you need
60-
to **install gopls using Go 1.18 or later**. The easiest way to do this is by
61-
[installing Go 1.18+](https://go.dev/dl) and then using this Go version to
62-
install gopls:
63-
64-
```
65-
$ go install golang.org/x/tools/gopls@latest
66-
```
67-
68-
It is strongly recommended that you install the latest version of `gopls`, or
69-
the latest **unstable** version as [described above](#installing-unreleased-versions).
70-
71-
The `gopls` built with these instructions understands generic code. See the
72-
[generics tutorial](https://go.dev/doc/tutorial/generics) for more information
73-
on how to use generics in Go!
74-
75-
### Known issues
76-
77-
* [`staticcheck`](https://github.com/golang/tools/blob/master/gopls/doc/settings.md#staticcheck)
78-
on generic code is not supported yet.
79-
8057
[Go project]: https://go.googlesource.com/go

‎gopls/doc/analyzers.md

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Analyzers
1+
# Gopls: Analyzers
22

33
<!-- No Table of Contents: GitHub's Markdown renderer synthesizes it. -->
44

@@ -15,19 +15,20 @@ before you run your tests, or even before you save your files.
1515
This document describes the suite of analyzers available in gopls,
1616
which aggregates analyzers from a variety of sources:
1717

18-
- all the usual bug-finding analyzers from the `go vet` suite;
19-
- a number of analyzers with more substantial dependencies that prevent them from being used in `go vet`;
20-
- analyzers that augment compilation errors by suggesting quick fixes to common mistakes; and
21-
- a handful of analyzers that suggest possible style improvements.
18+
- all the usual bug-finding analyzers from the `go vet` suite (e.g. `printf`; run `go tool vet help` for the complete list);
19+
- a number of analyzers with more substantial dependencies that prevent them from being used in `go vet` (e.g. `nilness`);
20+
- analyzers that augment compilation errors by suggesting quick fixes to common mistakes (e.g. `fillreturns`); and
21+
- a handful of analyzers that suggest possible style improvements (e.g. `simplifyrange`).
2222

23-
More details about how to enable and disable analyzers can be found
24-
[here](settings.md#analyses).
23+
To enable or disable analyzers, use the [analyses](settings.md#analyses) setting.
2524

2625
In addition, gopls includes the [`staticcheck` suite](https://staticcheck.dev/docs/checks),
2726
though these analyzers are off by default.
2827
Use the [`staticcheck`](settings.md#staticcheck`) setting to enable them,
2928
and consult staticcheck's documentation for analyzer details.
3029

30+
<!-- When staticcheck=true, we currently use the {S SA ST QF} suites, sans {SA5009, SA5011} -->
31+
3132

3233
<!-- BEGIN Analyzers: DO NOT MANUALLY EDIT THIS SECTION -->
3334
<a id='appends'></a>

‎gopls/doc/assets/convert-string-interpreted.png

41.3 KB
Loading

‎gopls/doc/assets/convert-string-raw.png

51.4 KB
Loading

‎gopls/doc/assets/diagnostic-analysis.png

51.4 KB
Loading

‎gopls/doc/assets/diagnostic-typeerror.png

63.5 KB
Loading

‎gopls/doc/assets/document-highlight.png

19.8 KB
Loading

‎gopls/doc/assets/documentlink.png

21.8 KB
Loading

‎gopls/doc/assets/extract-function-after.png

37.1 KB
Loading

0 commit comments

Comments
 (0)
0