x/tools/go/analysis/printf: doc: explain "possible formatting directive" message in documentation

[adonovan]

The printf checker reports a diagnostic for calls like this:

fmt.Print("hello, %s") // "%s call has possible Printf formatting directive %s"

(Aside: though it's easy to conceive of false positives for this heuristic, in practice it seems to be very reliable.)

In Google issue 302359716, a number of users tell us that the message makes them think the problem is in the format string, when really it's in the choice of formatting function. Perhaps the error message could give them a hint:

fmt.Print("hello, %s") // "fmt.Print call has possible formatting directive %s; use fmt.Printf(...) or fmt.Printf("%s", ...)"

The error message could vary depending on whether the corresponding 'f' variant function exists. The main challenge is deciding the exact wording; these messages have been agonized over for a decade.

@robpike

[robpike]

Print call has Printf formatting directive.

[adonovan]

Print call has Printf formatting directive.

Do you mean that you would prefer the message to say even less than it does currently, by removing the "possible" qualifier?

[rsc]

It would be good to keep the message short. Let's work on making the documentation link that accompanies this message do a better job of calling out the mistake.

[adonovan]

OK, I'll treat this as a documentation problem and update the printf docs.

[gopherbot]

Change https://go.dev/cl/578035 mentions this issue: go/analysis/passes/printf: elaborate the documentation

[findleyr]

See also #47872.

[findleyr]

...and, somewhat related, https://go.dev/cl/422854, derived from the google internal b/227741360.

While the printf analyzer is among the most useful vet checks, it does tend to be confusing for new users.

[nharper]

As someone who ran into difficulty with this message, the improvement that would help most (either in the message or the linked documentation) is a reminder that the caller probably meant to call a different function - the one that takes a formatting string instead of the one that doesn't, e.g. "Print call has Printf formatting directive. Call Printf instead of Print".