[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 <[email protected]>
(cherry picked from commit 2ce0e4f)
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236977

Author: stamblerre

docs/commands.md

@@ -21,6 +21,8 @@ Finally, you can also see a full list by using a meta command: `Go: Show All Com
 
 ## 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 @@ Below is a detailed list of commands. They are categorized into [code editing an
 <!--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,33 +68,47 @@ Generate unit tests for the current file. See [Generate unit tests](features.md#
 
 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
 
 #### [`Go: Test Function at Cursor`](features.md#test-and-benchmark-in-the-editor)
 
 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)
+
+Run the subtest (`t.Run`) at the current cursor position in the file.
 
-#### [`Go: Benchmark Function At Cursor`]()
+#### [`Go: Benchmark Function At Cursor`](features.md#test-and-benchmark-in-the-editor)
 
-#### [`Go: Debug Test At Cursor`]()
+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 @@ Re-run the most recently executed test command.
 
 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)
+
+Cancel currently running tests.
+
+#### [`Go: Toggle Test File`](features.md#toggle-between-code-and-tests)
 
-#### [`Go: Toggle Test File`]()
+Toggle between a file and its corresponding test file.
 
-#### [`Go: Apply Cover Profile]()
+#### [`Go: Apply Cover Profile`](features.md#code-coverage)
 
-#### [`Go: Toggle Test Coverage In Current Package`]()
+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)
+
+Build the current package and show build errors.
+
+#### [`Go: Vet Current Package`](features.md#vet-errors)
+
+Show vet errors for the current package.
+
+#### [`Go: Lint Current Package`](features.md#lint-errors)
 
-#### [`Go: Lint Current Package`]()
+Show lint errors for the current package.
 
-#### [`Go: Vet Current Package`]()
+#### [`Go: Build Workspace`](features.md#build-errors)
 
-#### [`Go: Build Workspace`]()
+Build all of the packages in the current workspace and show build errors.
 
-#### [`Go: Lint Workspace`]()
+#### [`Go: Vet Workspace`](features.md#vet-errors)
 
-#### [`Go: Vet Workspace`]()
+Show vet errors for all of the packages in the current workspace.
 
-#### [`Go: Install Current Package`]()
+#### [`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 @@ Upload the current selection or file to the Go Playground ([play.golang.org](htt
 
 #### `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

docs/features.md

@@ -26,6 +26,7 @@ Please see the [Tools documentation](tools.md) for details on how to troubleshoo
   * [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 @@ Rename all occurrences of a symbol in your workspace. This feature is provided b
 
 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 @@ This extension offers debugging of Go programs. See the [debugging documentation
 ### 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

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