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

   1 # Analyzers
   2
   3 <!--TODO: Generate this file from the documentation in golang/org/x/tools/go/analysis/passes and golang/org/x/tools/go/lsp/source/options.go.-->
   4
   5 This document describes the analyzers that `gopls` uses inside the editor.
   6
   7 A value of `true` means that the analyzer is enabled by default and a value of `false` means it is disabled by default.
   8
   9 Details about how to enable/disable these analyses can be found [here](settings.md#analyses).
  10
  11 ## Go vet suite
  12
  13 Below is the list of general analyzers that are used in `go vet`.
  14
  15 ### **asmdecl**
  16
  17 report mismatches between assembly files and Go declarations
  18
  19 Default value: `true`.
  20
  21 ### **assign**
  22
  23 check for useless assignments
  24
  25 This checker reports assignments of the form `x = x` or `a[i] = a[i]`.
  26 These are almost always useless, and even when they aren't they are
  27 usually a mistake.
  28
  29 Default value: `true`.
  30
  31 ### **atomic**
  32
  33 check for common mistakes using the sync/atomic package
  34
  35 The atomic checker looks for assignment statements of the form:
  36
  37 `x = atomic.AddUint64(&x, 1)`
  38
  39 which are not atomic.
  40
  41 Default value: `true`.
  42
  43 ### **atomicalign**
  44
  45 check for non-64-bits-aligned arguments to sync/atomic functions
  46
  47 Default value: `true`.
  48
  49 ### **bools**
  50
  51 check for common mistakes involving boolean operators
  52
  53 Default value: `true`.
  54
  55 ### **buildtag**
  56
  57 check that +build tags are well-formed and correctly located
  58
  59 Default value: `true`.
  60
  61 ### **cgocall**
  62
  63 detect some violations of the cgo pointer passing rules
  64
  65 Check for invalid cgo pointer passing.
  66 This looks for code that uses cgo to call C code passing values
  67 whose types are almost always invalid according to the cgo pointer
  68 sharing rules.
  69 Specifically, it warns about attempts to pass a Go chan, map, func,
  70 or slice to C, either directly, or via a pointer, array, or struct.
  71
  72 Default value: `true`.
  73
  74 ### **composites**
  75
  76 check for unkeyed composite literals
  77
  78 This analyzer reports a diagnostic for composite literals of struct
  79 types imported from another package that do not use the field-keyed
  80 syntax. Such literals are fragile because the addition of a new field
  81 (even if unexported) to the struct will cause compilation to fail.
  82
  83 As an example,
  84 `err = &net.DNSConfigError{err}`
  85
  86 should be replaced by:
  87 `err = &net.DNSConfigError{Err: err}`
  88
  89 Default value: `true`.
  90
  91 ### **copylock**
  92
  93 check for locks erroneously passed by value
  94
  95 Inadvertently copying a value containing a lock, such as sync.Mutex or
  96 sync.WaitGroup, may cause both copies to malfunction. Generally such
  97 values should be referred to through a pointer.
  98
  99 Default value: `true`.
 100
 101 ### **errorsas**
 102
 103 report passing non-pointer or non-error values to errors.As
 104
 105 The errorsas analysis reports calls to errors.As where the type
 106 of the second argument is not a pointer to a type implementing error.
 107
 108 Default value: `true`.
 109
 110 ### **httpresponse**
 111
 112 check for mistakes using HTTP responses
 113
 114 A common mistake when using the net/http package is to defer a function
 115 call to close the http.Response Body before checking the error that
 116 determines whether the response is valid:
 117
 118 ```go
 119 resp, err := http.Head(url)
 120 defer resp.Body.Close()
 121 if err != nil {
 122   log.Fatal(err)
 123 }
 124 // (defer statement belongs here)
 125 ```
 126
 127 This checker helps uncover latent nil dereference bugs by reporting a
 128 diagnostic for such mistakes.
 129
 130 Default value: `true`.
 131
 132 ### **loopclosure**
 133
 134 check references to loop variables from within nested functions
 135
 136 This analyzer checks for references to loop variables from within a
 137 function literal inside the loop body. It checks only instances where
 138 the function literal is called in a defer or go statement that is the
 139 last statement in the loop body, as otherwise we would need whole
 140 program analysis.
 141
 142 For example:
 143 ```go
 144 for i, v := range s {
 145   go func() {
 146     println(i, v) // not what you might expect
 147   }()
 148 }
 149 ```
 150
 151 See: https://golang.org/doc/go_faq.html#closures_and_goroutines
 152
 153 Default value: `true`.
 154
 155 ### **lostcancel**
 156
 157 check cancel func returned by context.WithCancel is called
 158
 159 The cancellation function returned by context.WithCancel, WithTimeout,
 160 and WithDeadline must be called or the new context will remain live
 161 until its parent context is cancelled.
 162 (The background context is never cancelled.)
 163
 164 Default value: `true`.
 165
 166 ### **nilfunc**
 167
 168 check for useless comparisons between functions and nil
 169
 170 A useless comparison is one like f == nil as opposed to f() == nil.
 171
 172 Default value: `true`.
 173
 174 ### **printf**
 175
 176 check consistency of Printf format strings and arguments
 177
 178 The check applies to known functions (for example, those in package fmt)
 179 as well as any detected wrappers of known functions.
 180
 181 A function that wants to avail itself of printf checking but is not
 182 found by this analyzer's heuristics (for example, due to use of
 183 dynamic calls) can insert a bogus call:
 184
 185 ```go
 186 if false {
 187   _ = fmt.Sprintf(format, args...) // enable printf checking
 188 }
 189 ```
 190
 191 The -funcs flag specifies a comma-separated list of names of additional
 192 known formatting functions or methods. If the name contains a period,
 193 it must denote a specific function using one of the following forms:
 194
 195 ```
 196         dir/pkg.Function
 197         dir/pkg.Type.Method
 198         (*dir/pkg.Type).Method
 199 ```
 200
 201 Otherwise the name is interpreted as a case-insensitive unqualified
 202 identifier such as "errorf". Either way, if a listed name ends in f, the
 203 function is assumed to be Printf-like, taking a format string before the
 204 argument list. Otherwise it is assumed to be Print-like, taking a list
 205 of arguments with no format string.
 206
 207 Default value: `true`.
 208
 209 ### **shift**
 210
 211 check for shifts that equal or exceed the width of the integer
 212
 213 Default value: `true`.
 214
 215 ### **stdmethods**
 216
 217 check signature of methods of well-known interfaces
 218
 219 Sometimes a type may be intended to satisfy an interface but may fail to
 220 do so because of a mistake in its method signature.
 221 For example, the result of this WriteTo method should be (int64, error),
 222 not error, to satisfy io.WriterTo:
 223
 224 ```go
 225         type myWriterTo struct{...}
 226         func (myWriterTo) WriteTo(w io.Writer) error { ... }
 227 ```
 228
 229 This check ensures that each method whose name matches one of several
 230 well-known interface methods from the standard library has the correct
 231 signature for that interface.
 232
 233 Checked method names include:
 234         Format GobEncode GobDecode MarshalJSON MarshalXML
 235         Peek ReadByte ReadFrom ReadRune Scan Seek
 236         UnmarshalJSON UnreadByte UnreadRune WriteByte
 237         WriteTo
 238
 239 Default value: `true`.
 240
 241 ### **structtag**
 242
 243 check that struct field tags conform to reflect.StructTag.Get
 244
 245 Also report certain struct tags (json, xml) used with unexported fields.
 246
 247 Default value: `true`.
 248
 249 ### **tests**
 250
 251 check for common mistaken usages of tests and examples
 252
 253 The tests checker walks Test, Benchmark and Example functions checking
 254 malformed names, wrong signatures and examples documenting non-existent
 255 identifiers.
 256
 257 Please see the documentation for package testing in golang.org/pkg/testing
 258 for the conventions that are enforced for Tests, Benchmarks, and Examples.
 259
 260 Default value: `true`.
 261
 262 ### **unmarshal**
 263
 264 report passing non-pointer or non-interface values to unmarshal
 265
 266 The unmarshal analysis reports calls to functions such as json.Unmarshal
 267 in which the argument type is not a pointer or an interface.
 268
 269 Default value: `true`.
 270
 271 ### **unreachable**
 272
 273 check for unreachable code
 274
 275 The unreachable analyzer finds statements that execution can never reach
 276 because they are preceded by an return statement, a call to panic, an
 277 infinite loop, or similar constructs.
 278
 279 Default value: `true`.
 280
 281 ### **unsafeptr**
 282
 283 check for invalid conversions of uintptr to unsafe.Pointer
 284
 285 The unsafeptr analyzer reports likely incorrect uses of unsafe.Pointer
 286 to convert integers to pointers. A conversion from uintptr to
 287 unsafe.Pointer is invalid if it implies that there is a uintptr-typed
 288 word in memory that holds a pointer value, because that word will be
 289 invisible to stack copying and to the garbage collector.
 290
 291 Default value: `true`.
 292
 293 ### **unusedresult**
 294
 295 check for unused results of calls to some functions
 296
 297 Some functions like fmt.Errorf return a result and have no side effects,
 298 so it is always a mistake to discard the result. This analyzer reports
 299 calls to certain functions in which the result of the call is ignored.
 300
 301 The set of functions may be controlled using flags.
 302
 303 Default value: `true`.
 304
 305 ## gopls suite
 306
 307 Below is the list of analyzers that are used by `gopls`.
 308
 309 ### **deepequalerrors**
 310
 311 check for calls of reflect.DeepEqual on error values
 312
 313 The deepequalerrors checker looks for calls of the form:
 314
 315 ```go
 316     reflect.DeepEqual(err1, err2)
 317 ```
 318
 319 where err1 and err2 are errors. Using reflect.DeepEqual to compare
 320 errors is discouraged.
 321
 322 Default value: `true`.
 323
 324 ### **fillreturns**
 325
 326 suggested fixes for "wrong number of return values (want %d, got %d)"
 327
 328 This checker provides suggested fixes for type errors of the
 329 type "wrong number of return values (want %d, got %d)". For example:
 330 ```go
 331 func m() (int, string, *bool, error) {
 332   return
 333 }
 334 ```
 335 will turn into
 336 ```go
 337 func m() (int, string, *bool, error) {
 338   return 0, "", nil, nil
 339 }
 340 ```
 341
 342 This functionality is similar to [goreturns](https://github.com/sqs/goreturns).
 343
 344 Default value: `false`.
 345
 346 ### **nonewvars**
 347
 348 suggested fixes for "no new vars on left side of :="
 349
 350 This checker provides suggested fixes for type errors of the
 351 type "no new vars on left side of :=". For example:
 352 ```go
 353 z := 1
 354 z := 2
 355 ```
 356 will turn into
 357 ```go
 358 z := 1
 359 z = 2
 360 ```
 361
 362 Default value: `false`.
 363
 364 ### **noresultvalues**
 365
 366 suggested fixes for "no result values expected"
 367
 368 This checker provides suggested fixes for type errors of the
 369 type "no result values expected". For example:
 370 ```go
 371 func z() { return nil }
 372 ```
 373 will turn into
 374 ```go
 375 func z() { return }
 376 ```
 377
 378 Default value: `true`.
 379
 380 ### **simplifycompositelit**
 381
 382 check for composite literal simplifications
 383
 384 An array, slice, or map composite literal of the form:
 385 ```go
 386 []T{T{}, T{}}
 387 ```
 388 will be simplified to:
 389 ```go
 390 []T{{}, {}}
 391 ```
 392
 393 This is one of the simplifications that "gofmt -s" applies.
 394
 395 Default value: `true`.
 396
 397 ### **simplifyrange**
 398
 399 check for range statement simplifications
 400
 401 A range of the form:
 402 ```go
 403 for x, _ = range v {...}
 404 ```
 405 will be simplified to:
 406 ```go
 407 for x = range v {...}
 408 ```
 409
 410 A range of the form:
 411 ```go
 412 for _ = range v {...}
 413 ```
 414 will be simplified to:
 415 ```go
 416 for range v {...}
 417 ```
 418
 419 This is one of the simplifications that "gofmt -s" applies.
 420
 421 Default value: `true`.
 422
 423 ### **simplifyslice**
 424
 425 check for slice simplifications
 426
 427 A slice expression of the form:
 428 ```go
 429 s[a:len(s)]
 430 ```
 431 will be simplified to:
 432 ```go
 433 s[a:]
 434 ```
 435
 436 This is one of the simplifications that "gofmt -s" applies.
 437
 438 Default value: `true`.
 439
 440 ### **sortslice**
 441
 442 check the argument type of sort.Slice
 443
 444 sort.Slice requires an argument of a slice type. Check that
 445 the interface{} value passed to sort.Slice is actually a slice.
 446
 447 Default value: `true`.
 448
 449 ### **testinggoroutine**
 450
 451 report calls to (*testing.T).Fatal from goroutines started by a test.
 452
 453 Functions that abruptly terminate a test, such as the Fatal, Fatalf, FailNow, and
 454 Skip{,f,Now} methods of *testing.T, must be called from the test goroutine itself.
 455 This checker detects calls to these functions that occur within a goroutine
 456 started by the test. For example:
 457
 458 ```go
 459 func TestFoo(t *testing.T) {
 460     go func() {
 461         t.Fatal("oops") // error: (*T).Fatal called from non-test goroutine
 462     }()
 463 }
 464 ```
 465
 466 Default value: `true`.
 467
 468 ### **undeclaredname**
 469
 470 suggested fixes for "undeclared name: <>"
 471
 472 This checker provides suggested fixes for type errors of the
 473 type `undeclared name: <>`. It will insert a new statement:
 474 `<> := `.
 475
 476 Default value: `false`.
 477
 478 ### **unusedparams**
 479
 480 check for unused parameters of functions
 481
 482 The unusedparams analyzer checks functions to see if there are
 483 any parameters that are not being used.
 484
 485 To reduce false positives it ignores:
 486 - methods
 487 - parameters that do not have a name or are underscored
 488 - functions in test files
 489 - functions with empty bodies or those with just a return stmt
 490
 491 Default value: `false`.