mirror of
https://github.com/golang/go
synced 2024-11-18 09:04:49 -07:00
gopls/doc: add and make minor changes to documentation
Change-Id: Ibb7d7715541ee2a712dd6927abceadc45ec60b41 Reviewed-on: https://go-review.googlesource.com/c/tools/+/195517 Reviewed-by: Ian Cottrell <iancottrell@google.com>
This commit is contained in:
Rebecca Stambler
parent
1d8cfc4bd2
commit
96954830e1
15
gopls/doc/command-line.md
Normal file
15
gopls/doc/command-line.md
Normal file
@ -0,0 +1,15 @@
|
||||
# Command line
|
||||
|
||||
## Flags
|
||||
|
||||
## Commands
|
||||
|
||||
### Serve
|
||||
|
||||
### Check
|
||||
|
||||
### Format
|
||||
|
||||
<!--- TODO: command line
|
||||
detailed command line instructions, use cases and flags
|
||||
--->
|
||||
@ -1,10 +1,10 @@
|
||||
# gopls documentation for contributors
|
||||
# Documentation for contributors
|
||||
|
||||
Contributions are welcome, but since development is so active, we request that you file an issue and claim it before starting to work on something. Otherwise, it is likely that we might already be working on a fix for your issue.
|
||||
|
||||
## Finding issues
|
||||
|
||||
All gopls issues are labeled as such (see the [gopls label][issue-gopls]. Issues that are suitable to just pick up are additionally tagged with the [help wanted label][issue-wanted]
|
||||
All `gopls` issues are labeled as such (see the [`gopls` label][issue-gopls]). Issues that are suitable for contributors are additionally tagged with the [`help-wanted` label][issue-wanted].
|
||||
|
||||
Before you begin working on an issue, please leave a comment that you are claiming it.
|
||||
|
||||
@ -14,7 +14,6 @@ Before you begin working on an issue, please leave a comment that you are claimi
|
||||
Provide information to get contributors up and running here
|
||||
--->
|
||||
|
||||
|
||||
## Debugging
|
||||
|
||||
<!--- TODO: debugging
|
||||
|
||||
@ -2,10 +2,10 @@
|
||||
|
||||
## Goals
|
||||
|
||||
* gopls should **become the default editor backend** for the major editors used by Go programmers, fully supported by the Go team.
|
||||
* gopls will be a **full implementation of LSP**, as described in the [LSP specification], to standardize as many of its features as possible.
|
||||
* gopls will be **clean and extensible** so that it can encompass additional features in the future, allowing Go tooling to become best in class once more.
|
||||
* gopls will **support alternate build systems** and file layouts, allowing Go development to be simpler and more powerful in any environment.
|
||||
* `gopls` should **become the default editor backend** for the major editors used by Go programmers, fully supported by the Go team.
|
||||
* `gopls` will be a **full implementation of LSP**, as described in the [LSP specification], to standardize as many of its features as possible.
|
||||
* `gopls` will be **clean and extensible** so that it can encompass additional features in the future, allowing Go tooling to become best in class once more.
|
||||
* `gopls` will **support alternate build systems and file layouts**, allowing Go development to be simpler and more powerful in any environment.
|
||||
|
||||
|
||||
## Context
|
||||
@ -220,7 +220,7 @@ Diagnostics | Static analysis results of the code, including compilation and lin
|
||||
----------- | ---
|
||||
Requires | Full go/analysis run, which needs full AST, type and SSA information
|
||||
LSP | [`textDocument/publishDiagnostics`]
|
||||
Previous | go build, go vet, golint, [errcheck], [staticcheck] <!-- TODO: and all the rest -->
|
||||
Previous | `go build`, `go vet`, `golint`, [errcheck], [staticcheck] <!-- TODO: and all the rest -->
|
||||
| | This is one of the most important IDE features, allowing fast turn around without having to run compilers and checkers in the shell. Often used to power problem lists, gutter markers and squiggle underlines in the IDE. <br/> There is some complicated design work to do in order to let users customize the set of checks being run, preferably without having to recompile the main LSP binary.
|
||||
|
||||
---
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Emacs
|
||||
|
||||
Use [lsp-mode]. gopls is built in now as a client, so no special config is necessary. You first must install gopls and put it somewhere in your PATH. Here is an example (assuming you are using [use-package]) to get you started:
|
||||
Use [lsp-mode]. gopls is built in now as a client, so no special config is necessary. You first must install `gopls` and put it somewhere in your `PATH`. Here is an example (assuming you are using [use-package]) to get you started:
|
||||
|
||||
```lisp
|
||||
(use-package lsp-mode
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# gopls plugin author documentation
|
||||
# Documentation for plugin authors
|
||||
|
||||
If you are integrating gopls into an editor by writing an editor plugin there are quite a few semantics of the communication between the editor and gopls that are not specified by the [LSP specification].
|
||||
If you are integrating `gopls` into an editor by writing an editor plugin, there are quite a few semantics of the communication between the editor and `gopls` that are not specified by the [LSP specification].
|
||||
|
||||
We attempt to document those details along with any other information that has been helpful to other plugin authors here.
|
||||
|
||||
|
||||
88
gopls/doc/settings.md
Normal file
88
gopls/doc/settings.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Settings
|
||||
|
||||
<!--TODO: Generate this file from the documentation in golang/org/x/tools/internal/lsp/source/options.go.-->
|
||||
|
||||
This document describes the global settings for `gopls` inside the editor. The settings block will be called `"gopls"` and contains a collection of controls for `gopls` that the editor is not expected to understand or control. These settings can also be configured differently per workspace folder.
|
||||
|
||||
In VSCode, this would be a section in your `settings.json` file that might look like this:
|
||||
|
||||
```json5
|
||||
"gopls": {
|
||||
"usePlaceholders": true,
|
||||
"completeUnimported": true
|
||||
},
|
||||
```
|
||||
|
||||
## Officially supported
|
||||
|
||||
Below is the list of settings that are officially supported for `gopls`.
|
||||
|
||||
### **buildFlags** *array of strings*
|
||||
|
||||
This is the set of flags passed on to the build system when invoked. It is applied to queries like `go list`, which is used when discovering files. The most common use is to set `-tags`.
|
||||
|
||||
### **env** *map of string to value*
|
||||
|
||||
This can be used to add environment variables. These will not affect `gopls` itself, but will be used for any external commands it invokes.
|
||||
|
||||
### **hoverKind** *string*
|
||||
|
||||
This controls the information that appears in the hover text.
|
||||
It must be one of:
|
||||
* `"NoDocumentation"`
|
||||
* `"SynopsisDocumentation"`
|
||||
* `"FullDocumentation"`
|
||||
|
||||
Authors of editor clients may wish to handle hover text differently, and so might use different settings. The options below are not intended for use by anyone other than the authors of editor plugins.
|
||||
|
||||
* `"SingleLine"`
|
||||
* `"Structured"`
|
||||
|
||||
Default: `"SynopsisDocumentation"`.
|
||||
|
||||
## **usePlaceholders** *boolean*
|
||||
|
||||
If true, then completion responses may contain placeholders for function parameters or struct fields.
|
||||
|
||||
Default: `false`.
|
||||
|
||||
## Experimental
|
||||
|
||||
The below settings are considered experimental. They may be deprecated or changed in the future. They are typically used to test experimental opt-in features or to disable features.
|
||||
|
||||
### **experimentalDisabledAnalyses** *array of strings*
|
||||
|
||||
A list of the names of analysis passes that should be disabled. You can use this to turn off analyses that you feel are not useful in the editor.
|
||||
|
||||
### **completionDocumentation** *boolean*
|
||||
|
||||
If false, indicates that the user does not want documentation with completion results.
|
||||
|
||||
Default value: `true`.
|
||||
|
||||
**completeUnimported** *boolean*
|
||||
|
||||
If true, the completion engine is allowed to make suggestions for packages that you do not currently import.
|
||||
|
||||
Default: `false`.
|
||||
|
||||
### **deepCompletion** *boolean*
|
||||
|
||||
If true, this turns on the ability to return completions from deep inside relevant entities, rather than just the locally accessible ones. Consider this example:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import "fmt"
|
||||
|
||||
type wrapString struct {
|
||||
str string
|
||||
}
|
||||
|
||||
func main() {
|
||||
x := wrapString{"hello world"}
|
||||
fmt.Printf(<>)
|
||||
}
|
||||
```
|
||||
|
||||
At the location of the `<>` in this program, deep completion would suggest the result `x.str`.
|
||||
@ -1,4 +1,4 @@
|
||||
# gopls status
|
||||
# Status
|
||||
|
||||
gopls is currently in **alpha**, so it is **not stable**.
|
||||
|
||||
|
||||
@ -1,42 +1,44 @@
|
||||
# gopls troubleshooting documentation
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
If you see a gopls error or crash, or gopls just stops working, please follow the troubleshooting steps below.
|
||||
|
||||
## Steps
|
||||
|
||||
|
||||
<!--- TODO: troubleshooting
|
||||
describe more basic and optional trouble shooting steps
|
||||
like checking you opened the module root
|
||||
and using the debug pages
|
||||
--->
|
||||
|
||||
1. Make sure gopls is [up to date](user.md#installing)
|
||||
1. Check the [known issues](status.md#known-issues)
|
||||
1. [Report the issue](file-an-issue)
|
||||
1. Make sure your `gopls` is [up to date](user.md#installing).
|
||||
1. Check the [known issues](status.md#known-issues).
|
||||
1. [Report the issue](file-an-issue).
|
||||
|
||||
## File an issue
|
||||
|
||||
You can use:
|
||||
* your editor's bug submission integration (if available)
|
||||
* `gopls bug` on the command line
|
||||
* directly on the [issue tracker](https://github.com/golang/go/issues/new?title=x%2Ftools%2Fgopls%3A%20%3Cfill%20this%20in%3E)
|
||||
* Your editor's bug submission integration (if available). For instance, `:GoReportGitHubIssue` in [`vim-go`](vim.md#vim-go).
|
||||
* `gopls bug` on the command line.
|
||||
* The [Go issue tracker](https://github.com/golang/go/issues/new?title=x%2Ftools%2Fgopls%3A%20%3Cfill%20this%20in%3E).
|
||||
|
||||
Along with an explanation of the issue, please share the information listed here:
|
||||
|
||||
1. Your editor and any settings you have configured (for example, your VSCode settings.json file).
|
||||
1. Your editor and any settings you have configured (for example, your VSCode `settings.json` file).
|
||||
1. A sample program that reproduces the issue, if possible.
|
||||
1. The output of `gopls version` on the command line.
|
||||
1. The output of `gopls -rpc.trace -v check /path/to/file.go`.
|
||||
1. gopls logs from when the issue occurred, as well as a timestamp for when the issue began to occur. See the [instructions](#capturing-gopls-logs) for information on how to capture gopls logs.
|
||||
|
||||
Much of this information is filled in for you if you use gopls to file the issue.
|
||||
Much of this information is filled in for you if you use `gopls bug` to file the issue.
|
||||
|
||||
### Capturing logs
|
||||
|
||||
### Capturing gopls logs
|
||||
For VSCode users, the gopls log can be found by going to `"View: Debug Console" -> "Output" -> "Tasks" -> "gopls"`. For other editors, you may have to directly pass a `-logfile` flag to gopls.
|
||||
|
||||
To increase the level of detail in your logs, start gopls with the `-rpc.trace` flag. To start a debug server that will allow you to see profiles and memory usage, start gopls with `serve --debug=localhost:6060`. See the editor configurations section below for information on how to pass these flags via your editor.
|
||||
To increase the level of detail in your logs, start `gopls` with the `-rpc.trace` flag. To start a debug server that will allow you to see profiles and memory usage, start `gopls` with `serve --debug=localhost:6060`.
|
||||
|
||||
If you are unsure of how to pass a flag to `gopls` through your editor, please see the [documentation for your editor](user.md#editors).
|
||||
|
||||
### Restart your editor
|
||||
Once you have filed an issue, you can then try to restart your gopls instance by restarting your editor. In many cases, this will correct the problem. In VSCode, the easiest way to restart the language server is by opening the command palette (Ctrl + Shift + P) and selecting `"Go: Restart Language Server"`. You can also reload the VSCode instance by selecting `"Developer: Reload Window"`.
|
||||
|
||||
Once you have filed an issue, you can then try to restart your `gopls` instance by restarting your editor. In many cases, this will correct the problem. In VSCode, the easiest way to restart the language server is by opening the command palette (Ctrl + Shift + P) and selecting `"Go: Restart Language Server"`. You can also reload the VSCode instance by selecting `"Developer: Reload Window"`.
|
||||
|
||||
@ -1,12 +1,13 @@
|
||||
# gopls user documentation
|
||||
# User guide
|
||||
|
||||
Most of this document is written from the perspective of VSCode as at the time of writing it was the most popular editor. Most of the features described work in any editor and the settings should be easy to translate to the specifics of each editor integration.
|
||||
For instance, anything in the configuration section has a specific layout, but the exact place you define the settings will depend on the editor, and the syntax of the declaration may be in a different language.
|
||||
##### If you're having issues with `gopls`, please see the [troubleshooting guide](troubleshooting.md).
|
||||
|
||||
This document focuses on VSCode, as at the time of writing, VSCode is the most popular Go editor. However, most of the features described here work in any editor. The settings should be easy to translate to those of another editor's LSP client. The differences will be in the place where you define the settings and the syntax with which you declare them.
|
||||
|
||||
## Editors
|
||||
|
||||
The following is the list of editors with known integrations.
|
||||
If you know of an editor not in this list that works, please let us know.
|
||||
If you use `gopls` with an editor that is not on this list, please let us know by [filing an issue](#new-issue) or [modifying this documentation](#contribute).
|
||||
|
||||
* [VSCode](vscode.md)
|
||||
* [Vim / Neovim](vim.md)
|
||||
@ -14,17 +15,17 @@ If you know of an editor not in this list that works, please let us know.
|
||||
* [Acme](acme.md)
|
||||
* [Sublime Text](subl.md)
|
||||
|
||||
## Installing
|
||||
## Installation
|
||||
|
||||
For the most part you should not need to install or update gopls, your editor should handle that step for you.
|
||||
For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you.
|
||||
|
||||
If you do want to get the latest stable version of gopls, change to any directory that is not in either your GOPATH or a module (a temp directory is fine), and use
|
||||
If you do want to get the latest stable version of `gopls`, change to any directory that is both outside of your `GOPATH` and outside of a module (a temp directory is fine), and run
|
||||
|
||||
```sh
|
||||
go get golang.org/x/tools/gopls@latest
|
||||
```
|
||||
|
||||
**do not** use the `-u` flag, as it will update your dependencies to incompatible versions.
|
||||
**Do not** use the `-u` flag, as it will update your dependencies to incompatible versions.
|
||||
|
||||
If you see this error:
|
||||
|
||||
@ -38,106 +39,55 @@ GO111MODULE=on go get golang.org/x/tools/gopls@latest
|
||||
```
|
||||
|
||||
|
||||
## Configuring
|
||||
## Configurations
|
||||
|
||||
gopls can be configured in a few different ways:
|
||||
* environment variables
|
||||
### Environment variables
|
||||
|
||||
These are often inherited from the editor that launches gopls, and sometimes the editor has a way to add or replace values before launching.
|
||||
These are often inherited from the editor that launches `gopls`, and sometimes the editor has a way to add or replace values before launching. For example, VSCode allows you to configure `go.toolsEnvVars`.
|
||||
|
||||
gopls does not use the environment directly, but it can use `go list` extensively underneath, so the standard Go environment is important.
|
||||
Configuring your environment correctly is important, as `gopls` relies on the `go` command.
|
||||
|
||||
* command line
|
||||
### Command line flags
|
||||
|
||||
See the [command line](#command-line) section for more information about the flags you might specify.
|
||||
All editors support some way of adding flags to gopls, for the most part you should not need to do this unless you have very unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps) gopls behavior.
|
||||
See the [command line page](command-line.md) for more information about the flags you might specify.
|
||||
All editors support some way of adding flags to `gopls`, for the most part you should not need to do this unless you have very unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps) `gopls` behavior.
|
||||
|
||||
* editor settings
|
||||
### Editor settings
|
||||
|
||||
For the most part these will be things that control how the editor interacts with or uses the results of gopls, not things that modify gopls itself. This means they are not standardized across editors, and you will have to look at the specific instructions for your editor integration to change them.
|
||||
For the most part these will be settings that control how the editor interacts with or uses the results of `gopls`, not modifications to `gopls` itself. This means they are not standardized across editors, and you will have to look at the specific instructions for your editor integration to change them.
|
||||
|
||||
* the set of workspace folders
|
||||
#### The set of workspace folders
|
||||
|
||||
This is one of the most important pieces of configuration. It is the set of folders that gopls considers to be "roots" that it should consider files to be a part of.
|
||||
This is one of the most important pieces of configuration. It is the set of folders that gopls considers to be "roots" that it should consider files to be a part of.
|
||||
|
||||
If you are using modules there should be one of these per go.mod that you are working on.
|
||||
If you do not open the right folders, very little will work. **This is the most common mis-configuration of gopls that we see**.
|
||||
If you are using modules there should be one of these per go.mod that you are working on.
|
||||
If you do not open the right folders, very little will work. **This is the most common misconfiguration of `gopls` that we see**.
|
||||
|
||||
* global configuration
|
||||
#### Global configuration
|
||||
|
||||
There should be a way of declaring global settings for gopls inside the editor.
|
||||
The settings block will be called "gopls" and contains a collection of controls for gopls that the editor is not expected to understand or control.
|
||||
There should be a way of declaring global settings for `gopls` inside the editor. The settings block will be called `"gopls"` and contains a collection of controls for `gopls` that the editor is not expected to understand or control.
|
||||
|
||||
In VSCode this would be a section in your settings file that might look like
|
||||
In VSCode, this would be a section in your settings file that might look like this:
|
||||
|
||||
```json5
|
||||
```json5
|
||||
"gopls": {
|
||||
"usePlaceholders": true, // add parameter placeholders when completing a function
|
||||
"wantCompletionDocumentation": true // for documentation in completion items
|
||||
"usePlaceholders": true,
|
||||
"completeUnimported": true
|
||||
},
|
||||
```
|
||||
```
|
||||
|
||||
See the [settings](#settings) for more information about what values you can set here.
|
||||
See [Settings](settings.md) for more information about the available configurations.
|
||||
|
||||
* per workspace folder configuration
|
||||
#### Workspace folder configuration
|
||||
|
||||
This contains exactly the same set of values that are in the global configuration, but it is fetched for every workspace folder separately.
|
||||
The editor can choose to respond with different values per folder, but this is
|
||||
This contains exactly the same set of values that are in the global configuration, but it is fetched for every workspace folder separately. The editor can choose to respond with different values per-folder.
|
||||
|
||||
## Command line support
|
||||
|
||||
### Settings
|
||||
Much of the functionality of `gopls` is available through a command line interface.
|
||||
|
||||
**buildFlags** *array of strings*
|
||||
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.
|
||||
|
||||
This is the set of flags passed on to the build system when invoked.
|
||||
It is applied to things like `go list` queries when discovering files.
|
||||
The most common use is to set `-tags`.
|
||||
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.
|
||||
|
||||
**env** *map of string to value*
|
||||
|
||||
This can be used to add environment variables. These will not affect gopls itself, but will be used for any external commands it invokes.
|
||||
|
||||
**experimentalDisabledAnalyses** *map*
|
||||
|
||||
The keys in this map indicate analysis passes that should be disabled.
|
||||
You can use this to turn off analyses that you feel are not useful in the editor.
|
||||
The values of the map are ignored.
|
||||
|
||||
**hoverKind** *string*
|
||||
|
||||
This controls the information that appears in the hover text.
|
||||
It must be one of:
|
||||
* "NoDocumentation"
|
||||
* "SingleLine"
|
||||
* "SynopsisDocumentation"
|
||||
* "FullDocumentation"
|
||||
* "Structured"
|
||||
|
||||
**deepCompletion** *boolean*
|
||||
|
||||
If true this turns on the ability to return completions from deep inside relevant entities, rather than just the locally accessible ones, for instance it may suggest fields of local variables that match.
|
||||
|
||||
**usePlaceholders** *boolean*
|
||||
|
||||
If true then completion responses may contain placeholders inside their snippets.
|
||||
|
||||
**completionDocumentation** *boolean*
|
||||
|
||||
If true it indicates that the user wants documentation with their completion responses.
|
||||
|
||||
**completeUnimported** *boolean*
|
||||
|
||||
If true the completion engine is allowed to make suggestions for packages that you do not currently import.
|
||||
|
||||
## Command line
|
||||
|
||||
gopls supports much of its functionality on the command line as well.
|
||||
|
||||
It does this for two main reasons, firstly so that you do not have to reach for another tool to do something gopls can already do in your editor.
|
||||
It also makes it easy to reproduce behavior seen in the editor from a command line you can ask others to run.
|
||||
|
||||
It is not a goal of gopls to be a high performance command line tool, its command line it intended for single file/package user interaction speeds, not bulk processing.
|
||||
|
||||
<!--- TODO: command line
|
||||
detailed command line instructions, use cases and flags
|
||||
--->
|
||||
For more information, see the `gopls` [command line page](command-line.md).
|
||||
|
||||
@ -8,12 +8,16 @@ Use the [VSCode-Go] plugin, with the following configuration:
|
||||
"editor.snippetSuggestions": "none",
|
||||
"editor.formatOnSave": true,
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.organizeImports": true
|
||||
"source.organizeImports": true,
|
||||
}
|
||||
},
|
||||
"gopls": {
|
||||
"usePlaceholders": true, // add parameter placeholders when completing a function
|
||||
"wantCompletionDocumentation": true // for documentation in completion items
|
||||
|
||||
// ----- Experimental settings -----
|
||||
"completeUnimported": true, // autocomplete unimported packages
|
||||
"watchChangedFiles": true, // watch file changes outside of the editor
|
||||
"deepComplete": true, // deep completion
|
||||
},
|
||||
"files.eol": "\n", // formatting only supports LF line endings
|
||||
```
|
||||
@ -38,9 +42,9 @@ To enable more detailed debug information, add the following to your VSCode sett
|
||||
],
|
||||
```
|
||||
|
||||
See the [section on command line](user.md#command-line) arguments for more information about what these do, along with other things like `--logfile=auto` that you might want to use.
|
||||
See the section on [command line](command-line.md) arguments for more information about what these do, along with other things like `--logfile=auto` that you might want to use.
|
||||
|
||||
You can disable features through the `"go.languageServerExperimentalFeatures"` section of the config. An example of a feature you may want to disable is `"documentLink"`, which opens Godoc links when you click on import statements in your file.
|
||||
You can disable features through the `"go.languageServerExperimentalFeatures"` section of the config. An example of a feature you may want to disable is `"documentLink"`, which opens [`godoc.org`](https://godoc.org) links when you click on import statements in your file.
|
||||
|
||||
|
||||
[VSCode-Go]: https://github.com/microsoft/vscode-go
|
||||
|
||||
Loading…
Reference in New Issue
Block a user