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/147018Reviewed-by: Daniel Martí <mvdan@mvdan.cc>
Run-TryBot: Daniel Martí <mvdan@mvdan.cc>
TryBot-Result: Gobot Gobot <gobot@golang.org>

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'.

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

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)
+}

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.

src/cmd/vet/doc.go

+// 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

src/cmd/vet/main.go

-// 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,