fmt: document space behavior of Append

Also, introduce the {Print,Fprint,Sprint,Append}{,f,ln}
cross product of functions at the top of the docs.

Fixes #74656

Change-Id: I85a156cd545ca866e579d8020ddf165cd4bcb26f
Reviewed-on: https://go-review.googlesource.com/c/go/+/688877
Reviewed-by: Rob Pike <r@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Damien Neil <dneil@google.com>

diff --git a/src/fmt/doc.go b/src/fmt/doc.go
index fa0ffa7f00ccc7c93454c0e9292a7e92df0b84c6..46f30b44e9a72289772d7078377e61db9259c896 100644 (file)
--- a/src/fmt/doc.go
+++ b/src/fmt/doc.go
@@ -9,6 +9,18 @@ are simpler.
 
 # Printing
 
+There are four families of printing functions defined by their output destination.
+[Print], [Println] and [Printf] write to [os.Stdout];
+[Sprint], [Sprintln] and [Sprintf] return a string;
+[Fprint], [Fprintln] and [Fprintf] write to an [io.Writer]; and
+[Append], [Appendln] and [Appendf] append the output to a byte slice.
+
+The functions within each family do the formatting according to the end of the name.
+Print, Sprint, Fprint and Append use the default format for each argument,
+adding a space between operands when neither is a string.
+Println, Sprintln, Fprintln and Appendln always add spaces and append a newline.
+Printf, Sprintf, Fprintf and Appendf use a sequence of "verbs" to control the formatting.
+
 The verbs:
 
 General:
@@ -222,7 +234,7 @@ formatting methods such as Error or String on unexported fields.
 
 # Explicit argument indexes
 
-In [Printf], [Sprintf], and [Fprintf], the default behavior is for each
+In [Printf], [Sprintf], [Fprintf], and [Appendf], the default behavior is for each
 formatting verb to format successive arguments passed in the call.
 However, the notation [n] immediately before the verb indicates that the
 nth one-indexed argument is to be formatted instead. The same notation

diff --git a/src/fmt/print.go b/src/fmt/print.go
index 01cfa1a1c7d7b440eff7927d34241a7de0bf1b7b..2340ceed8f294488d73d28e1ffd26a3fa67a2eb1 100644 (file)
--- a/src/fmt/print.go
+++ b/src/fmt/print.go
@@ -284,6 +284,7 @@ func Sprint(a ...any) string {
 
 // Append formats using the default formats for its operands, appends the result to
 // the byte slice, and returns the updated slice.
+// Spaces are added between operands when neither is a string.
 func Append(b []byte, a ...any) []byte {
        p := newPrinter()
        p.doPrint(a)