fmt: document GoStringer and explain application of formats to compound objects

%q quotes each element of a string slice; this was never explained in the docs.
Fixes #7015.

LGTM=josharian
R=golang-codereviews, josharian
CC=golang-codereviews
https://golang.org/cl/77140044

diff --git a/src/pkg/fmt/doc.go b/src/pkg/fmt/doc.go
index 11a3523b97fdaea7092dcef2f4fa5111831a3db9..7a7b63bd6b12d75fe3995197202e0dfd6bd37eca 100644 (file)
--- a/src/pkg/fmt/doc.go
+++ b/src/pkg/fmt/doc.go
@@ -115,7 +115,9 @@
        will print 23.
 
        If an operand implements interface Formatter, that interface
-       can be used for fine control of formatting.
+       can be used for fine control of formatting. Similarly, if an
+       operand implements the GoStringer interface, that will be
+       invoked if the '%#v' verb is used to format the operand.
 
        If the format (which is implicitly %v for Println etc.) is valid
        for a string (%s %q %v %x %X), the following two rules also apply:
@@ -128,6 +130,12 @@
        will be used to convert the object to a string, which will then
        be formatted as required by the verb (if any).
 
+       For compound operands such as slices and structs, the format
+       applies to the elements of each operand, recursively, not to the
+       operand as a whole. Thus %q will quote each element of a slice
+       of strings, and %6.2f will control formatting for each element
+       of a floating-point array.
+
        To avoid recursion in cases such as
                type X string
                func (x X) String() string { return Sprintf("<%s>", x) }