tools/cmd/vet: Incorporate comments from r@.

This commit fixes a few defects from a25a8d567b:

(1.) Making the top-level vars in main consistent w.r.t. documentation
     formatting, and the-like.

(2.) Removing of one-use top-level is-test predicate.

(3.) Including documentation of what the validation does and when.

Change-Id: I19b34d25836bb2af865219d18600e1add78c3fd7
Reviewed-on: https://go-review.googlesource.com/14557
Reviewed-by: Rob Pike <r@golang.org>

cmd/vet/doc.go

@@ -165,6 +165,13 @@ Flag: -shift
 
 Shifts equal to or longer than the variable's length.
 
+Documentation examples
+
+Flag: -example
+
+Mistakes involving example tests, including examples with incorrect names or
+function signatures, or that document identifiers not in the package.
+
 Other flags
 
 These flags configure the behavior of vet:

cmd/vet/example.go

@@ -24,7 +24,7 @@ func isExampleSuffix(s string) bool { return strings.ToLower(s) == s }
 // mistakes of misnamed functions, failure to map functions to existing
 // identifiers, etc.
 func checkExample(f *File, node ast.Node) {
-	if !f.IsTest() {
+	if !strings.HasSuffix(f.name, "_test.go") {
 		return
 	}
 	var (

cmd/vet/main.go

@@ -53,11 +53,13 @@ var experimental = map[string]bool{}
 // setTrueCount record how many flags are explicitly set to true.
 var setTrueCount int
 
-var (
-	dirsRun, filesRun bool
+// dirsRun and filesRun indicate whether the vet is applied to directory or
+// file targets. The distinction affects which checks are run.
+var dirsRun, filesRun bool
 
-	includesNonTest bool
-)
+// includesNonTest indicates whether the vet is applied to non-test targets.
+// Certain checks are relevant only if they touch both test and non-test files.
+var includesNonTest bool
 
 // A triState is a boolean that knows whether it has been set to either true or false.
 // It is used to identify if a flag appears; the standard boolean flag cannot
@@ -193,8 +195,6 @@ type File struct {
 	checkers map[ast.Node][]func(*File, ast.Node)
 }
 
-func (f *File) IsTest() bool { return strings.HasSuffix(f.name, "_test.go") }
-
 func main() {
 	flag.Usage = Usage
 	flag.Parse()