.config/coc/extensions/coc-go-data/tools/pkg/mod/golang.org/x/tools/gopls@v0.5.2/doc/settings.md

   1 # Settings
   2
   3 <!--TODO: Generate this file from the documentation in golang/org/x/tools/internal/lsp/source/options.go.-->
   4
   5 This document describes the 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. These settings can also be configured differently per workspace folder.
   6
   7 In VSCode, this would be a section in your `settings.json` file that might look like this:
   8
   9 ```json5
  10   "gopls": {
  11     "usePlaceholders": true,
  12     "completeUnimported": true
  13   },
  14 ```
  15
  16 ## Officially supported
  17
  18 Below is the list of settings that are officially supported for `gopls`.
  19
  20 To enable all experimental features, use **allExperiments: `true`**. You will
  21 still be able to independently override specific experimental features.
  22
  23 <!-- BEGIN User: DO NOT MANUALLY EDIT THIS SECTION -->
  24 ### **buildFlags** *[]string*
  25 buildFlags is the set of flags passed on to the build system when invoked.
  26 It is applied to queries like `go list`, which is used when discovering files.
  27 The most common use is to set `-tags`.
  28
  29
  30 Default: `[]`.
  31 ### **env** *map[string]string*
  32 env adds environment variables to external commands run by `gopls`, most notably `go list`.
  33
  34
  35 Default: `{}`.
  36 ### **hoverKind** *enum*
  37 hoverKind controls the information that appears in the hover text.
  38 SingleLine and Structured are intended for use only by authors of editor plugins.
  39 Must be one of:
  40
  41  * `"FullDocumentation"`
  42  * `"NoDocumentation"`
  43  * `"SingleLine"`
  44  * `"Structured"` is an experimental setting that returns a structured hover format.
  45 This format separates the signature from the documentation, so that the client
  46 can do more manipulation of these fields.\
  47 This should only be used by clients that support this behavior.
  48
  49  * `"SynopsisDocumentation"`
  50
  51
  52 Default: `"FullDocumentation"`.
  53 ### **usePlaceholders** *bool*
  54 placeholders enables placeholders for function parameters or struct fields in completion responses.
  55
  56
  57 Default: `false`.
  58 ### **linkTarget** *string*
  59 linkTarget controls where documentation links go.
  60 It might be one of:
  61
  62 * `"godoc.org"`
  63 * `"pkg.go.dev"`
  64
  65 If company chooses to use its own `godoc.org`, its address can be used as well.
  66
  67
  68 Default: `"pkg.go.dev"`.
  69 ### **local** *string*
  70 local is the equivalent of the `goimports -local` flag, which puts imports beginning with this string after 3rd-party packages.
  71 It should be the prefix of the import path whose imports should be grouped separately.
  72
  73
  74 Default: `""`.
  75 ### **gofumpt** *bool*
  76 gofumpt indicates if we should run gofumpt formatting.
  77
  78
  79 Default: `false`.
  80 <!-- END User: DO NOT MANUALLY EDIT THIS SECTION -->
  81
  82 ## Experimental
  83
  84 The below settings are considered experimental. They may be deprecated or changed in the future. They are typically used to test experimental opt-in features or to disable features.
  85
  86 <!-- BEGIN Experimental: DO NOT MANUALLY EDIT THIS SECTION -->
  87 ### **analyses** *map[string]bool*
  88 analyses specify analyses that the user would like to enable or disable.
  89 A map of the names of analysis passes that should be enabled/disabled.
  90 A full list of analyzers that gopls uses can be found [here](analyzers.md)
  91
  92 Example Usage:
  93 ```json5
  94 ...
  95 "analyses": {
  96   "unreachable": false, // Disable the unreachable analyzer.
  97   "unusedparams": true  // Enable the unusedparams analyzer.
  98 }
  99 ...
 100 ```
 101
 102
 103 Default: `{}`.
 104 ### **codelens** *map[string]bool*
 105 codelens overrides the enabled/disabled state of code lenses. See the "Code Lenses"
 106 section of settings.md for the list of supported lenses.
 107
 108 Example Usage:
 109 ```json5
 110 "gopls": {
 111 ...
 112   "codelens": {
 113     "generate": false,  // Don't show the `go generate` lens.
 114     "gc_details": true  // Show a code lens toggling the display of gc's choices.
 115   }
 116 ...
 117 }
 118 ```
 119
 120
 121 Default: `{"gc_details":false,"generate":true,"regenerate_cgo":true,"tidy":true,"upgrade_dependency":true,"vendor":true}`.
 122 ### **completionDocumentation** *bool*
 123 completionDocumentation enables documentation with completion results.
 124
 125
 126 Default: `true`.
 127 ### **completeUnimported** *bool*
 128 completeUnimported enables completion for packages that you do not currently import.
 129
 130
 131 Default: `true`.
 132 ### **deepCompletion** *bool*
 133 deepCompletion enables the ability to return completions from deep inside relevant entities, rather than just the locally accessible ones.
 134
 135 Consider this example:
 136
 137 ```go
 138 package main
 139
 140 import "fmt"
 141
 142 type wrapString struct {
 143     str string
 144 }
 145
 146 func main() {
 147     x := wrapString{"hello world"}
 148     fmt.Printf(<>)
 149 }
 150 ```
 151
 152 At the location of the `<>` in this program, deep completion would suggest the result `x.str`.
 153
 154
 155 Default: `true`.
 156 ### **matcher** *enum*
 157 matcher sets the algorithm that is used when calculating completion candidates.
 158 Must be one of:
 159
 160  * `"CaseInsensitive"`
 161  * `"CaseSensitive"`
 162  * `"Fuzzy"`
 163
 164
 165 Default: `"Fuzzy"`.
 166 ### **annotations** *map[string]bool*
 167 annotations suppress various kinds of optimization diagnostics
 168 that would be reported by the gc_details command.
 169  * noNilcheck suppresses display of nilchecks.
 170  * noEscape suppresses escape choices.
 171  * noInline suppresses inlining choices.
 172  * noBounds suppresses bounds checking diagnostics.
 173
 174
 175 Default: `{}`.
 176 ### **staticcheck** *bool*
 177 staticcheck enables additional analyses from staticcheck.io.
 178
 179
 180 Default: `false`.
 181 ### **symbolMatcher** *enum*
 182 symbolMatcher sets the algorithm that is used when finding workspace symbols.
 183 Must be one of:
 184
 185  * `"CaseInsensitive"`
 186  * `"CaseSensitive"`
 187  * `"Fuzzy"`
 188
 189
 190 Default: `"Fuzzy"`.
 191 ### **symbolStyle** *enum*
 192 symbolStyle controls how symbols are qualified in symbol responses.
 193
 194 Example Usage:
 195 ```json5
 196 "gopls": {
 197 ...
 198   "symbolStyle": "dynamic",
 199 ...
 200 }
 201 ```
 202 Must be one of:
 203
 204  * `"Dynamic"` uses whichever qualifier results in the highest scoring
 205 match for the given symbol query. Here a "qualifier" is any "/" or "."
 206 delimited suffix of the fully qualified symbol. i.e. "to/pkg.Foo.Field" or
 207 just "Foo.Field".
 208
 209  * `"Full"` is fully qualified symbols, i.e.
 210 "path/to/pkg.Foo.Field".
 211
 212  * `"Package"` is package qualified symbols i.e.
 213 "pkg.Foo.Field".
 214
 215
 216
 217 Default: `"Package"`.
 218 ### **linksInHover** *bool*
 219 linksInHover toggles the presence of links to documentation in hover.
 220
 221
 222 Default: `true`.
 223 ### **tempModfile** *bool*
 224 tempModfile controls the use of the -modfile flag in Go 1.14.
 225
 226
 227 Default: `true`.
 228 ### **importShortcut** *enum*
 229 importShortcut specifies whether import statements should link to
 230 documentation or go to definitions.
 231 Must be one of:
 232
 233  * `"Both"`
 234  * `"Definition"`
 235  * `"Link"`
 236
 237
 238 Default: `"Both"`.
 239 ### **verboseWorkDoneProgress** *bool*
 240 verboseWorkDoneProgress controls whether the LSP server should send
 241 progress reports for all work done outside the scope of an RPC.
 242
 243
 244 Default: `false`.
 245 ### **semanticTokens** *bool*
 246 semanticTokens controls whether the LSP server will send
 247 semantic tokens to the client.
 248
 249
 250 Default: `false`.
 251 ### **expandWorkspaceToModule** *bool*
 252 expandWorkspaceToModule instructs `gopls` to expand the scope of the workspace to include the
 253 modules containing the workspace folders. Set this to false to avoid loading
 254 your entire module. This is particularly useful for those working in a monorepo.
 255
 256
 257 Default: `true`.
 258 ### **experimentalWorkspaceModule** *bool*
 259 experimentalWorkspaceModule opts a user into the experimental support
 260 for multi-module workspaces.
 261
 262
 263 Default: `false`.
 264 ### **experimentalDiagnosticsDelay** *time.Duration*
 265 experimentalDiagnosticsDelay controls the amount of time that gopls waits
 266 after the most recent file modification before computing deep diagnostics.
 267 Simple diagnostics (parsing and type-checking) are always run immediately
 268 on recently modified packages.
 269
 270 This option must be set to a valid duration string, for example `"250ms"`.
 271
 272
 273 Default: `"0s"`.
 274 ### **experimentalPackageCacheKey** *bool*
 275 experimentalPackageCacheKey controls whether to use a coarser cache key
 276 for package type information to increase cache hits. This setting removes
 277 the user's environment, build flags, and working directory from the cache
 278 key, which should be a safe change as all relevant inputs into the type
 279 checking pass are already hashed into the key. This is temporarily guarded
 280 by an experiment because caching behavior is subtle and difficult to
 281 comprehensively test.
 282
 283
 284 Default: `false`.
 285 <!-- END Experimental: DO NOT MANUALLY EDIT THIS SECTION -->
 286
 287 ## Debugging
 288
 289 The below settings are for use in debugging `gopls`. Like the experimental options, they may be deprecated or changed in the future.
 290
 291 <!-- BEGIN Debugging: DO NOT MANUALLY EDIT THIS SECTION -->
 292 ### **verboseOutput** *bool*
 293 verboseOutput enables additional debug logging.
 294
 295
 296 Default: `false`.
 297 ### **completionBudget** *time.Duration*
 298 completionBudget is the soft latency goal for completion requests. Most
 299 requests finish in a couple milliseconds, but in some cases deep
 300 completions can take much longer. As we use up our budget we
 301 dynamically reduce the search scope to ensure we return timely
 302 results. Zero means unlimited.
 303
 304
 305 Default: `"100ms"`.
 306 <!-- END Debugging: DO NOT MANUALLY EDIT THIS SECTION -->
 307
 308 ## Code Lenses
 309
 310 These are the code lenses that `gopls` currently supports. They can be enabled and disabled using the `codeLenses` setting, documented above. The names and features are subject to change.
 311
 312 <!-- BEGIN Lenses: DO NOT MANUALLY EDIT THIS SECTION -->
 313 ### **Run go generate**
 314 Identifier: `generate`
 315
 316 generate runs `go generate` for a given directory.
 317
 318
 319 ### **Regenerate cgo**
 320 Identifier: `regenerate_cgo`
 321
 322 regenerate_cgo regenerates cgo definitions.
 323
 324
 325 ### **Run test(s)**
 326 Identifier: `test`
 327
 328 test runs `go test` for a specific test function.
 329
 330
 331 ### **Run go mod tidy**
 332 Identifier: `tidy`
 333
 334 tidy runs `go mod tidy` for a module.
 335
 336
 337 ### **Upgrade dependency**
 338 Identifier: `upgrade_dependency`
 339
 340 upgrade_dependency upgrades a dependency.
 341
 342
 343 ### **Run go mod vendor**
 344 Identifier: `vendor`
 345
 346 vendor runs `go mod vendor` for a module.
 347
 348
 349 ### **Toggle gc_details**
 350 Identifier: `gc_details`
 351
 352 gc_details controls calculation of gc annotations.
 353
 354
 355 <!-- END Lenses: DO NOT MANUALLY EDIT THIS SECTION -->