[release] docs: fully flesh out features.md and tools.md
From https://golang.org/cl/235199 authored by Rebecca Stambler (rstambler@golang.org).
This change adds a lot more details about the features and configurations that are supported by the extension. Also fully list the Go tools used by the extension.
This change also adds a file for gopls without any content - coming soon in a future CL.
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/235199
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
(cherry picked from commit a9811b683ca4bf82e9f84dd6fa636eef21ada6d9)
Change-Id: Ieabfd3db934314c99643d2a345f19ce54360837f
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236745
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 112dd45..0000000
--- a/docs/README.md
+++ /dev/null
@@ -1,9 +0,0 @@
-- How to contribute? [Build, Debug and/or SideLoad the Go extension](contributing.md)
-- [Go tools that the Go extension depends on](tools.md)
-- [GOPATH in the VS Code Go extension](gopath.md)
-- [Settings & Commands in Visual Studio Code Go extension](commands.md)
-- [Debugging Go Code Using VS Code](debugging.md)
-- [Release Notes](../CHANGELOG.md)
-
-
-See the [FAQ](troubleshooting.md).
\ No newline at end of file
diff --git a/docs/commands.md b/docs/commands.md
index 5647d8f..876d8b8 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -1,6 +1,6 @@
# Settings and Commands
-To view a complete list of the commands settings for this extension:
+To view a complete list of the commands and settings for this extension:
1. Navigate to the Extensions view (Ctrl+Shift+X).
2. Find the Go extension, click on it to open the Extension Editor.
@@ -13,3 +13,19 @@
## Settings
You can configure your settings by modifying your [User or Workspace Settings](https://code.visualstudio.com/docs/getstarted/settings). To navigate to your settings, open the Command Palette (Ctrl+Shift+P) and search for "settings". The simplest way to modify your settings is through "Preferences: Open Settings (UI)".
+
+**NOTE: Most of these settings don't apply if you are using [`gopls`](gopls.md). Learn more about `gopls`-specific settings in this [documentation](https://github.com/golang/tools/blob/master/gopls/doc/settings.md).**
+
+A list of popular and notable settings can be found below.
+
+### docsTool
+
+One of `"godoc"`, `"gogetdoc"`, or `"guru"` (`gogetdoc` is the default). This is the tool used by the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover) features. See more information about each of these tools in the [Documentation](tools.md#Documentation) section.
+
+### formatTool
+
+One of `"gofmt"`, `"goimports"`, `"goreturns"`, and `"goformat"` (`goreturns` is the default). This is the tool used by the [formatting and import organization](features.md#formatting-and-import-organization) features. See more information about each of these tools in the [Formatting](tools.md#Formatting) section.
+
+### lintTool
+
+One of `"golint"`, `"staticcheck"`, `"golangci-lint"`, and `"revive"` (`golint` is the default). This is the tool used by the [lint-on-save](features.md#lint-on-save) feature. See more information about each of these tools in the [Diagnostics](tools.md#Diagnostics) section.
diff --git a/docs/features.md b/docs/features.md
index 2662cf1..f646327 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,40 +1,183 @@
-**NOTE:** If `go.useLanguageServer` is enabled, many of the following features will be
-offered through the Go language server `gopls`.
+# Features
-### IntelliSense
+This document describes the features supported by this extension.
-- Auto Completion of symbols as you type (using `gocode` or `gopls`)
-- Signature Help for functions as you type (using `gogetdoc` or `godef`+`godoc` or `gopls`)
-- Quick Info on the symbol as you hover over it (using `gogetdoc` or `godef`+`godoc` or `gopls`)
+If you are using the Go language server, `gopls`, please the [gopls documentation](gopls.md) instead. (You can check if you are using `gopls` by opening your VS Code settings and checking if `go.useLanguageServer` is set to `true`.)
-### Code Navigation
+If you are using Go modules without the language server, some of the below features will not be available.
-- Go to or Peek Definition of symbols (using `gogetdoc` or `godef`+`godoc` or `gopls`)
-- Find References of symbols and Implementations of interfaces (using `guru` or `gopls`)
-- Go to symbol in file or see the file outline (using `go-outline` or `gopls`)
-- Go to symbol in workspace (using `go-symbols` or `gopls`)
-- Toggle between a Go program and the corresponding test file.
+Please see the [Tools](tools.md) documentation for details on how to troubleshoot and adjust your settings.
-### Code Editing
+## Table of Contents
-- Code Snippets for quick coding
-- Format code on file save as well as format manually (using `goreturns` or `goimports` or `gofmt` or `gopls`)
-- Symbol Rename (using `gorename` or `gopls`. Note: If not using `gopls`, then for undo after rename to work in Windows you need to have `diff` tool in your path)
-- Add Imports to current file (using `gopkgs` or `gopls`)
-- Add/Remove Tags on struct fields (using `gomodifytags`)
-- Generate method stubs for interfaces (using `impl`)
-- Fill struct literals with default values (using `fillstruct`)
+* [IntelliSense](#intellisense)
+ * [Code completion](#code-completion)
+ * [Signature help](#signature-help)
+ * [Quick info on hover](#quick-info-on-hover)
+* [Code Navigation](#code-navigation)
+ * [Go to definition](#go-to-definition)
+ * [Go to symbol](#go-to-symbol)
+ * [Find references](#find-references)
+ * [Find interface implementations](#find-interface-implementations)
+ * [Document outline](#document-outline)
+ * [Toggle between code and tests](#toggle-between-code-and-tests)
+* [Code Editing](#code-editing)
+ * [Snippets](#snippets)
+ * [Format and organize imports](#format-and-organize-imports)
+ * [Add import](#add-import)
+ * [Rename symbol](#rename-symbol)
+* [Code Generation](#code-generation)
+ * [Add struct tags](#add-struct-tags)
+ * [Generate interface implementation](#generate-interface-implementation)
+ * [Generate unit tests](#generate-unit-tests)
+ * [Fill struct literals](#fill-struct-literals)
+* [Diagnostics](#diagnostics)
+ * [Build errors](#build-errors)
+ * [Vet errors](#vet-errors)
+ * [Lint errors](#lint-errors)
+* [Testing](#testing)
+ * [Test and benchmark in the editor](#test-and-benchmark-in-the-editor)
+ * [Code coverage](#code-coverage)
+* [Debugging](#debugging)
+* [Other](#other)
+ * [Go Playground](#go-playground)
-### Diagnostics
+## [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense)
-- Build-on-save to compile code and show build errors. (using `go build` and `go test`)
-- Vet-on-save to run `go vet` and show errors as warnings (`gopls`)
-- Lint-on-save to show linting errors as warnings (using `golint`, `gometalinter`, `megacheck`, `golangci-lint` or `revive` or `gopls`)
-- Semantic/Syntactic error reporting as you type (using `gotype-live` or `gopls`)
+This extension supports the following IntelliSense features:
-### Testing
+### Code completion
-- Run Tests under the cursor, in current file, in current package, in the whole workspace using either commands or codelens
-- Run Benchmarks under the cursor using either commands or codelens
-- Show code coverage either on demand or after running tests in the package.
-- Generate unit tests skeleton (using `gotests`)
\ No newline at end of file
+Completion results appear for symbols as you type. You can trigger this manually with the Ctrl+Space shortcut. This feature is provided by the [`gocode`](tools.md#gocode) tool.
+
+Autocompletion is also supported for packages you have not imported into your program. This feature is provided by the [`gopkgs`](#tools.md#gopkgs) tool.
+
+### Signature help
+
+Information about the signature of a function pops up as you type in its parameters. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+
+### Quick info on hover
+
+Documentation appears when you hover over a symbol. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+
+## [Code Navigation](https://code.visualstudio.com/docs/editor/editingevolved)
+
+### Go to definition
+
+Jump to or peek a symbol's declaration. This feature is provided by the [`gogetdoc`](tools.md#gogetdoc) tool, but it can also be provided by a combination of [`godef`](tools.md#godef) and [`godoc`](tools.md#godoc) (configured via the [`"go.docsTool"`](commands.md#docs-tool) setting).
+
+### Find references
+
+Find or go to the references of a symbol. This feature is provided the [`guru`](tools.md#guru) tool.
+
+This feature is not available if you are using Go modules without `gopls`, the Go language server.
+
+### Find interface implementations
+
+Find the concrete types that implement a given interface. This feature is provided by the [`guru`](tools.md#guru) tool.
+
+This feature is not available if you are using Go modules without `gopls`, the Go language server.
+
+### [Go to symbol](https://code.visualstudio.com/docs/editor/editingevolved#_go-to-symbol)
+
+Search for symbols in your file or workspace by opening the Command Palette (Ctrl+Shift+P) and typing `@` for symbols in the current file or `#` for symbols in the entire workspace.
+
+This feature is provided by the [`go-outline`](tools.md#go-outline) and [`go-symbols`](tools.md#go-symbols) tools.
+
+### Document outline
+
+See all the symbols in the current file in the VS Code's [Outline view](https://code.visualstudio.com/docs/getstarted/userinterface#_outline-view).
+
+This feature is provided by the [`go-outline`](tools.md#go-outline) tool.
+
+### Toggle between code and tests
+
+Quickly toggle between a file and its corresponding test file by using the `Go: Toggle Test File` command.
+
+## Code Editing
+
+### [Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets)
+
+Predefined snippets for quick coding. These snippets will pop up as completion suggestions as you type. Users can also define their own custom snippets (see [these instructions](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets)).
+
+### Format and organize imports
+
+Format code and organize imports, either manually or on save. The code is formatted by the [`gofmt`](tools.md#gofmt) tool, which is the standard for Go code. Imports are added automatically to your file via the [`goimports`](tools.md#goimports) tool, which is also an industry standard. By default, this extension also uses the [`goreturns`](tools.md#goreturns) tool, which automatically fills in default return values for functions.
+
+The behavior of the formatter can be configured via the [`"go.formatTool"`](#commands#format-tool) tool setting. Formatting can also be turned off by adding the following setting to your `settings.json` file:
+
+```json5
+"[go]": {
+ "editor.formatOnSave": false
+}
+```
+
+#### Add import
+
+Manually add a new import to your file through the `Go: Add Import` command.
+
+### [Rename symbol](https://code.visualstudio.com/docs/editor/refactoring#_rename-symbol)
+
+Rename all occurrences of a symbol in your workspace. This feature is provided by the [`gorename`](tools.md#gorename) tool.
+
+**Note**: For undo after rename to work on Windows, you need to have `diff` tool on your `PATH`.
+
+This feature is not available if you are using Go modules without `gopls`, the Go language server.
+
+## Code Generation
+
+### Add struct tags
+
+Use the `Go: Add Tags to Struct Fields` command to automatically generate or remove [tags](https://pkg.go.dev/reflect?tab=doc#StructTag) for your struct. This feature is provided by the [`gomodifytags`](tools.md#gomodifytags) tool.
+
+### Generate interface implementation
+
+Use the `Go: Generate Interface Stubs` command to automatically generate method stubs for a given interface. This feature is provided by the [`impl`](tools.md#impl) tool.
+
+### Generate unit tests
+
+Easily generate unit tests for your project by running one of the `Go: Generate Unit Tests for ...` commands. This can be done at a function, file, or package level. This feature is provided by the [`gotests`](tools.md#gotests) tool.
+
+### Fill struct literals
+
+Use the `Go: Fill struct` command to automatically fill a struct literal with its default values. This command is provided by the [`fillstruct`](tools.md#fillstruct).
+
+## Diagnostics
+
+### Build errors
+
+Build errors can be shown as you type or on save. Configure this behavior through the [`"go.buildOnSave"`](commands.md#buildOnSave) setting.
+
+By default, code is compiled using the `go` command (`go build`), but build errors as you type are provided by the [`gotype-live`](tools.md#gotype-live) tool.
+
+### Vet errors
+
+Vet errors can be shown on save. The vet-on-save behavior can also be configured through the [`"go.vetOnSave"`](commands.md#vetOnSave) setting.
+
+The vet tool used is the one provided by the `go` command: `go vet`.
+
+### Lint errors
+
+Much like vet errors, lint errors can also be shown on save. This behavior is configurable through the [`"go.lintOnSave"`](commands.md#lintOnSave) setting.
+
+The default lint tool is the one provided by the `go` command: `go lint`. However, custom lint tools can be easily used instead by configuring the [`"go.lintTool"`](tools.md#lintTool) setting.
+
+## Testing
+
+### Test and benchmark in the editor
+
+[Code lenses](https://code.visualstudio.com/blogs/2017/02/12/code-lens-roundup) allow users to easily run tests and benchmarks for a given function, file, package, or workspace. Alternatively, the same functionality is available through a set of commands: `Go: Test Function At Cursor`, `Go: Test File`, `Go: Test Package`, and `Go: Test All Packages in Workspace`.
+
+### Code Coverage
+
+Show code coverage in the editor, either after running a test or on-demand. This can be done via the commands: `Go: Apply Cover Profile` and `Go: Toggle Test Coverage in Current Package`.
+
+## [Debugging](debugging.md)
+
+This extension offers debugging of Go programs. See the [debugging documentation](debugging.md) for more information.
+
+## Other
+
+### Go Playground
+
+Quickly 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.
diff --git a/docs/gopls.md b/docs/gopls.md
new file mode 100644
index 0000000..157138a
--- /dev/null
+++ b/docs/gopls.md
@@ -0,0 +1 @@
+# `gopls`, the Go language server
diff --git a/docs/tools.md b/docs/tools.md
index d07029a..98d4ef6 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -1,36 +1,173 @@
-First, the Go extension for Visual Studio Code requires the Go tools to be already installed.
-See [Go's installation guide](https://golang.org/doc/install) and ensure the `go` command is available from your [`PATH`](https://en.wikipedia.org/wiki/PATH_(variable)).
+# Tools
-The Go extension for Visual Studio Code offers extra Go tools that are installed in the user's GOPATH. Some of them are responsible for general language features like code navigation, auto-completions, symbol search etc. Others, while helpful, are optional for the Go extension to provide day-to-day language support.
+This document describes the tools used to create the VS Code Go extension. Each feature is provided by a command-line tool written in Go, so if you experience an issue, it may be due to the underlying tool. Some tools are required for the functionality of the extension, while others are provide optional features.
-Below are the tools essential for the general features of this extension. If you have chosen to use the [Go language server](https://github.com/microsoft/vscode-go#go-language-server), then most of the below tools are no longer needed as the corresponding features will be provided by the language server. Eventually, once the language server is stable, we will move to using it and deprecate the use of individual tools below.
+Some of the features can be provided by multiple tools, and this can be configured through the extension's settings. For more details, see the [Documentation](#documentation), [Formatting](#formatting), and [Diagnostics](#diagnostics) sections below.
-**NOTE**: If you are using Go modules, then we strongly recommend using the Go language server as it performs much better than the tools below.
+<!--TODO(rstambler): Clarify which tools are still needed with gopls.-->
+**NOTE: If you are using the language server, [`gopls`], then most of the below tools are not needed. We strongly recommend using [`gopls`] if you are using Go modules, as it performs better.**
-- [gocode](http://github.com/stamblerre/gocode/) for auto-completion
-- [go-outline](https://github.com/ramya-rao-a/go-outline) for symbol search in the current file
-- [go-symbols](https://github.com/acroca/go-symbols) for symbol search in the current workspace
-- [gopkgs](https://github.com/uudashr/gopkgs) for auto-completion of unimported packages
-- [guru](https://golang.org/x/tools/cmd/guru) for the `Find all References` feature
-- [gorename](https://golang.org/x/tools/cmd/gorename) for renaming symbols
-- [goreturns](https://github.com/sqs/goreturns) or [goimports](https://golang.org/x/tools/cmd/goimports) for formatting code _(not needed if using language server)_
-- [godef](https://github.com/rogpeppe/godef) or [gogetdoc](https://github.com/zmb3/gogetdoc) for the `Go to Definition` feature _(not needed if using language server)_
-- [godoc](https://golang.org/x/tools/cmd/godoc) or [gogetdoc](https://github.com/zmb3/gogetdoc) for the documentation that appears on hover _(not needed if using language server)_
-- [golint](https://golang.org/x/lint/golint) or [megacheck](https://honnef.co/go/tools/) or [golangci-lint](https://github.com/golangci/golangci-lint) or [revive](https://github.com/mgechev/revive) for linting
-- [dlv](https://github.com/derekparker/delve/tree/master/cmd/dlv) for debugging
+## Installation
-If any of these tools are missing, you will see an "Analysis Tools Missing" warning in the bottom right corner of the editor. Clicking it will offer to install the missing tools for you.
+These tools will be installed by default when you install the extension. You can manually install or update all of these tools by running the `Go: Install/Update Tools` command. If any tools are missing, you will see an "Analysis Tools Missing" warning in the bottom-right corner of the editor, which will prompt you to install these tools.
-There are other features of this extension which you most probably wouldn't be using every day. For eg: Generating unit tests or generating stubs for interface or modify tags. The tools used for such features are:
+VS Code Go will install the tools to your `GOPATH` by default, but the tools will also be found if they are on your `PATH`. If you wish to use a separate `GOPATH` for tools only, you can configure this via the [`"go.toolsGopath"`](commands.md#toolsGopath) setting.
-- [gomodifytags](https://github.com/fatih/gomodifytags) for modifying tags on structs
-- [goplay](https://github.com/haya14busa/goplay/) for running current file in the Go playground
-- [impl](https://github.com/josharian/impl) for generating stubs for interfaces
-- [gotype-live](https://github.com/tylerb/gotype-live) for providing diagnostics as you type
-- [gotests](https://github.com/cweill/gotests/) for generating unit tests
-- [fillstruct](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct) for filling a struct literal with default values
+## Table of Contents
-You can install all these tools at once by running the command `Go: Install/Update Tools`. The same command can be used to keep the tools up to date as well as to re-compile in case you change the version of Go being used.
+* [Go toolchain](#go-toolchain)
+* [`gocode`](#gocode)
+* [`gopkgs`](#gopkgs)
+* [`go-outline`](#go-outline)
+* [`go-symbols`](#go-symbols)
+* [`guru`](#guru)
+* [`gorename`](#gorename)
+* [`delve`](#delve)
+* [`gomodifytags`](#gomodifytags)
+* [`goplay`](#goplay)
+* [`impl`](#impl)
+* [`gotests`](#gotests)
+* [`fillstruct`](#fillstruct)
+* [Documentation](#documentation)
+ * [`gogetdoc`]
+ * [`godef`]
+ * [`godoc`]
+* [Formatting](#formatting)
+ * [`goreturns`]
+ * [`goimports`]
+ * [`gofmt`]
+ * [`goformat`]
+* [Diagnostics](#diagnostics)
+ * [`gotype-live`]
+ * [`golint`]
+ * [`staticcheck`]
+ * [`golangci-lint`]
+ * [`revive`]
-If you wish to have the extension use a separate GOPATH for its tools, provide the desired location in the setting `go.toolsGopath`.
+### Go toolchain
+This extension requires you to install the Go toolchain, meaning that you have the `go` command on your [`PATH`](https://en.wikipedia.org/wiki/PATH_(variable)). To do this, follow [the Go installation guide](https://golang.org/doc/install).
+
+The [build-on-save](features.md#build-on-save) and [vet-on-save](features.md#vet-on-save) features are provided by the `go build` and `go vet` commands.
+
+### `gocode`
+
+Code completion is provided by `gocode`. It is the only tool that runs as a server. This enables it to provide completions faster, since a new process isn't starting per-keystroke. As a result, it is also easier to troubleshoot.
+
+To restart `gocode`, run `gocode close` on the command-line.
+
+To see `gocode`'s internals for debugging purposes, run:
+
+```bash
+gocode close
+gocode -s -debug
+```
+
+Then, type and trigger completions in your VS Code window as usual. You should see information printed in your terminal window.
+
+Different versions of `gocode` are used depending on your version of Go.
+
+* Go 1.8 and below: [nsf/gocode](https://github.com/nsf/gocode)
+* Go 1.9 and above: [mdempsky/gocode](https://github.com/mdempsky/gocode)
+* Go 1.11 and above, with modules enabled: [stamblerre/gocode](https://github.com/stamblerre/gocode)
+ * This version of `gocode` does not have any caching, so if you find it slow, consider using [gopls] instead.
+
+### [`gopkgs`](https://pkg.go.dev/github.com/uudashr/gopkgs?tab=overview)
+
+This tool provides autocompletion for unimported packages.
+
+### [`go-outline`](https://pkg.go.dev/github.com/ramya-rao-a/go-outline?tab=overview)
+
+This tool provides the [document outline](features.md#document-outline) feature, as well as the [go to symbol](features.md#go-to-symbol) in the current file feature.
+
+### [`go-symbols`](https://pkg.go.dev/github.com/acroca/go-symbols?tab=overview)
+
+This tool provides the [go to symbol](#go-to-symbol) in workspace feature.
+
+### [`guru`](https://pkg.go.dev/golang.org/x/tools/cmd/guru?tab=doc)
+
+This tool provides the [find references](features.md#find-references) and [find interface implementations](features.md#find-interface-implementations) features.
+
+It can also be used to provide the [go to definition](features.md#go-to-definition) via the [`"go.docsTool"`](commands.md#docsTool) setting (see [Customization](#Customization)).
+
+`guru` does not have support for Go modules, so we recommend using [`gopls`] for those features instead.
+
+### [`gorename`](https://pkg.go.dev/golang.org/x/tools/cmd/gorename?tab=doc)
+
+This tool provides the [rename symbol](features.md#rename-symbol) feature.
+
+`gorename` does not have support for Go modules, so we recommend using [`gopls`] for this feature instead.
+
+### [`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.
+
+### [`goplay`](https://pkg.go.dev/github.com/haya14busa/goplay?tab=overview)
+
+This tool provides support for the [`Go: Run on Go Playground`](features.md#go-playground) command.
+
+### [`gomodifytags`](https://pkg.go.dev/github.com/fatih/gomodifytags?tab=overview)
+
+This tool provides support for the [`Go: Add Tags to Struct Fields`](features.md#add-struct-tags) command.
+
+### [`impl`](https://github.com/josharian/impl)
+
+This tool provides support for the [`Go: Generate Interface Stubs`](features.md#generate-interface-implementation) command.
+
+### [`gotests`](https://github.com/cweill/gotests/)
+
+This tool provides support for the [`Go: Generate Unit Tests`](features.md#generate-unit-tests) set of commands.
+
+### [`fillstruct`](https://github.com/davidrjenni/reftools/tree/master/cmd/fillstruct)
+
+This tool provides support the [`Go: Fill struct`](features.md#fill-struct) command.
+
+### Documentation
+
+Documentation tools are used for the [go to definition](features.md#go-to-definition), [signature help](features.md#signature-help), and [quick info on hover](features.md#quick-info-on-hover). [`gogetdoc`] is used by default.
+
+If `gogetdoc` does not work for you, a combination of the [`godef`] and [`godoc`] tools can be used. [`guru`](#guru) can also be used, but only for the [go to definition](features.md#go-to-definition) behavior.
+
+Configure this via the [`"go.docsTool"`](commands.md#docsTool) setting.
+
+### Formatting
+
+Formatting tools are used by the [formatting and import organization](features.md#format-and-organize-imports) features.
+
+[`goreturns`] is used by default. It formats the file according to the industry standard [`gofmt`] style, organizes imports, and fills in default return values for functions. Other tools can be used for formatting instead; this can be configured with the [`"go.formatTool"`](commands.md#formatTool) setting.
+
+**NOTE: [`goreturns`] does not have support for Go modules, so we recommend using [`goimports`] or [`gopls`] instead.**
+
+Other format tool options include:
+
+* [`goimports`], which applies the default `gofmt` style and organizes imports, but without the behavior of filling in default return values
+* [`gofmt`] only formats the file, without import organization or filling in return values
+* [`goformat`] is a configurable version of [`gofmt`]
+
+### Diagnostics
+
+Diagnostic tools are used to surface errors and warnings in your code when you save your file or as you type.
+
+By default, [`gotype-live`], `go vet`, and [`golint`] are used to provide [build](#build-on-save), [vet](#vet-on-save), and [lint](#lint-on-save) errors. [`gotype-live`] provides build errors as you type, while `go build` can be used to show build errors only on save.
+
+**NOTE: [`gotype-live`] does not work with modules, so if you are using modules, we recommend using [`gopls`] instead.**
+
+Other lint tools can be used instead of [`golint`] by configuring the [`"go.lintTool"`](commands.md#lintTool) setting. Other options include:
+
+* [`staticcheck`]: This tool provides a great deal of useful checks that are not provided by `golint`. See the full list at [staticcheck.io/docs/checks](https://staticcheck.io/docs/checks). It is also officially supported by the [Go team at Google](https://staticcheck.io/sponsors).
+* [`golangci-lint`]: This tool combines a number of existing lint tools, including [staticcheck](#staticcheck), into one interface.
+* [`revive`]: This tool is an enhancement on top of [`golint`](#golint), and it provides additional checks.
+
+[`gogetdoc`]: https://pkg.go.dev/github.com/zmb3/gogetdoc?tab=overview
+[`godef`]: https://pkg.go.dev/github.com/rogpeppe/godef?tab=doc
+[`godoc`]: https://pkg.go.dev/golang.org/x/tools/godoc?tab=doc
+[`goreturns`]: https://pkg.go.dev/github.com/sqs/goreturns?tab=overview
+[`goimports`]: https://pkg.go.dev/golang.org/x/tools/cmd/goimports?tab=doc
+[`gofmt`]: https://golang.org/cmd/gofmt/
+[`goformat`]: https://pkg.go.dev/winterdrache.de/goformat?tab=overview
+[`gotype-live`]: https://pkg.go.dev/github.com/tylerb/gotype-live?tab=doc
+[`golint`]: https://pkg.go.dev/golang.org/x/lint/golint?tab=overview
+[`staticcheck`]: https://pkg.go.dev/honnef.co/go/tools/staticcheck?tab=overview
+[`golangci-lint`]: https://golangci-lint.run/
+[`revive`]: https://pkg.go.dev/github.com/mgechev/revive?tab=overview
+[`gopls`]: gopls.md
