diff options
author | Alan Donovan <adonovan@google.com> | 2018-11-02 11:27:53 -0400 |
---|---|---|
committer | Alan Donovan <adonovan@google.com> | 2018-11-19 15:20:54 +0000 |
commit | 42b46585f19a6d6b3819d025e0f4b07b18a6b5b7 (patch) | |
tree | 64af8ff9f34446024ddc85ac25900b6027a1507c | |
parent | 3c92bdc7db3ebf062adc9287743d74e60ba5bb03 (diff) | |
download | go-42b46585f19a6d6b3819d025e0f4b07b18a6b5b7.tar.gz go-42b46585f19a6d6b3819d025e0f4b07b18a6b5b7.zip |
cmd/go: improve go vet documentation
- restore and rework cmd/vet/doc.go, which was clobbered during the vet-lite switch.
- document go vet -vettool=prog flag and how to run an alternative checker.
- make 'go vet -help' show how to list vet tool's flags. Example:
$ 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 vet -vettool=~/bin/myvet -help
usage: go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]
Run 'go help vet' for details.
Run '~/bin/myvet help' for the vet tool's flags.
Updates #28840
Change-Id: Ieb79dfe29e1df074f865bc9a9d47b44199675d7d
Reviewed-on: https://go-review.googlesource.com/c/147018
Reviewed-by: Daniel Martà <mvdan@mvdan.cc>
Run-TryBot: Daniel Martà <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>
-rw-r--r-- | src/cmd/go/alldocs.go | 11 | ||||
-rw-r--r-- | src/cmd/go/internal/vet/vet.go | 13 | ||||
-rw-r--r-- | src/cmd/go/internal/vet/vetflag.go | 18 | ||||
-rw-r--r-- | src/cmd/go/testdata/script/help.txt | 1 | ||||
-rw-r--r-- | src/cmd/vet/doc.go | 71 | ||||
-rw-r--r-- | src/cmd/vet/main.go | 20 |
6 files changed, 111 insertions, 23 deletions
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index e7412f9bc7..12134b21c0 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -1299,16 +1299,25 @@ // // Usage: // -// go vet [-n] [-x] [build flags] [vet flags] [packages] +// 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'. diff --git a/src/cmd/go/internal/vet/vet.go b/src/cmd/go/internal/vet/vet.go index 616f774bf6..327b761c3c 100644 --- a/src/cmd/go/internal/vet/vet.go +++ b/src/cmd/go/internal/vet/vet.go @@ -16,17 +16,26 @@ import ( var CmdVet = &base.Command{ Run: runVet, CustomFlags: true, - UsageLine: "go vet [-n] [-x] [build flags] [vet flags] [packages]", + UsageLine: "go vet [-n] [-x] [-vettool prog] [build flags] [vet flags] [packages]", Short: "report likely mistakes in packages", Long: ` 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'. @@ -38,7 +47,7 @@ See also: go fmt, go fix. func runVet(cmd *base.Command, args []string) { modload.LoadTests = true - vetFlags, pkgArgs := vetFlags(cmd.Usage, args) + vetFlags, pkgArgs := vetFlags(vetUsage, args) work.BuildInit() work.VetFlags = vetFlags diff --git a/src/cmd/go/internal/vet/vetflag.go b/src/cmd/go/internal/vet/vetflag.go index 9b5184a4d4..37342f4163 100644 --- a/src/cmd/go/internal/vet/vetflag.go +++ b/src/cmd/go/internal/vet/vetflag.go @@ -166,3 +166,21 @@ func vetFlags(usage func(), args []string) (passToVet, packageNames []string) { } return args, nil } + +var vetUsage func() + +func init() { vetUsage = usage } // break initialization cycle + +func usage() { + fmt.Fprintf(os.Stderr, "usage: %s\n", CmdVet.UsageLine) + fmt.Fprintf(os.Stderr, "Run 'go help %s' for details.\n", CmdVet.LongName()) + + // This part is additional to what (*Command).Usage does: + cmd := "go tool vet" + if vetTool != "" { + cmd = vetTool + } + fmt.Fprintf(os.Stderr, "Run '%s -help' for the vet tool's flags.\n", cmd) + + os.Exit(2) +} diff --git a/src/cmd/go/testdata/script/help.txt b/src/cmd/go/testdata/script/help.txt index 3d0650880e..9f455256f7 100644 --- a/src/cmd/go/testdata/script/help.txt +++ b/src/cmd/go/testdata/script/help.txt @@ -34,6 +34,7 @@ stderr 'Run ''go help mod'' for usage.' ! go vet -h stderr 'usage: go vet' stderr 'Run ''go help vet'' for details' +stderr 'Run ''go tool vet -help'' for the vet tool''s flags' # Earlier versions of Go printed a large document here, instead of these two # lines. diff --git a/src/cmd/vet/doc.go b/src/cmd/vet/doc.go new file mode 100644 index 0000000000..279d081be3 --- /dev/null +++ b/src/cmd/vet/doc.go @@ -0,0 +1,71 @@ +// Copyright 2018 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +/* + +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 + +*/ +package main diff --git a/src/cmd/vet/main.go b/src/cmd/vet/main.go index 3ea781a7d4..4ec174b3cd 100644 --- a/src/cmd/vet/main.go +++ b/src/cmd/vet/main.go @@ -1,8 +1,3 @@ -// 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. package main import ( @@ -31,21 +26,6 @@ import ( "golang.org/x/tools/go/analysis/passes/unusedresult" ) -// Legacy vet had the concept of "experimental" checkers. - -// There was exactly one, shadow, and it had to be explicitly -// enabled by the -shadow flag, which would of course disable -// all the other tristate flags, requiring the -all flag (which -// is now a no-op) to reenable them. -// -// The shadow analyzer has been removed from the suite, -// but can be run using these additional commands: -// $ go install golang.org/x/tools/go/analysis/passes/shadow/cmd/shadow -// $ go vet -vettool=$(which shadow) -// Alternatively, one could build a multichecker containing all -// the desired checks (vet's suite + shadow) and run it in a -// single "go vet" command. - func main() { unitchecker.Main( asmdecl.Analyzer, |