Skip to content

Commit

Permalink
gopls/doc: document all of gopls' features
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
adonovan authored and gopherbot committed Jun 28, 2024
1 parent 2e239ad commit 799a471
Show file tree
Hide file tree
Showing 65 changed files with 1,822 additions and 161 deletions.
12 changes: 10 additions & 2 deletions gopls/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
25 changes: 1 addition & 24 deletions gopls/doc/advanced.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
15 changes: 8 additions & 7 deletions gopls/doc/analyzers.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Analyzers
# Gopls: Analyzers

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

Expand All @@ -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>
Expand Down
Binary file added gopls/doc/assets/convert-string-interpreted.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/convert-string-raw.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/diagnostic-analysis.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/diagnostic-typeerror.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/document-highlight.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/documentlink.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-function-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-function-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-to-new-file-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-to-new-file-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-var-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/extract-var-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-struct-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-struct-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-switch-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-switch-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-switch-enum-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/fill-switch-enum-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/foldingrange.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/hover-basic.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/hover-embed.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/hover-linkname.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/inlayhint-parameternames.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/invert-if-after.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/invert-if-before.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added gopls/doc/assets/outgoingcalls.png
Binary file added gopls/doc/assets/remove-unusedparam-after.png
Binary file added gopls/doc/assets/remove-unusedparam-before.png
Binary file added gopls/doc/assets/rename-conflict.png
Binary file added gopls/doc/assets/signature-help.png
9 changes: 8 additions & 1 deletion gopls/doc/codelenses.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down
38 changes: 29 additions & 9 deletions gopls/doc/command-line.md
Original file line number Diff line number Diff line change
@@ -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).
Loading

0 comments on commit 799a471

Please sign in to comment.