gopls/doc: clean up and slightly reorganize documentation

This is a first CL to clean up the gopls documentation. The main changes
are cosmetic (to correct warnings found by the MD Lint VS Code
extension), though some parts are reworded or moved around. Ultimately,
more work needs to be done, particularly on the user guide and features
overview.

My current thinking is that we should rename settings.md to
configuration and move the configuration piece out of the user guide,
and also reorganize the user guide to be more "getting started"
oriented.

I'm still not sure where miscellaneous items should go (e.g., working on
the Go distribution itself)--I deleted the FAQ because it seemed useless
and is probably not the most discoverable, but it's the only place that
comes to mind so far.

Change-Id: I3689362067672f7ad8d5e8fd97ca9c7c45cfc8c4
Reviewed-on: https://go-review.googlesource.com/c/tools/+/280595
Trust: Rebecca Stambler <rstambler@golang.org>
Run-TryBot: Rebecca Stambler <rstambler@golang.org>
Reviewed-by: Robert Findley <rfindley@google.com>

gopls/doc/acme.md

@@ -1,7 +1,7 @@
 # Acme
 
-Use the experimental [`acme-lsp`], simply follow the [install steps]
+Use the experimental [`acme-lsp`] plugin.
+Get started by following the[installation guide].
 
 [`acme-lsp`]: https://github.com/fhs/acme-lsp
-[install steps]: https://github.com/fhs/acme-lsp#gopls
+[installation guide]: https://github.com/fhs/acme-lsp#gopls
-

gopls/doc/atom.md

@@ -1,6 +1,6 @@
 # Atom
 
-Install the [`ide-gopls`] package.
+Use the [`ide-gopls`] package.
 You will also need to install the [`atom-ide-ui`] package.
 
 [`ide-gopls`]: https://github.com/MordFustang21/ide-gopls

gopls/doc/command-line.md

@@ -1,15 +1,17 @@
 # Command line
 
-## Flags
+**Note: The `gopls` command-line is still experimental and subject to change at any point.**
 
-## Commands
+`gopls` exposes some (but not all) features on the command-line. This can be useful for debugging `gopls` itself.
 
-### Serve
+<!--TODO(rstambler): Generate this file.-->
 
-### Check
+Learn about available commands and flags by running `gopls help`.
 
-### Format
+Much of the functionality of `gopls` is available through a command line interface.
 
-<!--- TODO: command line
+There are two main reasons for this. The first is that we do not want users to rely on separate command line tools when they wish to do some task outside of an editor. The second is that the CLI assists in debugging. It is easier to reproduce behavior via single command.
-detailed command line instructions, use cases and flags
+
---->
+It is not a goal of `gopls` to be a high performance command line tool. Its command line is intended for single file/package user interaction speeds, not bulk processing.
+
+For more information, see the `gopls` [command line page](command-line.md).

gopls/doc/contributing.md

@@ -9,15 +9,35 @@ it is likely that we might already be working on a fix for your issue.
 
 ## Finding issues
 
-All `gopls` issues are labeled as such (see the [`gopls` label][issue-gopls]). Issues that are suitable for contributors are additionally tagged with the [`help-wanted` label][issue-wanted].
+All `gopls` issues are labeled as such (see the [`gopls` label][issue-gopls]).
+Issues that are suitable for contributors are additionally tagged with the
+[`help-wanted` label][issue-wanted].
 
-Before you begin working on an issue, please leave a comment that you are claiming it.
+Before you begin working on an issue, please leave a comment that you are
+claiming it.
 
 ## Getting started
 
-<!--- TODO: getting started
+Most of the `gopls` logic is actually in the `golang.org/x/tools/internal/lsp`
-Provide information to get contributors up and running here
+directory, so you are most likely to develop in the golang.org/x/tools module.
---->
+
+## Build
+
+To build a version of `gopls` with your changes applied:
+
+```bash
+cd /path/to/tools/gopls
+go install
+```
+
+To confirm that you are testing with the correct `gopls` version, check that
+your `gopls` version looks like this:
+
+```bash
+$ gopls version
+golang.org/x/tools/gopls master
+    golang.org/x/tools/gopls@(devel)
+```
 
 ## Getting help
 
@@ -30,21 +50,24 @@ about contributing in general.
 
 To run tests for just `gopls/`, run,
 
