diff options
Diffstat (limited to 'src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go')
| -rw-r--r-- | src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go | 60 |
1 files changed, 52 insertions, 8 deletions
diff --git a/src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go b/src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go index 1ee16126ad..85da8346f7 100644 --- a/src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go +++ b/src/cmd/vendor/golang.org/x/tools/go/analysis/passes/printf/doc.go @@ -11,14 +11,53 @@ // // 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 @@ -26,14 +65,19 @@ // // 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 |