cmd/vet: restore documentation about vet flags

[ianlancetaylor]

The rearrangement of the vet tool, while a great step forward, seems to have lost the documentation of vet flags.

> go vet -help
usage: go vet [-n] [-x] [build flags] [vet flags] [packages]
Run 'go help vet' for details.

> go help vet
usage: go vet [-n] [-x] [build flags] [vet flags] [packages]

Vet runs the Go vet command on the packages named by the import paths.

For more about vet and its flags, see 'go doc cmd/vet'.
For more about specifying packages, see 'go help packages'.

The -n flag prints commands that would be executed.
The -x flag prints commands as they are executed.

The build flags supported by go vet are those that control package resolution
and execution, such as -n, -x, -v, -tags, and -toolexec.
For more about these flags, see 'go help build'.

See also: go fmt, go fix.

> go doc cmd/vet
The vet command is a driver for static checkers conforming to the
golang.org/x/tools/go/analysis API. Run it using 'go vet'.

For a tool capable of running standalone, use a multichecker-based tool such
as golang.org/x/tools/go/analysis/cmd/vet.

> go tool vet -help
vet is a tool for static analysis of Go programs.

Usage of vet:
	vet unit.cfg	# execute analysis specified by config file
	vet help		# general help
	vet help name	# help on specific analyzer and its flags

go tool vet help does list available flags. But that didn't work in 1.11. And I only got there by knowing about go tool vet, which is not mentioned by any of the first places to look.

CC @alandonovan

[gopherbot]

Change https://golang.org/cl/147018 mentions this issue: cmd/go: improve go vet documentation

[alandonovan]

For ease of review, this is the behavior proposed by Patchset 11 of https://go-review.googlesource.com/c/go/+/147018

$ go vet -help
usage: go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]
Run 'go help vet' for details.
Run 'go tool vet -help' for the vet tool's flags.

$ go help vet
usage: go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]

Vet runs the Go vet command on the packages named by the import paths.

For more about vet and its flags, see 'go doc cmd/vet'.
For more about specifying packages, see 'go help packages'.
For a list of checkers and their flags, see 'go tool vet help'.
For details of a specific checker such as 'printf', see 'go tool vet help printf'.

The -n flag prints commands that would be executed.
The -x flag prints commands as they are executed.

The -vettool=prog flag selects a different analysis tool with alternative
or additional checks.
For example, the 'shadow' analyzer can be built and run using these commands:

  go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow
  go vet -vettool=$(which shadow)

The build flags supported by go vet are those that control package resolution
and execution, such as -n, -x, -v, -tags, and -toolexec.
For more about these flags, see 'go help build'.

See also: go fmt, go fix.

$ go doc cmd/vet
Vet examines Go source code and reports suspicious constructs, such as
Printf calls whose arguments do not align with the format string. Vet uses
heuristics that do not guarantee all reports are genuine problems, but it
can find errors not caught by the compilers.

Vet is normally invoked through the go command. This command vets the
package in the current directory:

    go vet

whereas this one vets the packages whose path is provided:

    go vet my/project/...

Use "go help packages" to see other ways of specifying which packages to
vet.

Vet's exit code is non-zero for erroneous invocation of the tool or if a
problem was reported, and 0 otherwise. Note that the tool does not check
every possible problem and depends on unreliable heuristics, so it should be
used as guidance only, not as a firm indicator of program correctness.

To list the available checks, run "go tool vet help":

    asmdecl      report mismatches between assembly files and Go declarations
    assign       check for useless assignments
    atomic       check for common mistakes using the sync/atomic package
    bools        check for common mistakes involving boolean operators
    buildtag     check that +build tags are well-formed and correctly located
    cgocall      detect some violations of the cgo pointer passing rules
    composites   check for unkeyed composite literals
    copylocks    check for locks erroneously passed by value
    httpresponse check for mistakes using HTTP responses
    loopclosure  check references to loop variables from within nested functions
    lostcancel   check cancel func returned by context.WithCancel is called
    nilfunc      check for useless comparisons between functions and nil
    printf       check consistency of Printf format strings and arguments
    shift        check for shifts that equal or exceed the width of the integer
    stdmethods   check signature of methods of well-known interfaces
    structtag    check that struct field tags conform to reflect.StructTag.Get
    tests        check for common mistaken usages of tests and examples
    unmarshal    report passing non-pointer or non-interface values to unmarshal
    unreachable  check for unreachable code
    unsafeptr    check for invalid conversions of uintptr to unsafe.Pointer
    unusedresult check for unused results of calls to some functions

For details and flags of a particular check, such as printf, run "go tool
vet help printf".

By default, all checks are performed. If any flags are explicitly set to
true, only those tests are run. Conversely, if any flag is explicitly set to
false, only those tests are disabled. Thus -printf=true runs the printf
check, and -printf=false runs all checks except the printf check.

For information on writing a new check, see golang.org/x/tools/go/analysis.

Core flags:

    -c=N
      	display offending line plus N lines of surrounding context
    -json
      	emit analysis diagnostics (and errors) in JSON format

$ go tool vet -help
vet is a tool for static analysis of Go programs.

Usage of vet:
	vet unit.cfg	# execute analysis specified by config file
	vet help		# general help
	vet help name	# help on specific analyzer and its flags

$ go tool vet help
vet is a tool for static analysis of Go programs.

vet examines Go source code and reports suspicious constructs,
such as Printf calls whose arguments do not align with the format
string. It uses heuristics that do not guarantee all reports are
genuine problems, but it can find errors not caught by the compilers.