-```
+```bash
 cd /path/to/tools/gopls
 go test ./...
 ```
 
-But, much of the gopls work involves `internal/lsp` too, so you might want to
+But, much of the gopls work involves `internal/lsp` too, so you will want to
 run both:
 
-```
+```bash
 cd /path/to/tools
 cd gopls && go test ./...
 cd ..
 go test ./internal/lsp/...
 ```
 
+There is additional information about the `internal/lsp` tests in the
+[internal/lsp/tests `README`](https://github.com/golang/tools/blob/master/internal/lsp/tests/README.md).
+
 ### Regtests
 
 gopls has a suite of regression tests defined in the `./gopls/internal/regtest`
@@ -78,10 +101,11 @@ by the TryBots.
 
 ## Debugging
 
-<!--- TODO: debugging
+The easiest way to debug your change is to run can run a single `gopls` test
-actual debugging steps
+with a debugger.
-viewing telemetry
+
---->
+<!--TODO(rstambler): Add more details about the debug server and viewing
+telemetry.-->
 
 [issue-gopls]: https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Agopls "gopls issues"
 [issue-wanted]: https://github.com/golang/go/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3Agopls+label%3A"help+wanted" "help wanted"

gopls/doc/daemon.md

@@ -40,8 +40,9 @@ flag `-remote=auto` to the gopls process started by your editor. This will
 cause this process to auto-start the gopls daemon if needed, connect to it, and
 forward the LSP. For example, here is a reasonable gopls invocation, that sets
 some additional flags for easier [debugging](#debugging):
-```
+
-$ gopls -remote=auto -logfile=auto -debug=:0 -remote.debug=:0 -rpc.trace
+```bash
+gopls -remote=auto -logfile=auto -debug=:0 -remote.debug=:0 -rpc.trace
 ```
 
 Note that the shared gopls process will automatically shut down after one
@@ -55,23 +56,28 @@ forwarders manage it, you must start a gopls daemon process with the
 started by your editor.
 
 For example, to host the daemon on the TCP port `37374`, do:
-```
+
-$ gopls -listen=:37374 -logfile=auto -debug=:0
+```bash
+gopls -listen=:37374 -logfile=auto -debug=:0
 ```
 
 And then from the editor, run
-```
+
-$ gopls -remote=:37374 -logfile=auto -debug=:0 -rpc.trace
+```bash
+gopls -remote=:37374 -logfile=auto -debug=:0 -rpc.trace
 ```
 
 If you are on a POSIX system, you can also use unix domain sockets by prefixing
 the flag values with `unix;`. For example:
+
+```bash
+gopls -listen="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0
 ```
-$ gopls -listen="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0
+
-```
 And connect via:
-```
+
-$ gopls -remote="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0 -rpc.trace
+```bash
+gopls -remote="unix;/tmp/gopls-daemon-socket" -logfile=auto -debug=:0 -rpc.trace
 ```
 
 (Note that these flag values MUST be enclosed in quotes, because ';' is a

gopls/doc/design/design.md

@@ -1,4 +1,4 @@
-# gopls design documentation
+# `gopls` design documentation
 
 ## Goals
 
@@ -7,7 +7,6 @@
 * `gopls` will be **clean and extensible** so that it can encompass additional features in the future, allowing Go tooling to become best in class once more.
 * `gopls` will **support alternate build systems and file layouts**, allowing Go development to be simpler and more powerful in any environment.
 
-
 ## Context
 
 While Go has a number of excellent and useful command-line tools that enhance the developer experience, it has become clear that integrating these tools with IDEs can pose challenges.
@@ -170,7 +169,6 @@ All of these things make it hard for users to report a bug usefully, or create a
 
 There needs to be easy ways for users to report what information they can, and ways to attempt to reproduce problems without their entire state. This is also needed to produce regression tests.
 
-
 ## Basic design decisions
 
 There are some fundamental architecture decisions that affect much of the rest of the design of the tool, making fundamental trade offs that impact the user experience.
@@ -208,6 +206,8 @@ In the future it is expected to run in separated client server mode, so writing
 
 ## Features
 
+<!--TODO(rstambler): Generate a file that lists all of the supported features.-->
+
 There is a set of features that gopls needs to expose to be a comprehensive IDE solution.
 The following is the minimum set of features, along with their existing solutions and how they should map to the LSP.
 
@@ -239,7 +239,6 @@ LSP            | [`textDocument/signatureHelp`]
 Previous       | [gogetdoc]
 |              | As a function call is being typed into code, it is helpful to know the parameters of that call to enable the developer to call it correctly.
 
-
 ### Navigation
 
 Navigation features are designed to make it easier for a developer to find their way round a code base.
@@ -278,7 +277,6 @@ LSP        | [`textDocument/references`]
 Previous   | [guru]
 |          | This requires knowledge of every package that could possible depend on any packages the current file is part of. In the past this has been implemented either by global knowledge, which does not scale, or by specifying a "scope" which confused users to the point where they just did not use the tools. gopls is probably going to need a more powerful solution in the long term, but to start with automatically limiting the scope may produce acceptable results. This would probably be the module if known, or some sensible parent directory otherwise.
 
-
 ---
 Folding  | Report logical hierarchies of blocks
 -------- | ---
@@ -314,7 +312,6 @@ LSP      | [`textDocument/formatting`]
 Previous | [gofmt], [goimports], [goreturns]
 |        | It will use the standard format package. <br/> Current limitations are that it does not work on malformed code. It may need some very careful changes to the formatter to allow for formatting an invalid AST or changes to force the AST to a valid mode. These changes would improve range and file mode as well, but are basically vital to onTypeFormatting
 
-
 ---
 Imports  | Rewrite the imports block automatically to match the symbols used.
 -------- | ---
@@ -323,7 +320,6 @@ LSP      | [`textDocument/codeAction`]
 Previous | [goimports], [goreturns]
 |        | This needs knowledge of packages that are not yet in use, and the ability to find those packages by name. <br/> It also needs exported symbol information for all the packages it discovers. <br/> It should be implemented using the standard imports package, but there may need to be exposed a more fine grained API than just a file rewrite for some of the interactions.
 
-
 ---
 Autocompletion | Makes suggestions to complete the entity currently being typed.
 -------------- | ---
@@ -350,7 +346,6 @@ LSP             | [`textDocument/codeAction`]
 Previous        | N/A
 |               | This is a brand new feature powered by the new go/analysis engine, and it should allow a huge amount of automated refactoring.
 
-
 [LSP specification]: https://microsoft.github.io/language-server-protocol/specifications/specification-3-14/
 [talk]: TODO
 [slides]: https://github.com/gophercon/2019-talks/blob/master/RebeccaStambler-GoPleaseStopBreakingMyEditor/slides.pdf "Go, please stop breaking my editor!"
@@ -375,7 +370,6 @@ Previous        | N/A
 [go/ast]: https://golang.org/pkg/go/ast/
 [go/token]: https://golang.org/pkg/go/token/
 
-
 [`completionItem/resolve`]:https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#completionItem_resolve
 [`textDocument/codeAction`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_codeAction
 [`textDocument/completion`]: https://github.com/Microsoft/language-server-protocol/blob/gh-pages/_specifications/specification-3-14.md#textDocument_completion

gopls/doc/emacs.md

@@ -29,9 +29,7 @@ Both Eglot and LSP Mode can integrate with popular packages in the Emacs
 ecosystem:
 
 * The built-in [`xref`] package provides cross-references.
-
 * The built-in [Flymake] package provides an on-the-fly diagnostic overlay.
-
 * [Company] mode displays code completion candidates (with a richer UI than
   the built-in [`completion-at-point`]).
 
@@ -151,18 +149,18 @@ meantime, see those issues for discussion and possible workarounds.
 
 Common errors:
 
--   When prompted by Emacs for your project folder, if you are using modules you
+* When prompted by Emacs for your project folder, if you are using modules you
   must select the module's root folder (i.e. the directory with the "go.mod").
   If you are using GOPATH, select your $GOPATH as your folder.
--   Emacs must have your environment set properly (PATH, GOPATH, etc). You can
+* Emacs must have your environment set properly (PATH, GOPATH, etc). You can
   run `M-x getenv <RET> PATH <RET>` to see if your PATH is set in Emacs. If
   not, you can try starting Emacs from your terminal, using [this
   package][exec-path-from-shell], or moving your shell config from `.bashrc`
   into `.profile` and logging out and back in.
--   Make sure only one LSP client mode is installed. (For example, if using
+* Make sure only one LSP client mode is installed. (For example, if using
   `lsp-mode`, ensure that you are not _also_ enabling `eglot`.)
--   Look for errors in the `*lsp-log*` buffer or run `M-x eglot-events-buffer`.
+* Look for errors in the `*lsp-log*` buffer or run `M-x eglot-events-buffer`.
--   Ask for help in the `#emacs` channel on the [Gophers slack].
+* Ask for help in the `#emacs` channel on the [Gophers slack].
 
 [LSP Mode]: https://emacs-lsp.github.io/lsp-mode/
 [Eglot]: https://github.com/joaotavora/eglot/blob/master/README.md

gopls/doc/faq.md

@@ -1,7 +0,0 @@
-# gopls FAQ
-
-## Why is it called gopls?
-
-Since gopls works both as a language server and as a command line tool, we wanted a name that could be used as a verb. For example, gopls check should read as "go please check." See: [cl/158197].
-
-[cl/158197]: https://golang.org/cl/158197

gopls/doc/features.md

@@ -0,0 +1,24 @@
+# Features
+
+This document describes some of the features supported by `gopls`. It is
+currently under construction, so, for a comprehensive list, see the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
+
+For now, only special features outside of the LSP are described below.
+
+## Special features
+
+### Symbol Queries
+
+Gopls supports some extended syntax for `workspace/symbol` requests, when using
+the `fuzzy` symbol matcher (the default). Inspired by the popular fuzzy matcher
+[FZF](https://github.com/junegunn/fzf), the following special characters are
+supported within symbol queries:
+
+| Character | Usage     | Match        |
+| --------- | --------- | ------------ |
+| `'`       | `'abc`    | exact        |
+| `^`       | `^printf` | exact prefix |
+| `$`       | `printf$` | exact suffix |
+
+<!--TODO(rstambler): Automatically generate a list of supported features.-->

gopls/doc/status.md

@@ -1,37 +0,0 @@
-# Status
-
-gopls is currently in **alpha**, so it is **not stable**.
-
-gopls is currently under active development by the Go team. The code is in the [x/tools] repository, in [golang.org/x/tools/internal/lsp] and [golang.org/x/tools/gopls].
-
-## Supported features
-
-<!--- TODO: supported features
-details and status for the features
-missing features
---->
-
-### Autocompletion
-### Jump to definition
-### Signature help
-### Hover
-### Document symbols
-### References
-### Rename
-
-## Known issues
-
-1. Editing multiple modules in one editor window: [#32394]
-1. Type checking does not work in cgo packages: [#35721]
-1. Does not work with build tags: [#29202]
-1. Find references and rename only work in a single package: [#32877]
-
-[x/tools]: https://github.com/golang/tools
-[golang.org/x/tools/gopls]: https://github.com/golang/tools/tree/master/gopls
-[golang.org/x/tools/internal/lsp]: https://github.com/golang/tools/tree/master/internal/lsp
-
-
-[#32394]: https://github.com/golang/go/issues/32394
-[#35721]: https://github.com/golang/go/issues/35721
-[#29202]: https://github.com/golang/go/issues/29202
-[#32877]: https://github.com/golang/go/issues/32877

gopls/doc/user.md

@@ -1,13 +1,11 @@
 # User guide
 
-##### If you're having issues with `gopls`, please see the [troubleshooting guide](troubleshooting.md).
+**If you're having issues with `gopls`, please see the
-
+[troubleshooting guide](troubleshooting.md).**
-This document focuses on VSCode, as at the time of writing, VSCode is the most popular Go editor. However, most of the features described here work in any editor. The settings should be easy to translate to those of another editor's LSP client. The differences will be in the place where you define the settings and the syntax with which you declare them.
 
 ## Editors
 
-The following is the list of editors with known integrations.
+The following is the list of editors with known integrations for `gopls`.
-If you use `gopls` with an editor that is not on this list, please let us know by [filing an issue](#new-issue) or [modifying this documentation](#contribute).
 
 * [VSCode](vscode.md)
 * [Vim / Neovim](vim.md)
@@ -16,6 +14,19 @@ If you use `gopls` with an editor that is not on this list, please let us know b
 * [Sublime Text](subl.md)
 * [Atom](atom.md)
 
+If you use `gopls` with an editor that is not on this list, please let us know
+by [filing an issue](#new-issue) or [modifying this documentation](contributing.md).
+
+## Overview
+
+* [Installation](#installation)
+* [Configuration](#configuration)
+
+Learn more at the following pages:
+
+* [Features](features.md)
+* [Command-line](command-line.md)
+
 ## Installation
 
 For the most part, you should not need to install or update `gopls`. Your editor should handle that step for you.
@@ -72,35 +83,51 @@ meaning that it officially supports the last 2 major Go releases. We run CI to
 verify that the `gopls` tests pass for the last 4 major Go releases, but do not
 prioritize issues only affecting legacy Go release (3 or 4 releases ago).
 
-## Configurations
+## Configuration
 
 ### Environment variables
 
-These are often inherited from the editor that launches `gopls`, and sometimes the editor has a way to add or replace values before launching. For example, VSCode allows you to configure `go.toolsEnvVars`.
+These are often inherited from the editor that launches `gopls`, and sometimes
+the editor has a way to add or replace values before launching. For example,
+VSCode allows you to configure `go.toolsEnvVars`.
 
-Configuring your environment correctly is important, as `gopls` relies on the `go` command.
+Configuring your environment correctly is important, as `gopls` relies on the
+`go` command.
 
-### Command line flags
+### Command-line flags
 
-See the [command line page](command-line.md) for more information about the flags you might specify.
+See the [command-line page](command-line.md) for more information about the
-All editors support some way of adding flags to `gopls`, for the most part you should not need to do this unless you have very unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps) `gopls` behavior.
+flags you might specify. All editors support some way of adding flags to
+`gopls`, for the most part you should not need to do this unless you have very
+unusual requirements or are trying to [troubleshoot](troubleshooting.md#steps)
+`gopls` behavior.
 
 ### Editor settings
 
-For the most part these will be settings that control how the editor interacts with or uses the results of `gopls`, not modifications to `gopls` itself. This means they are not standardized across editors, and you will have to look at the specific instructions for your editor integration to change them.
+For the most part these will be settings that control how the editor interacts
+with or uses the results of `gopls`, not modifications to `gopls` itself. This
+means they are not standardized across editors, and you will have to look at
+the specific instructions for your editor integration to change them.
 
 #### The set of workspace folders
 
-This is one of the most important pieces of configuration. It is the set of folders that gopls considers to be "roots" that it should consider files to be a part of.
+This is one of the most important pieces of configuration. It is the set of
+folders that gopls considers to be "roots" that it should consider files to
+be a part of.
 
-If you are using modules there should be one of these per go.mod that you are working on.
+If you are using modules there should be one of these per go.mod that you
-If you do not open the right folders, very little will work. **This is the most common misconfiguration of `gopls` that we see**.
+are working on. If you do not open the right folders, very little will work.
+**This is the most common misconfiguration of `gopls` that we see**.
 
 #### Global configuration
 
-There should be a way of declaring global settings for `gopls` inside the editor. The settings block will be called `"gopls"` and contains a collection of controls for `gopls` that the editor is not expected to understand or control.
+There should be a way of declaring global settings for `gopls` inside the
+editor. The settings block will be called `"gopls"` and contains a collection
+of controls for `gopls` that the editor is not expected to understand or
+control.
 
-In VSCode, this would be a section in your settings file that might look like this:
+In VSCode, this would be a section in your settings file that might look like
+this:
 
 ```json5
   "gopls": {
@@ -109,30 +136,22 @@ In VSCode, this would be a section in your settings file that might look like th
   },
 ```
 
-See [Settings](settings.md) for more information about the available configurations.
+See [Settings](settings.md) for more information about the available
+configurations.
 
 #### Workspace folder configuration
 
-This contains exactly the same set of values that are in the global configuration, but it is fetched for every workspace folder separately. The editor can choose to respond with different values per-folder.
+This contains exactly the same set of values that are in the global
-
+configuration, but it is fetched for every workspace folder separately.
-## Special Features
+The editor can choose to respond with different values per-folder.
-
-### Symbol Queries
-
-Gopls supports some extended syntax for `workspace/symbol` requests, when using
-the `fuzzy` symbol matcher (the default). Inspired by the popular fuzzy matcher
-[FZF](https://github.com/junegunn/fzf), the following special characters are
-supported within symbol queries:
-
-| Character | Usage     | Match        |
-| --------- | --------- | ------------ |
-| `'`       | `'abc`    | exact        |
-| `^`       | `^printf` | exact prefix |
-| `$`       | `printf$` | exact suffix |
 
 ### Working on the Go source distribution
 
-If you are working on the [Go project](https://go.googlesource.com/go) itself, your `go` command will have to correspond to the version of the source you are working on. That is, if you have downloaded the code to `$HOME/go`, your `go` command should be the `$HOME/go/bin/go` executable that you built with `make.bash` or equivalent.
+If you are working on the [Go project](https://go.googlesource.com/go) itself,
+your `go` command will have to correspond to the version of the source you are
+working on. That is, if you have downloaded the code to `$HOME/go`, your `go`
+command should be the `$HOME/go/bin/go` executable that you built with
+`make.bash` or equivalent.
 
 You can achieve this by adding the right version of `go` to your `PATH` (`export PATH=$HOME/go/bin:$PATH` on Unix systems) or by configuring your editor. In VS Code, you can use the `go.alternateTools` setting to point to the correct version of `go`:
 
@@ -144,13 +163,3 @@ You can achieve this by adding the right version of `go` to your `PATH` (`export
     }
 }
 ```
-
-## Command line support
-
-Much of the functionality of `gopls` is available through a command line interface.
-
-There are two main reasons for this. The first is that we do not want users to rely on separate command line tools when they wish to do some task outside of an editor. The second is that the CLI assists in debugging. It is easier to reproduce behavior via single command.
-
-It is not a goal of `gopls` to be a high performance command line tool. Its command line is intended for single file/package user interaction speeds, not bulk processing.
-
-For more information, see the `gopls` [command line page](command-line.md).

gopls/doc/vim.md

@@ -18,7 +18,7 @@
 
 Use [vim-go] ver 1.20+, with the following configuration:
 
-```
+```vim
 let g:go_def_mode='gopls'
 let g:go_info_mode='gopls'
 ```
@@ -27,7 +27,7 @@ let g:go_info_mode='gopls'
 
 Use [LanguageClient-neovim], with the following configuration:
 
-```
+```vim
 " Launch gopls when Go files are in use
 let g:LanguageClient_serverCommands = {
        \ 'go': ['gopls']

gopls/doc/vscode.md

@@ -1,23 +1,16 @@
-# VSCode
+# VS Code
 
-Use the [VSCode-Go] plugin, with the following configuration:
+Use the [VS Code Go] plugin, with the following configuration:
 
 ```json5
 "go.useLanguageServer": true,
-"[go]": {
+```
-    "editor.formatOnSave": true,
+
-    "editor.codeActionsOnSave": {
+As of February 2020, `gopls` will be enabled by default in [VS Code Go].
-        "source.organizeImports": true,
+To learn more, follow along with
-    },
+[golang.vscode-go#1037](https://github.com/golang/vscode-go/issues/1037).
-    // Optional: Disable snippets, as they conflict with completion ranking.
+
-    "editor.snippetSuggestions": "none",
+```json5
-},
-"[go.mod]": {
-    "editor.formatOnSave": true,
-    "editor.codeActionsOnSave": {
-        "source.organizeImports": true,
-    },
-},
 "gopls": {
     // Add parameter placeholders when completing a function.
     "ui.completion.usePlaceholders": true,
@@ -27,7 +20,7 @@ Use the [VSCode-Go] plugin, with the following configuration:
     "ui.diagnostic.staticcheck": false,
     
     // For more customization, see
-    // see https://github.com/golang/vscode-go/blob/master/docs/settings.md
+    // see https://github.com/golang/vscode-go/blob/master/docs/settings.md.
 }
 ```
 
@@ -37,25 +30,37 @@ To enable more detailed debug information, add the following to your VSCode sett
 "go.languageServerFlags": [
     "-rpc.trace", // for more detailed debug logging
     "serve",
-    "--debug=localhost:6060", // Optional: to investigate memory usage, see profiles
+    "--debug=localhost:6060", // Optional: investigate memory usage, see profiles
 ],
 ```
 
-See the section on [command line](command-line.md) arguments for more information about what these do, along with other things like `--logfile=auto` that you might want to use.
+See the section on [command line](command-line.md) arguments for more
+information about what these do, along with other things like
+`--logfile=auto` that you might want to use.
 
-You can disable features through the `"go.languageServerExperimentalFeatures"` section of the config. An example of a feature you may want to disable is `"documentLink"`, which opens [`pkg.go.dev`](https://pkg.go.dev) links when you click on import statements in your file.
+## Build tags and flags
 
-### Build tags and flags
+Build tags and flags will be automatically picked up from `"go.buildTags"` and
+`"go.buildFlags"` settings. In the rare case that you don't want that default
+behavior, you can still override the settings from the `gopls` section, using
+`"gopls": { "build.buildFlags": [] }`.
 
-build tags and flags will be automatically picked up from `"go.buildTags"` and `"go.buildFlags"` settings. In rare cases if you don't want the default behavior, you can still override the settings from the `gopls` section, using `"gopls": { "build.buildFlags": [] }`.
+## Remote Development with `gopls`
 
+You can also make use of `gopls` with the
+[VS Code Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
+extensions to enable full-featured Go development on a lightweight client
+machine, while connected to a more powerful server machine.
 
-[VSCode-Go]: https://github.com/golang/vscode-go
+First, install the Remote Development extension of your choice, such as the
+[Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) extension. Once
+you open a remote session in a new window, open the Extensions pane
+(Ctrl+Shift+X) and you will see several different sections listed. In the
+"Local - Installed" section, navigate to the Go extension and click
+"Install in SSH: hostname".
 
-# VSCode Remote Development with gopls
+Once you have reloaded VS Code, you will be prompted to install `gopls` and other
+Go-related tools. After one more reload, you should be ready to develop remotely
+with VS Code and the Go extension.
 
-You can also make use of `gopls` with the [VSCode Remote Development](https://code.visualstudio.com/docs/remote/remote-overview) extensions to enable full-featured Go development on a lightweight client machine, while connected to a more powerful server machine.
+[VS Code Go]: https://github.com/golang/vscode-go
-
-First, install the Remote Development extension of your choice, such as the [Remote - SSH](https://code.visualstudio.com/docs/remote/ssh) extension. Once you open a remote session in a new window, open the Extensions pane (Ctrl+Shift+X) and you will see several different sections listed. In the "Local - Installed" section, navigate to the Go extension and click "Install in SSH: hostname".
-
-Once you have reloaded VSCode, you will be prompted to install `gopls` and other Go-related tools. After one more reload, you should be ready to develop remotely with VSCode and the Go extension.

internal/lsp/tests/README.md

@@ -1,9 +1,9 @@
-## Testing
+# Testing
 
 LSP has "marker tests" defined in `internal/lsp/testdata`, as well as
 traditional tests.
 
-#### Marker tests
+## Marker tests
 
 Marker tests have a standard input file, like
 `internal/lsp/testdata/foo/bar.go`, and some may have a corresponding golden
@@ -18,17 +18,17 @@ is encoded in the golden file.
 When tests are run, each annotation results in a new subtest, which is encoded
 in the golden file with a heading like,
 
-```
+```bash
 -- suggestedfix_bar_11_21 --
 // expected contents go here
 -- suggestedfix_bar_13_20 --
 // expected contents go here
 ```
 
-The format of these headings vary: they are defined by the "Golden" function for
+The format of these headings vary: they are defined by the
-each annotation: https://pkg.go.dev/golang.org/x/tools/internal/lsp/tests#Data.Golden.
+[`Golden`](https://pkg.go.dev/golang.org/x/tools/internal/lsp/tests#Data.Golden)
-In the case above, the format is: annotation name, file name, annotation line
+function for each annotation. In the case above, the format is: annotation
-location, annotation character location.
+name, file name, annotation line location, annotation character location.
 
 So, if `internal/lsp/testdata/foo/bar.go` has three `suggestedfix` annotations,
 the golden file should have three headers with `suggestedfix_bar_xx_yy`
@@ -39,7 +39,7 @@ To see a list of all available annotations, see the exported "expectations" in
 
 To run marker tests,
 
-```
+```bash
 cd /path/to/tools
 
 # The marker tests are located in "internal/lsp", "internal/lsp/cmd, and
@@ -50,17 +50,17 @@ go test ./internal/lsp/...
 There are quite a lot of marker tests, so to run one individually, pass the test
 path and heading into a -run argument:
 
-```
+```bash
 cd /path/to/tools
 go test ./internal/lsp -v -run TestLSP/Modules/SuggestedFix/bar_11_21
 ```
 
-#### Resetting marker tests
+## Resetting marker tests
 
 Sometimes, a change is made to lsp that requires a change to multiple golden
 files. When this happens, you can run,
 
-```
+```bash
 cd /path/to/tools
 ./internal/lsp/reset_golden.sh
 ```