fmt: explain how Formatter interface affects verbs and flags

Formatter is mentioned further down, but it's helpful
to add it amongst the verbs and flags.

Background: I spent a while puzzling how "%+v" prints
a stack trace for github.com/pkg/errors when this isn't
documented under 'flags'.

Change-Id: Ic70145902a36780147dedca568b3cf482974fc38
GitHub-Last-Rev: 6571b499f211a2266812af66dd3b88dff602cabf
GitHub-Pull-Request: golang/go#39860
Reviewed-on: https://go-review.googlesource.com/c/go/+/240000
Reviewed-by: Rob Pike <r@golang.org>
Trust: Rob Pike <r@golang.org>
Trust: Ian Lance Taylor <iant@golang.org>

diff --git a/src/fmt/doc.go b/src/fmt/doc.go
index a7115809d3dcf7d82c99ace45f55d4a950c7bb5a..d05ee519c3db471c384bae5bfe05de56914b0dcc 100644 (file)
--- a/src/fmt/doc.go
+++ b/src/fmt/doc.go
@@ -150,7 +150,8 @@
        concrete value that it holds, and printing continues with the next rule.
 
        2. If an operand implements the Formatter interface, it will
-       be invoked. Formatter provides fine control of formatting.
+       be invoked. In this case the interpretation of verbs and flags is
+       controlled by that implementation.
 
        3. If the %v verb is used with the # flag (%#v) and the operand
        implements the GoStringer interface, that will be invoked.

diff --git a/src/fmt/print.go b/src/fmt/print.go
index 778b5b0938f9babaa30aa19a3ed92b23a52dafaf..8bc225f5484ae4171e650d52cba6c93db13beadb 100644 (file)
--- a/src/fmt/print.go
+++ b/src/fmt/print.go
@@ -47,11 +47,11 @@ type State interface {
        Flag(c int) bool
 }
 
-// Formatter is the interface implemented by values with a custom formatter.
-// The implementation of Format may call Sprint(f) or Fprint(f) etc.
-// to generate its output.
+// Formatter is implemented by any value that has a Format method.
+// The implementation controls how State and rune are interpreted,
+// and may call Sprint(f) or Fprint(f) etc. to generate its output.
 type Formatter interface {
-       Format(f State, c rune)
+       Format(f State, verb rune)
 }
 
 // Stringer is implemented by any value that has a String method,