go/analysis/passes/printf: elaborate the documentation

Fixes golang/go#66733

Change-Id: Idbd92f92bad0fcb9286fcb68c6109b42a9d84045
Reviewed-on: https://go-review.googlesource.com/c/tools/+/578035
LUCI-TryBot-Result: Go LUCI <[email protected]>
Reviewed-by: Robert Findley <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>

Author: adonovan

go/analysis/passes/printf/doc.go

@@ -11,29 +11,73 @@
 //
 // The check applies to calls of the formatting functions such as
 // [fmt.Printf] and [fmt.Sprintf], as well as any detected wrappers of
-// those functions.
+// those functions such as [log.Printf]. It reports a variety of
+// mistakes such as syntax errors in the format string and mismatches
+// (of number and type) between the verbs and their arguments.
 //
-// In this example, the %d format operator requires an integer operand:
+// See the documentation of the fmt package for the complete set of
+// format operators and their operand types.
+//
+// # Examples
+//
+// The %d format operator requires an integer operand.
+// Here it is incorrectly applied to a string:
 //
 //	fmt.Printf("%d", "hello") // fmt.Printf format %d has arg "hello" of wrong type string
 //
-// See the documentation of the fmt package for the complete set of
-// format operators and their operand types.
+// A call to Printf must have as many operands as there are "verbs" in
+// the format string, not too few:
+//
+//	fmt.Printf("%d") // fmt.Printf format reads arg 1, but call has 0 args
+//
+// nor too many:
+//
+//	fmt.Printf("%d", 1, 2) // fmt.Printf call needs 1 arg, but has 2 args
+//
+// Explicit argument indexes must be no greater than the number of
+// arguments:
+//
+//	fmt.Printf("%[3]d", 1, 2) // fmt.Printf call has invalid argument index 3
+//
+// The checker also uses a heuristic to report calls to Print-like
+// functions that appear to have been intended for their Printf-like
+// counterpart:
+//
+//	log.Print("%d", 123) // log.Print call has possible formatting directive %d
+//
+// # Inferred printf wrappers
+//
+// Functions that delegate their arguments to fmt.Printf are
+// considered "printf wrappers"; calls to them are subject to the same
+// checking. In this example, logf is a printf wrapper:
+//
+//	func logf(level int, format string, args ...any) {
+//		if enabled(level) {
+//			log.Printf(format, args...)
+//		}
+//	}
+//
+//	logf(3, "invalid request: %v") // logf format reads arg 1, but call has 0 args
 //
 // To enable printf checking on a function that is not found by this
 // analyzer's heuristics (for example, because control is obscured by
 // dynamic method calls), insert a bogus call:
 //
 //	func MyPrintf(format string, args ...any) {
 //		if false {
-//			_ = fmt.Sprintf(format, args...) // enable printf checker
+//			_ = fmt.Sprintf(format, args...) // enable printf checking
 //		}
 //		...
 //	}
 //
-// The -funcs flag specifies a comma-separated list of names of additional
-// known formatting functions or methods. If the name contains a period,
-// it must denote a specific function using one of the following forms:
+// # Specifying printf wrappers by flag
+//
+// The -funcs flag specifies a comma-separated list of names of
+// additional known formatting functions or methods. (This legacy flag
+// is rarely used due to the automatic inference described above.)
+//
+// If the name contains a period, it must denote a specific function
+// using one of the following forms:
 //
 //	dir/pkg.Function
 //	dir/pkg.Type.Method

gopls/doc/analyzers.md

@@ -553,40 +553,13 @@ printf: check consistency of Printf format strings and arguments
 
 The check applies to calls of the formatting functions such as
 [fmt.Printf] and [fmt.Sprintf], as well as any detected wrappers of
-those functions.
-
-In this example, the %d format operator requires an integer operand:
-
-	fmt.Printf("%d", "hello") // fmt.Printf format %d has arg "hello" of wrong type string
+those functions such as [log.Printf]. It reports a variety of
+mistakes such as syntax errors in the format string and mismatches
+(of number and type) between the verbs and their arguments.
 
 See the documentation of the fmt package for the complete set of
 format operators and their operand types.
 
-To enable printf checking on a function that is not found by this
-analyzer's heuristics (for example, because control is obscured by
-dynamic method calls), insert a bogus call:
-
-	func MyPrintf(format string, args ...any) {
-		if false {
-			_ = fmt.Sprintf(format, args...) // enable printf checker
-		}
-		...
-	}
-
-The -funcs flag specifies a comma-separated list of names of additional
-known formatting functions or methods. If the name contains a period,
-it must denote a specific function using one of the following forms:
-
-	dir/pkg.Function
-	dir/pkg.Type.Method
-	(*dir/pkg.Type).Method
-
-Otherwise the name is interpreted as a case-insensitive unqualified
-identifier such as "errorf". Either way, if a listed name ends in f, the
-function is assumed to be Printf-like, taking a format string before the
-argument list. Otherwise it is assumed to be Print-like, taking a list
-of arguments with no format string.
-
 [Full documentation](https://pkg.go.dev/golang.org/x/tools/go/analysis/passes/printf)
 
 **Enabled by default.**