From: Rob Pike <r@golang.org>
Date: Tue, 18 Mar 2014 00:25:04 +0000 (+1100)
Subject: fmt: document GoStringer and explain application of formats to compound objects
X-Git-Tag: go1.3beta1~339
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=0de0de0907a9e7b644ce0ce8f9862b4d70f531c7;p=gostls13.git

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 11a3523b97..7a7b63bd6b 100644
--- 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) }