[release] docs: update GOPATH, modules, and gopls documentation
This change finishes the general work of updating the documentation. The
GOPATH, modules, and gopls pages are finalized. I expect that I still
have 3 CLs left in this set of changes:
(1) Generating settings and commands docs from the package.json
(2) A pass for proofreading, checking links, and other improvements
(3) A pass to remove and file issues for all TODOs
Let me know if there's anything else I'm missing here.
Change-Id: I0ba9c2be9cc92e32dc7bae4526745306ef49a503
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236840
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit 2ce0e4f034072097f9aeea8e9b67ff2e790dcb5b)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236977
diff --git a/docs/commands.md b/docs/commands.md
index 73f9a5b..c778e0b 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -21,6 +21,8 @@
## Detailed list
+<!--TODO(rstambler): Automatically generate this list using the package.json.-->
+
Below is a detailed list of commands. They are categorized into [code editing and generation](#code-editing-and-generation), [testing and benchmarking](#testing-and-benchmarking), [build, lint, and vet](#build-lint-and-vet), [miscellaneous](#miscellaneous), and [troubleshooting](#troubleshooting). You will find the [troubleshooting](#troubleshooting) commands helpful when diagnosing an issue with the extension (learn more in the [Troubleshooting documentation](troubleshooting.md)).
### Code editing and generation
@@ -32,7 +34,11 @@
<!--TODO(rstambler): Confirm exactly how this works.-->
Manually add an import to your file. See [Add import](features.md#add-import).
-#### [`Go: Add Package to Workspace`]()
+#### [`Go: Add Package to Workspace`]
+
+Add a package to the current workspace.
+
+<!--TODO(rstambler): Figure out how this command works, its use cases, and how it fits into modules.-->
#### [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags)
@@ -62,9 +68,13 @@
Generate unit tests for the current package. See [Generate unit tests](features.md#generate-unit-tests).
-#### [`Go: Extract to function`]()
+#### [`Go: Extract to function`](features.md#refactor)
-#### [`Go: Extract to variable`]()
+Extract the highlighted code to a function. Provided by the [`godoctor`](tools.md#godoctor) tool. Learn more about [refactoring](features.md#refactoring).
+
+#### [`Go: Extract to variable`](features.md#refactor)
+
+Extract the highlighted code to a local variable. Provided by the [`godoctor`](tools.md#godoctor) tool. Learn more about [refactoring](features.md#refactoring).
### Testing and benchmarking
@@ -72,23 +82,33 @@
Run the test function at the current cursor position in the file.
-#### [`Go: Subtest at Cursor`]()
+#### [`Go: Subtest at Cursor`](features.md#test-and-benchmark-in-the-editor)
-#### [`Go: Benchmark Function At Cursor`]()
+Run the subtest (`t.Run`) at the current cursor position in the file.
-#### [`Go: Debug Test At Cursor`]()
+#### [`Go: Benchmark Function At Cursor`](features.md#test-and-benchmark-in-the-editor)
+
+Run the benchmark at the current cursor position in the file.
+
+#### [`Go: Debug Test At Cursor`](features.md#debugging)
+
+Debug the test at the current cursor position.
#### [`Go: Test File`](features.md#test-and-benchmark-in-the-editor)
Run all of the tests in the current file.
-#### [`Go: Benchmark File`]()
+#### [`Go: Benchmark File`](features.md#test-and-benchmark-in-the-editor)
+
+Run all of the benchmarks in the current file.
#### [`Go: Test Package`](features.md#test-and-benchmark-in-the-editor)
-Run all of tests in the current package.
+Run all of the tests in the current package.
-#### [`Go: Benchmark Package`]()
+#### [`Go: Benchmark Package`](features.md#test-and-benchmark-in-the-editor)
+
+Run all of the benchmarks in the current package.
#### [`Go: Test Previous`](features.md#test-and-benchmark-in-the-editor)
@@ -98,33 +118,57 @@
Run all of the tests in the current workspace.
-#### [`Go: Cancel Running Tests]()
+#### [`Go: Cancel Running Tests`](features.md#test-and-benchmark-in-the-editor)
-#### [`Go: Toggle Test File`]()
+Cancel currently running tests.
-#### [`Go: Apply Cover Profile]()
+#### [`Go: Toggle Test File`](features.md#toggle-between-code-and-tests)
-#### [`Go: Toggle Test Coverage In Current Package`]()
+Toggle between a file and its corresponding test file.
+
+#### [`Go: Apply Cover Profile`](features.md#code-coverage)
+
+Apply a given [cover profile](https://blog.golang.org/cover) to the current file.
+
+#### [`Go: Toggle Test Coverage In Current Package`](features.md#code-coverage)
+
+Show [code coverage](features.md#code-coverage) in the current file.
### Build, lint, and vet
-#### [`Go: Build Current Package`]()
+#### [`Go: Build Current Package`](features.md#build-errors)
-#### [`Go: Lint Current Package`]()
+Build the current package and show build errors.
-#### [`Go: Vet Current Package`]()
+#### [`Go: Vet Current Package`](features.md#vet-errors)
-#### [`Go: Build Workspace`]()
+Show vet errors for the current package.
-#### [`Go: Lint Workspace`]()
+#### [`Go: Lint Current Package`](features.md#lint-errors)
-#### [`Go: Vet Workspace`]()
+Show lint errors for the current package.
-#### [`Go: Install Current Package`]()
+#### [`Go: Build Workspace`](features.md#build-errors)
+
+Build all of the packages in the current workspace and show build errors.
+
+#### [`Go: Vet Workspace`](features.md#vet-errors)
+
+Show vet errors for all of the packages in the current workspace.
+
+#### [`Go: Lint Workspace`](features.md#lint-errors)
+
+Show lint errors for all of the packages in the current workspace.
+
+#### `Go: Install Current Package`
+
+Install the current package and its dependencies.
### Miscellaneous
-#### [`Go: Restart Language Server`]()
+#### [`Go: Restart Language Server`](gopls.md)
+
+Use this command to restart the [language server](gopls.md) without reloading the VS Code window. This can be helpful if something seems goes wrong with the language server (for example, if you see incorrect error messages).
#### [`Go: Run on Go Playground`](features.md#go-playground)
@@ -134,13 +178,15 @@
#### `Go: Current GOPATH`
-See the current value of GOPATH. This is not equivalent to `go env GOPATH`, as your VS Code settings may have altered the value of `GOPATH` used by the extension.
+See the current value of GOPATH. This is not equivalent to `go env GOPATH`, as your VS Code settings may have altered the value of `GOPATH` used by the extension. This command is helpful when [troubleshooting](troubleshooting.md) the extension.
#### [`Go: Install/Update Tools`](tools.md)
Install or update the Go tools on which the extension depends. Tools can be installed or updated all at once, or individual tools can be selected.
-#### [`Go: Locate Configured Go Tools`]()
+#### [`Go: Locate Configured Go Tools`](troubleshooting.md#check-your-set-up)
+
+This command is helpful when [troubleshooting](troubleshooting.md) the extension. It prints out the environment variables and paths to the tools used by the extension. See an example of the command's output in the [troubleshooting documentation](troubleshooting.md#check-your-set-up).
[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
diff --git a/docs/features.md b/docs/features.md
index 9c581c1..6057552 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -26,6 +26,7 @@
* [Format and organize imports](#format-and-organize-imports)
* [Add import](#add-import)
* [Rename symbol](#rename-symbol)
+ * [Refactor](#refactor)
* [Code Generation](#code-generation)
* [Add or remove struct tags](#add-or-remove-struct-tags)
* [Generate interface implementation](#generate-interface-implementation)
@@ -127,6 +128,10 @@
This feature is not available if you are using Go modules without `gopls`, the Go language server.
+### Refactor
+
+Extract a piece of code to a local variable or to its own function using the [`Go: Extract to variable`](commands.md#go-extract-to-variable) and [`Go: Extract to function`](commands.md#go-extract-to-function) commands. These features are provided by the [`godoctor`](tools.md#godoctor) tool. These features do not work with Go modules, but they will be supported by [`gopls`] in the future (see [golang/go#37170](https://github.com/golang/go/issues/37170)).
+
## Code Generation
### Add or remove struct tags
@@ -194,3 +199,5 @@
### Go Playground
Export your current file to the [Go Playground](https://play.golang.org) via the `Go: Run On Go Playground` command. This is useful for quickly exporting code for an example.
+
+[`gopls`]: gopls.md
diff --git a/docs/gopath.md b/docs/gopath.md
index 7498595..de26575 100644
--- a/docs/gopath.md
+++ b/docs/gopath.md
@@ -1,26 +1,80 @@
# `GOPATH`
-At any point in time, you can run the command `Go: Current GOPATH` to see the GOPATH being used by the extension.
+The `GOPATH` environment variable is a fundamental part of writing Go code before the introduction of [Go modules]. It specifies the location of your workspace, and it defaults to `$HOME/go`. A `GOPATH` directory contains `src`, `bin`, and `pkg` directories. Your code is typically located in the `$GOPATH/src` directory.
-### GOPATH from the environment variable
-Out of the box, the extension uses the value of the environment variable `GOPATH`. From Go 1.8 onwards, if no such environment variable is set, then the default GOPATH as deciphered from the command `go env` is used.
+If you are not familiar with Go and `GOPATH`, please first read about [writing Go code with `GOPATH`](https://golang.org/doc/gopath_code.html#GOPATH).
-### GOPATH from `go.gopath` setting
-Setting `go.gopath` in User settings overrides the GOPATH that was derived from the above logic.
-Setting `go.gopath` in Workspace settings overrides the one from User settings.
-You can set multiple folders as GOPATH in this setting. Note that they should be `;` separated in Windows and `:` separated otherwise.
+## Overview
-### GOPATH from `go.inferGopath` setting
-Setting `go.inferGopath` overrides the value set in `go.gopath` setting. If `go.inferGopath` is set to true, the extension will try to infer the `GOPATH` from the path of the workspace i.e. the directory opened in `vscode`. It searches upwards in the path for the `src` directory, and sets `GOPATH` to one level above that. It will also include the global GOPATH. Run `go env GOPATH` to find out what your global GOPATH is.
+* [Check the value of `GOPATH`](#check-the-value-of-gopath)
+* [Setting `GOPATH`](#setting-gopath)
+* [Different `GOPATH`s for different projects](#different-gopaths-for-different-projects)
+* [Automatically inferring your `GOPATH`](#automatically-inferring-your-gopath)
+* [Install tools to a separate `GOPATH`](#install-tools-to-a-separate-gopath)
-For example, if your project looks like `/aaa/bbb/ccc/src/...`, then opening the directory `/aaa/bbb/ccc/src` (or anything below that) will cause the extension to search upwards, find the `src` component in the path, and set the `GOPATH` to one level above that i.e. `GOPATH=/aaa/bbb/ccc`.
+## Check the value of `GOPATH`
-This setting is useful when you are working on different Go projects which have different GOPATHs. Instead of setting the GOPATH in the workspace settings of each project or setting all the paths as `;`/`:` separated string, you can just set `go.inferGopath` to `true`and the extension uses the right GOPATH automatically.
+First, it's useful to quickly check that you are using the right `GOPATH`. Two commands report the `GOPATH` value used by the VS Code Go extension: (1) `Go: Current GOPATH`, or (2) `Go: Locate Configured Go Tools`. Use either of these commands to check which `GOPATH` the extension is using.
-### GOPATH for installing the Go tools using `go.toolsGopath`
+If the `GOPATH` value is incorrect, see the details below on how to configure it.
-The `go get` command installs Go tools in your GOPATH. To prevent the Go tools from cluttering your GOPATH, use the `go.toolsGopath` setting to provide a separate GOPATH to use just for the Go tools.
+## Setting `GOPATH`
-The first time you set `go.toolsGopath`, you will have to run `Go: Install/Update Tools` command so that the Go tools get installed in the provided location.
+If you have chosen not to use [Go modules], you will need to configure your `GOPATH`. Modules have largely eliminated the need for a `GOPATH`, so if you're interested in using them, taking a look at the [modules documentation](modules.md) for the VS Code Go extension.
-If `go.toolsGopath` is not set or if the Go tools are not found there, then the Go tools from the GOPATH derived from the logic described in the previous section are used. If not found in there as well, then they are looked for in the paths that are part of the PATH environment variable.
+Setting `GOPATH` is typically as simple as setting the environment variable once in your system's configuration. Take a look at the [Setting `GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH) Wiki page if you're unsure how to do this.
+
+By default, the extension uses the value of the environment variable `GOPATH`. If no such environment variable is set, the extension runs `go env` and uses the `GOPATH` provided in that output.
+
+Note that, much like a `PATH` variable, `GOPATH` can contain multiple directory paths, separated by `:` or `;`. This allows you to set different `GOPATH`s for different projects.
+
+Still, there are a number of cases in which you might want a more complicated `GOPATH` set-up. This document will explain how to configure and manage your `GOPATH` within the VS Code Go extension.
+
+## Different `GOPATH`s for different projects
+
+Setting [`go.gopath`](settings.md#gopath) in your [user settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) overrides the environment's `GOPATH` value.
+
+[Workspace settings](https://vscode.readthedocs.io/en/latest/getstarted/settings/) override user settings, so you can use the [`go.gopath`](settings.md#gopath) setting to set different `GOPATH`s for different projects. A `GOPATH` can also contain multiple directories, so this setting is not necessary to achieve this behavior.
+
+## Automatically inferring your `GOPATH`
+
+**NOTE: This feature only works in `GOPATH` mode, not in module mode.**
+
+The [`go.inferGopath`](settings.md#inferGopath) setting overrides the [`go.gopath`](settings.md#gopath) setting. If you set [`go.inferGopath`](settings.md#inferGopath) to `true`, the extension will try to infer your `GOPATH` based on the workspace opened in VS Code. This is done by searching for a `src` directory in your workspace. The parent of this `src` directory is then added to your [global `GOPATH`](#setting-gopath) (`go env GOPATH`).
+
+For example, say your global `GOPATH` is `$HOME/go`, but you are working in a repository with the following structure.
+
+```bash
+foo/
+└── bar
+ └── src
+ └── main.go
+```
+
+If you open the `foo` directory as your workspace root in VS Code, [`"go.inferGopath"`](settings.md#inferGopath) will set your `GOPATH` to `$HOME/go:/path/to/foo/bar`.
+
+This setting is useful because it allows you to avoid setting the `GOPATH` in the workspace settings of each of your projects.
+
+## Install tools to a separate `GOBIN`
+
+If you find yourself frequently switching between `GOPATH`s, you may have found that the extension prompts you to install tools for every `GOPATH`. You can resolve this by making sure your tool installations are on your `PATH`, or you can configure a separate directory for tool installation: `GOBIN`. This environment variable tells the `go` command where to install all binaries. Configure it by setting:
+
+```json5
+"go.toolsEnvVars": {
+ "GOBIN": "path/to/gobin"
+}
+```
+
+## Install tools to a separate `GOPATH`
+
+**NOTE: The following is only relevant if you are using a Go version that does not support [Go modules], that is, any version of Go before 1.11.**
+
+Before Go 1.11, the `go get` command installs tools and their source code to your `GOPATH`. Because this extension uses a lot of different tools, this can clutter up your `GOPATH`. If you wish to reduce this clutter, you can have the extension install tools do a different location. This also addresses the issue described above, when switching `GOPATHs` forces you to reinstall Go tools.
+
+This can be done via the [`"go.toolsGopath"`](settings.md#toolsGopath) setting. Use it to specify an alternate directory that the extension can use to install tools. After you set this value, be sure to run the `Go: Install/Update Tools` command so that the Go tools get installed to the provided location.
+
+The extension will fall back to your existing `GOPATH` if tools are not found in the [`go.toolsGopath`](settings.md#toolsGopath) directory.
+
+<!--TODO(rstambler): Should we deprecate this setting for Go > 1.11?-->
+
+[Go modules]: https://blog.golang.org/using-go-modules
diff --git a/docs/gopls.md b/docs/gopls.md
index ceff565..39c36f6 100644
--- a/docs/gopls.md
+++ b/docs/gopls.md
@@ -1,41 +1,102 @@
-# [`gopls`](golang.org/s/gopls), the Go language server
+# [`gopls`], the Go language server
-**Note: `gopls` only supports Go versions above 1.11.**
+[`gopls`] is the official Go [language server](https://langserver.org/) developed by the Go team. It was developed in response to the release of [Go modules], and it is the recommended approach when working with [Go modules] in VS Code.
-#### Install/Update the Go language server
+[`gopls`] is currently in an alpha state, so it is not enabled by default. Please note that [`gopls`] only supports Go versions above 1.12.
+<!--TODO(rstambler): Change this once we support 1.11 and 1.12 again.-->
-Ideally, you would see prompts to use/install/update the language server.
-Follow the prompts and the language server should get set up correctly.
-If you want to manually install/update the language server,
-- Ensure you have set `go.useLanguageServer` to `true` in your settings
-- Use the `Go: Install/Update Tools` command, select `gopls` from the list and press Ok.
+[`gopls`] has its own [documentation pages](https://github.com/golang/tools/tree/master/gopls/doc), and they should be treated as the source of truth for how to use [`gopls` in VS Code](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md).
+## Overview
-#### Settings to control the use of the Go language server
+* [Background](#background)
+* [Enable the language server](#enable-the-language-server)
+ * [Automatic updates](#automatic-updates)
+* [Configuration](#configuration)
+ * [Ignored settings](#ignored-settings)
+ * [`gopls` settings block](#gopls-settings-block)
+* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
+* [Additional resources](#additional-resources)
-Below are the settings you can use to control the use of the language server. You need to reload the VS Code window for any changes in these settings to take effect.
+<!--TODO(rstambler): Write a gopls troubleshooting section here or in the gopls VS Code docs.-->
-- Set `go.useLanguageServer` to `true` to enable the use of language server.
-- When using `gopls`, see the [recommended settings](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md).
-- Some of the features from the language server can be disabled if needed using the setting `go.languageServerExperimentalFeatures`. Below are the features you can thus control. By default, all are set to `true` i.e are enabled.
-```json
+## Background
+
+This extension functions by shelling out to a number of command-line tools. This introduces complexity, as each feature is provided by a different tool. Language servers enable all editors to support all programming languages without these individualized tools. They also provide speed improvements, as they can cache and reuse results.
+
+[`gopls`] is the official Go language server. Using `gopls` will enable the VS Code Go extension to provide high-quality Go support as the language evolves.
+
+To learn more about the context behind [`gopls`], you can watch the [Go pls, stop breaking my editor](https://www.youtube.com/watch?v=EFJfdWzBHwE) talk at GopherCon 2019.
+
+## Enable the language server
+
+To start using the language server, set [`"go.useLanguageServer": true`](settings.md#useLanguageServer) in your VS Code Go settings.
+
+You should see a prompt to install `gopls`. If you do not see a prompt, please run the `Go: Install/Update Tools` command and select `gopls`.
+
+### Automatic updates
+
+The `gopls` team releases new versions of `gopls` approximately once a month ([release notes](https://github.com/golang/go/issues/33030)). The Go extension will automatically detect that a new version has been released, and a pop-up will appear prompting you to update.
+
+If you would like to opt-out of these updates, set [`"go.useGoProxyToCheckForToolUpdates"`](settings.md#useGoProxyToCheckForToolUpdates) to `false`.
+
+## Configuration
+
+There are a number of VS Code Go settings for controlling the language server. These include:
+
+* [`"go.languageServerExperimentalFeatures"`](settings.md#languageServerExperimentalFeatures) allows you to disable certain features.
+ * `"diagnostics": false` disables diagnostic warnings from `gopls`. You may want to disable these if you don't like the diagnostics changing as you type.
+ * `"documentLink": false` disables document links. The reason to disable these is explained in [golang/go#39065](https://github.com/golang/go/issues/39065): the Ctrl+Click shortcut for clicking on a link collides with the Ctrl+Click shortcut for go-to-definition.
+
+ ```json5
"go.languageServerExperimentalFeatures": {
- "diagnostics": true,
- "documentLink": true
+ "diagnostics": false,
+ "documentLink": false
}
-```
-- Set `"go.languageServerFlags": ["-logfile", "path to a text file that exists"]` to collect logs in a log file.
-- Set `"go.languageServerFlags": ["-rpc.trace"]` to see the complete rpc trace in the output panel (`View` -> `Output` -> `gopls`)
+ ```
-#### Provide feedback on gopls
+* [`"go.languageServerFlags"`](settings.md#languageServerFlags) allows you to pass flags to the `gopls` process.
+ * The `-rpc.trace` flag enables verbose debug logging.
-If you find any problems using the `gopls` language server, please first check the [list of existing issues for gopls](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls) and update the relevant ones with your case before logging a new one at https://github.com/golang/go/issues
+ ```json5
+ "go.languageServerFlags": [
+ "-rpc.trace"
+ ]
+ ```
+### Ignored settings
-#### Helpful links for gopls
+A number of the extension's settings are not passed in to `gopls`. We are working on unifying all of the settings, but some may still be ignored. These include:
-- [Wiki for gopls](https://github.com/golang/tools/blob/master/gopls/doc/user.md)
-- [Recommended settings for VSCode when using gopls](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md)
-- [Troubleshooting for gopls](https://github.com/golang/go/wiki/gopls#troubleshooting)
-- [Known bugs with gopls](https://github.com/golang/go/wiki/gopls#known-issues)
-- [Github issues for gopls](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
+* [`"go.buildFlags"`](settings.md#buildFlags)
+<!--TODO(rstambler): Complete this list.-->
+
+These configurations can be passed to `gopls` via your environment or the `gopls.env` setting. Learn more in the [`gopls` VS Code documentation](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md#build-tags).
+
+### `gopls` settings block
+
+[`gopls`] exposes a lot more [additional configuration](https://github.com/golang/tools/blob/master/gopls/doc/settings.md). However, because [`gopls`] is in a state of rapid development and change, these settings change frequently. Therefore, we have not yet built these settings into the Go extension.
+
+As shown in the [`gopls` VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md), you can still configure these settings through VS Code by adding a `"gopls"` block to your `settings.json` file (Command Palette -> Preferences: Open Settings (JSON)). **You will see an `Unknown Configuration Setting` warning, but the settings will still work.** Add any settings there, and `gopls` will warn you if they are incorrect, unknown, or deprecated.
+
+A full list of `gopls` settings is available in the [`gopls` settings documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md).
+
+## Additional resources
+
+If you encounter an issue while using [`gopls`], take a look at these resources:
+
+* [VS Code user guide](https://github.com/golang/tools/blob/master/gopls/doc/vscode.md)
+* [Known issues](https://github.com/golang/tools/blob/master/gopls/doc/status.md#known-issues)
+* [Troubleshooting](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md)
+* [`gopls` issue tracker](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls)
+
+If you are unable to resolve your issue, please ask for help. Make sure to mention that you are using `gopls`. Here's how to ask for guidance:
+
+* [File a VS Code Go issue](https://github.com/golang/vscode-go/issues/new/choose). If it is a bug in `gopls`, we will transfer your issue to the [`gopls` issue tracker](https://github.com/golang/go/issues).
+* [File a `gopls` issue](https://github.com/golang/go/issues/new) directly.
+* Ask a question in the `#gopls` channel on [Gophers Slack].
+* Ask a question in the `#vscode` channel on [Gophers Slack].
+
+[Go modules]: https://blog.golang.org/using-go-modules
+[`gopls`]: https://golang.org/s/gopls
+[Gophers Slack]: https:/gophers.slack.com/
diff --git a/docs/modules.md b/docs/modules.md
index 82ec0bd..31ed4f2 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -1,47 +1,37 @@
# Modules
-The Go language server [gopls](https://golang.org/s/gopls/README.md) provides support for [Go modules](https://blog.golang.org/modules2019).
+This extension mostly supports [Go modules]. However, certain features have not been ported to work with modules. The reason for this is that the Go team is developing a language server, [gopls](gopls.md). This provides a comprehensive solution for [Go modules] support in all editors.
-Add the below in your [settings](https://code.visualstudio.com/docs/getstarted/settings) to use Go modules.
+However, as described in the [language server documentation](gopls.md), `gopls` is still in an alpha state, so it is **not yet** the default in VS Code Go. We understand that many users will not want to use alpha software, so this document describes how this extension works with [Go modules], **without the language server**.
-```json
-"go.useLanguageServer": true
-```
+To learn how to use the language server with modules in VS Code, read our [`gopls` documentation](gopls.md).
-> **Note**: You will be prompted to install the latest stable version of `gopls` as and when the Go tools team tag a new version as stable.
+## Overview
-Extra settings to fine tune `gopls` are available. Please see the [gopls documentation](https://golang.org/s/gopls/doc/vscode.md) for more information and recommended settings.
+* [Missing features](#missing-features)
+ * [Formatting](#formatting)
+ * [References and rename](#references-and-rename)
+* [Performance](#performance)
+ * [Autocompletion](#autocompletion)
-* [Known issues](https://golang.org/s/gopls/doc/status.md#known-issues) in VS Code when using `gopls`
+## Missing features
-* [Troubleshooting and reporting issues](https://golang.org/s/gopls/doc/troubleshooting.md)
+As mentioned above, not all Go tools have been ported to work with modules. **Many tools will never be ported, as they are being replaced by [`gopls`](gopls.md).** [golang/go#24661](https://golang.org/issues/24661) contains up-to-date information about modules support in various Go tools.
-In addition to the Go language server, VS Code extension may use additional [Go tools](tools.md) to provide features like code navigation, code completion, build, lint etc. Some tools may not have a good support for Go modules yet. Please report [an issue](https://github.com/microsoft/vscode-go/issues/new) if you encounter problems.
+### Formatting
+The default [formatting](features.md#format-and-organize-imports) tool, [`goreturns`](tools.md#formatting), has not been ported to work with modules. As a result, you will need to change your [`"go.formatTool"`](settings.md#formatTool) setting for [formatting and import organization support](features.md#format-and-organize-imports). We recommend changing the value to `"goimports"` instead. Other options are also available, and you can read about them in the [format tools documentation](tools.md#formatting).
-If you don't want to use the language server for any reason, then please know that not all the [Go tools](tools.md) that this extension depends on supports Go modules. https://golang.org/issues/24661 is the issue used by the Go tools team to track the update of Go modules support in various Go tools.
+<!--TODO(rstambler): I never thought about this before, but it seems like we should either change the default or do the port ourselves. I doubt it would take long.-->
-## FAQ
+### [References](features.md#find-references) and [rename](tools.md#rename)
-### Can I use the language server when using Go modules?
+The tools that provide these two features, [`guru`](tools.md#guru) and [`gorename`](tools.md#gorename), have not been updated for Go modules. Instead, they will be replaced by [`gopls`](gopls.md).
-Yes, you can and this is the path forward for module support in VS Code. Please be aware that the language server itself is in alpha mode with active development in progress. See the section right above this question for details.
+## Performance
-### Why is code navigation and code completion slow when using Go modules?
+[Go modules] introduced additional complexity to the way that Go tooling has to work. As a result, the performance of a number of tools is worse with modules enabled. Hopefully, you will not notice this too frequently.
-Code navigation and code completion definitely works better when using `gopls`. So, please give that a try.
+One case in which you may notice this is autocompletion. The best solution to this is to switch to [`gopls`](gopls.md), which makes use of an in-memory cache to provide results quickly.
-If you are not using the language server, then this is mostly due to the limitation of the tools that power these features which are `godef` and `gocode` respectively. The Go tools team at Google are working on a [language server](https://golang.org/s/gopls/README.md) which will be the long term solution for all language features.
-
-Please try out the language server as described in the first section of this page.
-
-If you don't want to use the language server then,
-- For slowness in code completion, log an issue in the [gocode repo](https://github.com/stamblerre/gocode).
-- For slowness in code navigation, log an issue in the [godef repo](https://github.com/rogpeppe/godef) or if you chosen to `gogetdoc` in your settings, then log an issue in the [gogetdoc repo](https://github.com/zmb3/gogetdoc)
-
-### Auto import no longer happens on file save. Why?
-
-If you are not using the language server, this extension uses [goreturns](https://github.com/sqs/goreturns) tool by default to format your files and auto import missing packages. Since this tool doesn't support modules, the auto import feature on file save no longer works.
-
-Add the setting `"go.formatTool": "goimports"` and then use `Go: Install/Update Tools` to install/update `goimports` as it has recently added support for modules.
-
+[Go modules]: https://blog.golang.org/using-go-modules
diff --git a/docs/settings.md b/docs/settings.md
index d8b63ec..824d565 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -62,3 +62,5 @@
"-config=${workspaceFolder}/config.toml"
]
```
+
+<!--TODO(rstambler): Automatically generate this list using the package.json.-->
diff --git a/docs/Smoke-Test.md b/docs/smoke-test.md
similarity index 100%
rename from docs/Smoke-Test.md
rename to docs/smoke-test.md
diff --git a/docs/tasks.md b/docs/tasks.md
index 44c20b9..daf2373 100644
--- a/docs/tasks.md
+++ b/docs/tasks.md
@@ -1,75 +1,86 @@
-# Using [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks) with Go
+# Using [VS Code Tasks] with Go
-Invoke `Tasks: Configure Task Runner` from the command palette.
+From the [VS Code Tasks] documentation:
-This will create a `tasks.json` file in your workspace's `.vscode` folder. Replace the contents of this file with:
+> Tasks in VS Code can be configured to run scripts and start processes so that . . . existing tools can be used from within VS Code without having to enter a command line or write new code. Workspace or folder specific tasks are configured from the tasks.json file in the .vscode folder for a workspace.
-```json
+To begin configuring tasks, run the `Tasks: Configure Task` command from the Command Palette (Ctrl+Shift+P).
+
+This will create a `tasks.json` file in your workspace's `.vscode` folder.
+
+Replace the contents of this file with the following and adjust the tasks as needed.
+
+<!--TODO(rstambler): Can the extension just provide these default tasks?-->
+
+```json5
{
- "version": "0.1.0",
- "command": "go",
- "isShellCommand": true,
- "showOutput": "silent",
- "tasks": [
- {
- "taskName": "install",
- "args": [ "-v", "./..."],
- "isBuildCommand": true
- },
- {
- "taskName": "test",
- "args": [ "-v", "./..."],
- "isTestCommand": true
- }
- ]
-}
-```
-```json
-{
- "version": "2.0.0",
- "type": "shell",
- "echoCommand": true,
- "cwd": "${workspaceFolder}",
- "tasks": [
- {
- "label": "rungo",
- "command": "go run ${file}",
- "group": {
- "kind": "build",
- "isDefault": true
- }
- },
- ]
-}
-
-```
-
-You can now invoke <kbd>ctrl/cmd</kbd>+<kbd>shift</kbd>+<kbd>b</kbd> to run `go install -v ./...` and report results in the output window, or <kbd>ctrl/cmd</kbd>+<kbd>shift</kbd>+<kbd>t</kbd> to run `go test -v ./...`.
-
-You can use this same technique to invoke other build and test tools. For example, to invoke makefile targets if your build is defined in a makefile, or to invoke tools like `go generate`.
-
-More on configuring tasks in VS Code can be found at https://code.visualstudio.com/docs/editor/tasks.
-
-You can define a specific task to run only some tests:
-
-```
-{
- "version": "0.1.0",
+ "version": "2.0.0",
+ "type": "shell",
"command": "go",
- "isShellCommand": true,
- "showOutput": "silent",
- "suppressTaskName": true,
+ "cwd": "${workspaceFolder}",
"tasks": [
{
- "taskName": "Full test suite",
- "args": [ "test", "v", "./..."]
+ "label": "install",
+ "args": ["install", "-v", "./..."],
+ "group": "build",
},
{
- "taskName": "Blog User test suite",
- "args": [ "test", "./...", "-test.v", "-test.run", "User"]
- }
- ]
+ "label": "run",
+ "args": ["run", "${file}"],
+ "group": "build",
+ },
+ {
+ "label": "test",
+ "args": ["test", "-v", "./..."],
+ "group": "test",
+ },
+ ],
}
```
-The above task would run all tests with `User` in their name.
+You can run these tasks via the `Tasks: Run Task` command or by using the Ctrl+Shift+B shortcut.
+
+You can also define additional tasks to run other commands, like `go generate`. Here's an example of a task to run only a specific test (`TestBlogUser`, in this case):
+
+```json5
+{
+ "label": "Blog User test suite",
+ "args": [ "test", "./...", "-test.run", "TestBlogUser"]
+}
+```
+
+If you want to invoke tools other than `go`, you will have to move the `"command": "go"` setting into the task objects. For example:
+
+```json5
+{
+ "version": "2.0.0",
+ "cwd": "${workspaceFolder}",
+ "tasks": [
+ {
+ "label": "install",
+ "command": "go",
+ "args": ["install", "-v", "./..."],
+ "group": "build",
+ "type": "shell",
+ },
+ {
+ "label": "run",
+ "command": "go",
+ "args": ["run", "${file}"],
+ "group": "build"
+ "type": "shell",
+ },
+ {
+ "label": "test",
+ "command": "go",
+ "args": ["test", "-v", "./..."],
+ "group": "test",
+ "type": "shell",
+ },
+ ],
+}
+```
+
+Learn more by reading the [VS Code Tasks] documentation.
+
+[VS Code Tasks]: https://code.visualstudio.com/docs/editor/tasks
diff --git a/docs/tools.md b/docs/tools.md
index 66428bd..203140e 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -22,6 +22,7 @@
* [`go-symbols`](#go-symbols)
* [`guru`](#guru)
* [`gorename`](#gorename)
+* [`godoctor`](#godoctor)
* [`delve`](#delve)
* [`gomodifytags`](#gomodifytags)
* [`goplay`](#goplay)
@@ -98,6 +99,12 @@
`gorename` does not have support for Go modules, so we recommend using [`gopls`] for this feature instead.
+### [`godoctor`](https://github.com/godoctor/godoctor)
+
+This tool provides the [refactoring](features.md#refactor) features.
+
+It does not have support for Go modules, so we expect that [`gopls`] will provide this feature instead ([golang/go#37170](https://github.com/golang/go/issues/37170)).
+
### [`delve`](https://pkg.go.dev/github.com/go-delve/delve?tab=overview)
This is the debugger for the Go language. It is used to provide the [debugging](debugging.md) features of this extension.
