docs: update gopls related documentation (#3203)

docs/All-Settings-&-Commands-in-Visual-Studio-Code-Go-extension.md

@@ -1,9 +1,9 @@
 You can view the Visual Studio Code settings for the Go extension along with their *default* values and description in the product itself
 
-1. Press `Ctrl+Shift+X` or `Cmd+Shift+X` to open the Extensions viewlet
-2. Find the Go extension, click on it to open the Extension Editor
+1. Press `Ctrl+Shift+X` or `Cmd+Shift+X` to open the Extensions viewlet.
+2. Find the Go extension, click on it to open the Extension Editor.
 3. Click on the `Contributions` tab.
-4. Scroll away
+4. Scroll away.
 
 ![ext](https://user-images.githubusercontent.com/16890566/30246497-9d6cc588-95b0-11e7-87dd-4bd1b18b139f.gif)
 

docs/Features-for-Go-in-VS-Code.md

@@ -1,33 +1,36 @@
+**NOTE:** If `go.useLanguageServer` is enabled, many of the following features will be
+offered through the Go language server `gopls`.
+
 ### IntelliSense
 
-- Auto Completion of symbols as you type (using `gocode`)
-- Signature Help for functions as you type (using `gogetdoc` or `godef`+`godoc`)
-- Quick Info on the symbol as you hover over it (using `gogetdoc` or `godef`+`godoc`)
+- 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`)
 
 ### Code Navigation
 
-- Go to or Peek Definition of symbols (using `gogetdoc` or `godef`+`godoc`)
-- Find References of symbols and Implementations of interfaces (using `guru`)
-- Go to symbol in file or see the file outline (using `go-outline`)
-- Go to symbol in workspace (using `go-symbols`)
+- 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.
 
 ### Code Editing
 
 - Code Snippets for quick coding
-- Format code on file save as well as format manually (using `goreturns` or `goimports` or `gofmt`)
-- Symbol Rename (using `gorename`. Note: For Undo after rename to work in Windows you need to have `diff` tool in your path)
-- Add Imports to current file (using `gopkgs`)
+- 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`)
 
 ### Diagnostics
 
 - 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
-- Lint-on-save to show linting errors as warnings (using `golint`, `gometalinter`, `megacheck`, `golangci-lint` or `revive`)
-- Semantic/Syntactic error reporting as you type (using `gotype-live`)
+- 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`)
 
 ### Testing
 

docs/Go-modules-support-in-Visual-Studio-Code.md

@@ -1,27 +1,23 @@
-VS Code uses a host of [Go tools](Go-tools-that-the-Go-extension-depends-on.md) to provide features like code navigation, code completion, build, lint etc. 
+The Go language server [gopls](https://golang.org/s/gopls/README.md) provides support for [Go modules](https://blog.golang.org/modules2019).
 
-> ⚠️ These tools **do not** provide a good support for [Go modules](https://blog.golang.org/modules2019) yet. 
-
-The new language server [gopls](https://github.com/golang/go/wiki/gopls) does support modules. Add the below in your [settings](https://code.visualstudio.com/docs/getstarted/settings) to use it.
+Add the below in your [settings](https://code.visualstudio.com/docs/getstarted/settings) to use Go modules.
 
 ```json
 "go.useLanguageServer": true
 ```
 
 > **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.
 
-Known issues in VS Code when using `gopls`:
+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.
+
+* [Known issues](https://golang.org/s/gopls/doc/status.md#known-issues) in VS Code when using `gopls`
 
-- Completion of unimported packages doesnt work
-- Find references and rename only work in a single package
-- For more, see 
-    - [Known issues with gopls](https://github.com/golang/go/wiki/gopls#known-issues) 
-	- Issues in this repo with the label [go-modules](https://github.com/Microsoft/vscode-go/issues?q=is%3Aopen+is%3Aissue+label%3Ago-modules)
+* [Troubleshooting and reporting issues](https://golang.org/s/gopls/doc/troubleshooting.md)
 
-To troubleshoot the language server, please see [Troubleshooting gopls](https://github.com/golang/go/wiki/gopls#troubleshooting)
+In addition to the Go language server, VS Code extension may use additional [Go tools](Go-tools-that-the-Go-extension-depends-on.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.
 
 
-If you don't want to use the language server for any reason, then please know that not all the [Go tools](Go-tools-that-the-Go-extension-depends-on.md) that this extension depends on supports Go modules. https://github.com/golang/go/issues/24661 is the issue used by the Go tools team to track the update of Go modules support in various Go tools.
+If you don't want to use the language server for any reason, then please know that not all the [Go tools](Go-tools-that-the-Go-extension-depends-on.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.
 
 ## FAQ
 
@@ -31,11 +27,12 @@ Yes, you can and this is the path forward for module support in VS Code. Please
 
 ### Why is code navigation and code completion slow when using Go modules?
 
-Code navigation and code completion definitely works better when using the language server from Google. So, please give that a try. 
+Code navigation and code completion definitely works better when using `gopls`. So, please give that a try.
 
-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://godoc.org/golang.org/x/tools/cmd/gopls) which will be the long term solution for all language features.
+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)
@@ -46,6 +43,3 @@ If you are not using the language server, this extension uses [goreturns](https:
 
 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.
 
-
-
-

docs/Go-with-VS-Code-FAQ-and-Troubleshooting.md

@@ -30,7 +30,7 @@ If you see an error of the form `command <command-name-here> not found`, it mean
 
 **Q: Why do my spaces keep getting replaced with tabs when saving the file?**
 
-**A:** Because the formatting tools used by this extension either `goreturns`, `goimports` or `gofmt` all follow the rule of using tabs instead of spaces.
+**A:** Because the formatting tools used by this extension either `goreturns`, `goimports` or `gofmt` or `gopls` all follow the default Go formatting rule of using tabs instead of spaces.
 
 **Q: Shoudln't the formatting tools be using a tab size of 8?**
 
@@ -76,7 +76,7 @@ _Tip_: If you are looking for logs after doing a particular operation, first cle
 
 **Q: Auto-completions stopped working. What do I do?**
 - Check the logs for errors first. See the previous question on how to view logs from the extension.
-- If you are using the language server, then the dropdown for output pane in the previous step will have an entry for the language server. Check that out.
+- If you are using the language server, then the dropdown for output pane in the previous step will have an entry for the language server (i.e., `gopls`). Check that out.
 - If you are **not** using the language server,
      - and this is for symbols from external packages, then ensure they installed first. You can do this by either running `Go: Build Current Package` which will install all dependencies or install the dependencies manually yourself using `go install`.
      - If it still doesnt work, run `gocode close` or `gocode exit` in a terminal and try again. Use `gocode-gomod` instead of `gocode` if you are using Go modules.
@@ -85,9 +85,32 @@ _Tip_: If you are looking for logs after doing a particular operation, first cle
      - If you see expected results in the terminal, but not in VS Code, log an issue in the [vscode-go](https://github.com/Microsoft/vscode-go) repo, else 
 log an issue in the [gocode](https://github.com/mdempsky/gocode) repo. If you are using Go modules, log the issue in https://github.com/stamblerre/gocode
 
-**Q: Why doesn't formatting doesn't work on file save?**
-
-**A:** Check the logs (View -> Output -> Log (Extension Host) from the drop down in the top right corner) for messages like "Formatting took too long" or "Format On Save feature could be aborted". If you find such a message, then chances are formatted was aborted because it took too long and so can affect the save experience. You can control this timeout using the setting `editor.formatOnSaveTimeout`
+**Q: File saving is sometimes slow or stuck running save participants.**
+
+**A:** You may noticed this problem because of the window popup with a
+message such as "Running Save Participants ...". This indicates the
+underlying tools used for file formatting or other code action such as
+package imports take longer than desired. Before 1.42, VS Code aborted
+the code action and skipped formatting, which resulted in file saving
+without expected formatting or import. After 1.42, VS Code changed to
+surface the issue and let users either wait or cancel the entire file
+save operation.
+
+There are many reasons that cause the underlying tools to misbehave.
+Please file [an issue](https://github.com/microsoft/vscode-go/issues/new)
+with information about your settings and, if possible, with the workspace
+structure (e.g., where is the workspace directory relative to `GOPATH`, 
+where is `go.mod`, in what directory you opened from the `code`, etc.).
+
+If you are using `gopls`, follow the
+[`gopls` troubleshooting documentation](https://github.com/golang/tools/blob/master/gopls/doc/troubleshooting.md) 
+to capture gopls traces and include them in the issue.
+
+Workarounds such as 1) disabling "On Save" features, or 2) canceling the
+slow file saving operation and retrying to save file without formatting
+using "Alt+k, s" ("File: Save Without Formatting" command) exist but should 
+be used as a last resort because this skips all the formatting and auto import
+features.
 
 **Q: My imports have red lines saying "package not found"**