Registered analyzers:

    asmdecl      report mismatches between assembly files and Go declarations
    assign       check for useless assignments
    atomic       check for common mistakes using the sync/atomic package
    bools        check for common mistakes involving boolean operators
    buildtag     check that +build tags are well-formed and correctly located
    cgocall      detect some violations of the cgo pointer passing rules
    composites   checked for unkeyed composite literals
    copylocks    check for locks erroneously passed by value
    httpresponse check for mistakes using HTTP responses
    loopclosure  check references to loop variables from within nested functions
    lostcancel   check cancel func returned by context.WithCancel is called
    nilfunc      check for useless comparisons between functions and nil
    printf       check consistency of Printf format strings and arguments
    shift        check for shifts that equal or exceed the width of the integer
    stdmethods   check signature of methods of well-known interfaces
    structtag    check that struct field tags conform to reflect.StructTag.Get
    tests        check for common mistaken usages of tests and examples
    unmarshal    report passing non-pointer or non-interface values to unmarshal
    unreachable  check for unreachable code
    unsafeptr    check for invalid conversions of uintptr to unsafe.Pointer
    unusedresult check for unused results of calls to some functions

By default all analyzers are run.
To select specific analyzers, use the -NAME flag for each one,
 or -NAME=false to run all analyzers not explicitly disabled.

Core flags:

  -V	print version and exit
  -all
    	no effect (deprecated)
  -asmdecl
    	enable asmdecl analysis
  -assign
    	enable assign analysis
  -atomic
    	enable atomic analysis
  -bool
    	deprecated alias for -bools
  -bools
    	enable bools analysis
  -buildtag
    	enable buildtag analysis
  -buildtags
    	deprecated alias for -buildtag
  -c int
    	display offending line with this many lines of context (default -1)
  -cgocall
    	enable cgocall analysis
  -composites
    	enable composites analysis
  -compositewhitelist
    	deprecated alias for -composites.whitelist (default true)
  -copylocks
    	enable copylocks analysis
  -flags
    	print analyzer flags in JSON
  -httpresponse
    	enable httpresponse analysis
  -json
    	emit JSON output
  -loopclosure
    	enable loopclosure analysis
  -lostcancel
    	enable lostcancel analysis
  -methods
    	deprecated alias for -stdmethods
  -nilfunc
    	enable nilfunc analysis
  -printf
    	enable printf analysis
  -printfuncs value
    	deprecated alias for -printf.funcs (default (*log.Logger).Fatal,(*log.Logger).Fatalf,(*log.Logger).Fatalln,(*log.Logger).Panic,(*log.Logger).Panicf,(*log.Logger).Panicln,(*log.Logger).Print,(*log.Logger).Printf,(*log.Logger).Println,(*testing.common).Error,(*testing.common).Errorf,(*testing.common).Fatal,(*testing.common).Fatalf,(*testing.common).Log,(*testing.common).Logf,(*testing.common).Skip,(*testing.common).Skipf,(testing.TB).Error,(testing.TB).Errorf,(testing.TB).Fatal,(testing.TB).Fatalf,(testing.TB).Log,(testing.TB).Logf,(testing.TB).Skip,(testing.TB).Skipf,fmt.Errorf,fmt.Fprint,fmt.Fprintf,fmt.Fprintln,fmt.Print,fmt.Printf,fmt.Println,fmt.Sprint,fmt.Sprintf,fmt.Sprintln,log.Fatal,log.Fatalf,log.Fatalln,log.Panic,log.Panicf,log.Panicln,log.Print,log.Printf,log.Println,runtime/trace.Logf)
  -rangeloops
    	deprecated alias for -loopclosure
  -shift
    	enable shift analysis
  -source
    	no effect (deprecated)
  -stdmethods
    	enable stdmethods analysis
  -structtag
    	enable structtag analysis
  -tags string
    	no effect (deprecated)
  -tests
    	enable tests analysis
  -unmarshal
    	enable unmarshal analysis
  -unreachable
    	enable unreachable analysis
  -unsafeptr
    	enable unsafeptr analysis
  -unusedfuncs value
    	deprecated alias for -unusedresult.funcs (default errors.New,fmt.Errorf,fmt.Sprint,fmt.Sprintf,sort.Reverse)
  -unusedresult
    	enable unusedresult analysis
  -unusedstringmethods value
    	deprecated alias for -unusedresult.stringmethods (default Error,String)
  -v	no effect (deprecated)

To see details and flags of a specific analyzer, run 'vet help name'.

$ go tool vet help unusedresult
unusedresult: check for unused results of calls to some functions

Analyzer flags:

  -unusedresult.funcs value
    	comma-separated list of functions whose results must be used (default errors.New,fmt.Errorf,fmt.Sprint,fmt.Sprintf,sort.Reverse)
  -unusedresult.stringmethods value
    	comma-separated list of names of methods of type func() string whose results must be used (default Error,String)

Some functions like fmt.Errorf return a result and have no side effects,
so it is always a mistake to discard the result. This analyzer reports
calls to certain functions in which the result of the call is ignored.

The set of functions may be controlled using flags.

[jmcc32]

Hello,
Not sure if this is for re-enabling previous wording or if it's open to change. I think this option could be reworded to explain why. Useless seems vague.

assign check for useless assignments

The options below it are much more expressive. Something like this:

assign check for common mistakes using assignments

[ianlancetaylor]

This is better now.