docs: rewrite the main README

My goal in this change was to clean up the main README and make it a bit more welcoming. The structure is now oriented towards helping people get started and linking all of the pages in the docs/ folder. A lot of the current content is a bit too specific and fits better in the docs pages, so I copy-pasted a lot of text to the relevant pages. Follow-up CLs will involve cleaning up these other pages and smoothing out the content there. Change-Id: I905026d1b4efb3dbad3b7c41e2f234185dee51ed Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/236057 Reviewed-by: Hyang-Ah Hana Kim <[email protected]>
0xch4z · Jun 3, 2020 · 4bccab7 · 4bccab7
1 parent 6a61856
commit 4bccab7
Show file tree

Hide file tree

Showing 7 changed files with 213 additions and 204 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1 +1,3 @@
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+# Code of Conduct
+
+This project follows the [Go Community Code of Conduct](https://golang.org/conduct). If you encounter an issue, please mail [email protected].
diff --git a/README.md b/README.md
diff --git a/docs/commands.md b/docs/commands.md
@@ -29,3 +29,60 @@ One of `"gofmt"`, `"goimports"`, `"goreturns"`, and `"goformat"` (`goreturns` is
 ### 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.
+
+### lintFlags
+
+This setting can be used to pass additional flags to your lint tool of choice.
+
+Most linters can be configured via special configuration files, but you may still need to pass command-line flags. The configuration documentation for each supported linter is listed here:
+
+* [`staticcheck`](https://staticcheck.io/docs/#configuration)
+* [`golangci-lint`](https://golangci-lint.run/usage/configuration/)
+* [`revive`](https://github.com/mgechev/revive#command-line-flags)
+
+#### Examples
+
+Enable all [`golangci-lint`] linters and only show errors in new code:
+
+```json5
+"go.lintFlags": ["--enable-all", "--new"]
+```
+
+Configure `revive` to exclude `vendor` directories and apply extra configuration with a `config.toml` file:
+
+```json5
+"go.lintFlags": [
+    "-exclude=vendor/...",
+    "-config=${workspaceFolder}/config.toml"
+]
+```
+
+### Commands
+
+In addition to integrated editing features, the extension also provides several commands in the Command Palette for working with Go files:
+
+* `Go: Add Import` to add an import from the list of packages in your Go context
+* `Go: Current GOPATH` to see your currently configured GOPATH
+* `Go: Test at cursor` to run a test at the current cursor position in the active document
+* `Go: Test Package` to run all tests in the package containing the active document
+* `Go: Test File` to run all tests in the current active document
+* `Go: Test Previous` to run the previously run test command
+* `Go: Test All Packages in Workspace` to run all tests in the current workspace
+* `Go: Generate Unit Tests For Package` Generates unit tests for the current package
+* `Go: Generate Unit Tests For File` Generates unit tests for the current file
+* `Go: Generate Unit Tests For Function` Generates unit tests for the selected function in the current file
+* `Go: Install Tools` Installs/updates all the Go tools that the extension depends on
+* `Go: Add Tags` Adds configured tags to selected struct fields.
+* `Go: Remove Tags` Removes configured tags from selected struct fields.
+* `Go: Generate Interface Stubs` Generates method stubs for given interface
+* `Go: Fill Struct` Fills struct literal with default values
+* `Go: Run on Go Playground` Upload the current selection or file to the Go Playground
+
+You can access all of the above commands from the command palette (`Cmd+Shift+P` or `Ctrl+Shift+P`).
+
+A few of these are available in the editor context menu as an experimental feature as well. To control which of these commands show up in the editor context menu, update the setting `go.editorContextMenuCommands`.
+
+[`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
diff --git a/docs/debugging.md b/docs/debugging.md
@@ -1,10 +1,30 @@
-## Install delve
+# Debugging
 
-There are 2 ways to install delve
-- Run the command `Go: Install/Update Tools`, select `dlv`, press `Ok` to install/update delve
-- Or install it manually install delve as per the [Installation Instructions](https://github.com/go-delve/delve/tree/master/Documentation/installation).
+The Go debugger is [Delve]. The [Delve] repository has detailed instructions, so we recommend taking a look at the [Delve documentation](https://github.com/go-delve/delve/tree/master/Documentation).
 
-## Set up configurations in your settings
+## Table of Contents
+
+* [Features](#features)
+* [Set up](#set-up)
+  * [Installation](#installation)
+  * [Configuration](#configuration)
+* [Launch Configuration](#launch-configuration)
+* [Debugging in WSL](#debugging-in-wsl)
+* [Remote Debugging](#remote-debugging)
+* [Common Issues](#common-issues)
+
+## Set up
+
+[Delve] should be installed by default when you install this extension.
+
+### Installation
+
+You can also install it manually in one of two ways:
+
+1. Open the Command Palette (Ctrl+Shift+P), select `Go: Install/Update Tools`, and select `dlv`.
+2. Follow the [Delve installation instructions](https://github.com/go-delve/delve/tree/master/Documentation/installation).
+
+### Configuration
 
 The below settings are used by the debugger. You may not need to add/change any of them to have debugging working in simple cases, but do give them a read sometime
 - `go.gopath`. See [GOPATH in VS Code](gopath.md)
@@ -149,6 +169,10 @@ Enter the id of the process running your executable in the below snippet
 }
 ```
 
+## Debugging in WSL
+
+If using WSL on Windows, you will need the WSL 2 Linux kernel.  See [WSL 2 Installation](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install) and note the Window 10 build version requirements. 
+
 ## Remote Debugging
 
 To remote debug using VS Code, you must first run a headless Delve server on the target machine. The below examples assume
@@ -264,3 +288,5 @@ Check the version of delve api being used in the remote delve process i.e check
 #### Try using dlv from the terminal/command-line
 
 Add `"trace": "log"` to your debug configuration and debug in VS Code. This will send logs to the debug console where you can see the actual call being made to dlv. You can copy that and run it in your terminal
+
+[Delve]: https://github.com/go-delve/delve
diff --git a/docs/troubleshooting.md → docs/faq.md b/docs/troubleshooting.md → docs/faq.md
@@ -1,4 +1,4 @@
-## FAQ
+# Frequently Asked Questions
 
 **Q: I installed the plugin, but none of the features are working. Why?**
 
@@ -32,7 +32,7 @@ If you see an error of the form `command <command-name-here> not found`, it mean
 
 **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?**
+**Q: Shouldn't the formatting tools be using a tab size of 8?**
 
 **A:** The default tab size in VS Code is 4. To change this to 8 for Go files, add the below to your settings.
 ```json
@@ -119,3 +119,9 @@ features.
 **Q: How do I get the features/bug fixes that are implemented but not released yet? How do I get the beta version of the Go extension?**
 
 **A:** Install the [Go Nightly](nightly.md) extension.
+
+**Q: I am seeing out-of-date completion results.**
+
+If you are using the language server (`"go.useLanguageServer": true`), please file a [`gopls` issue](https://github.com/golang/go/issues/new).
+
+Otherwise, check the value of `"go.buildOnSave"`. If it is `"off"`, then you may not get fresh results from not-yet-built dependencies. Therefore, ensure you have built your dependencies manually in such cases.
diff --git a/docs/features.md b/docs/features.md
@@ -160,7 +160,7 @@ The vet tool used is the one provided by the `go` command: `go vet`.
 
 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.
+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"`](commands.md#lintTool) setting. To learn more about the different options, see the [documentation for diagnostic tools](tools.md#diagnostics).
 
 ## Testing
 

diff --git a/docs/gopls.md b/docs/gopls.md
@@ -1 +1,41 @@
-# `gopls`, the Go language server
+# [`gopls`](golang.org/s/gopls), the Go language server
+
+**Note: `gopls` only supports Go versions above 1.11.**
+
+#### Install/Update the Go language server
+
+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.
+
+
+#### Settings to control the use of the Go language server
+
+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.
+
+- 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
+  "go.languageServerExperimentalFeatures": {
+    "diagnostics": true,
+    "documentLink": true
+  }
+```
+- 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
+
+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
+
+
+#### Helpful links for gopls
+
+- [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)