fmt: unify the printing examples

Provide an example for each of the printing functions (Print,
Sprintf, Fprintln etc.), and make them all produce the same output
so their usage can be compared.

Also add a package-level example explaining the difference between
how Printf, Println, and Print behave.

There are more examples to come.

Update #27554.

Change-Id: Ide03e5233f3762a9ee2ac0269f534ab927562ce2
Reviewed-on: https://go-review.googlesource.com/136615Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

src/fmt/example_test.go

@@ -19,6 +19,7 @@ func ExampleErrorf() {
 	const name, id = "bueller", 17
 	err := fmt.Errorf("user %q (id %d) not found", name, id)
 	fmt.Println(err.Error())
+
 	// Output: user "bueller" (id 17) not found
 }
 
@@ -31,7 +32,7 @@ func ExampleFscanf() {
 	r := strings.NewReader("5 true gophers")
 	n, err := fmt.Fscanf(r, "%d %t %s", &i, &b, &s)
 	if err != nil {
-		panic(err)
+		fmt.Fprintf(os.Stderr, "Fscanf: %v\n", err)
 	}
 	fmt.Println(i, b, s)
 	fmt.Println(n)
@@ -40,98 +41,168 @@ func ExampleFscanf() {
 	// 3
 }
 
-func ExampleSprintf() {
-	i := 30
-	s := "Aug"
-	sf := fmt.Sprintf("Today is %d %s", i, s)
-	fmt.Println(sf)
-	fmt.Println(len(sf))
+func ExampleFscanln() {
+	s := `dmr 1771 1.61803398875
+	ken 271828 3.14159`
+	r := strings.NewReader(s)
+	var a string
+	var b int
+	var c float64
+	for {
+		n, err := fmt.Fscanln(r, &a, &b, &c)
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			panic(err)
+		}
+		fmt.Printf("%d: %s, %d, %f\n", n, a, b, c)
+	}
 	// Output:
-	// Today is 30 Aug
-	// 15
+	// 3: dmr, 1771, 1.618034
+	// 3: ken, 271828, 3.141590
 }
 
 func ExamplePrint() {
-	n, err := fmt.Print("there", "are", 99, "gophers", "\n")
-	if err != nil {
-		panic(err)
-	}
-	fmt.Print(n)
+	const name, age = "Kim", 22
+	fmt.Print(name, " is ", age, " years old.\n")
+
+	// It is conventional not to worry about any
+	// error returned by Print.
+
 	// Output:
-	// thereare99gophers
-	// 18
+	// Kim is 22 years old.
 }
 
 func ExamplePrintln() {
-	n, err := fmt.Println("there", "are", 99, "gophers")
-	if err != nil {
-		panic(err)
-	}
-	fmt.Print(n)
+	const name, age = "Kim", 22
+	fmt.Println(name, "is", age, "years old.")
+
+	// It is conventional not to worry about any
+	// error returned by Println.
+
+	// Output:
+	// Kim is 22 years old.
+}
+
+func ExamplePrintf() {
+	const name, age = "Kim", 22
+	fmt.Printf("%s is %d years old.\n", name, age)
+
+	// It is conventional not to worry about any
+	// error returned by Printf.
+
+	// Output:
+	// Kim is 22 years old.
+}
+
+func ExampleSprint() {
+	const name, age = "Kim", 22
+	s := fmt.Sprint(name, " is ", age, " years old.\n")
+
+	io.WriteString(os.Stdout, s) // Ignoring error for simplicity.
+
 	// Output:
-	// there are 99 gophers
-	// 21
+	// Kim is 22 years old.
 }
 
 func ExampleSprintln() {
-	s := "Aug"
-	sl := fmt.Sprintln("Today is 30", s)
-	fmt.Printf("%q", sl)
+	const name, age = "Kim", 22
+	s := fmt.Sprintln(name, "is", age, "years old.")
+
+	io.WriteString(os.Stdout, s) // Ignoring error for simplicity.
+
+	// Output:
+	// Kim is 22 years old.
+}
+
+func ExampleSprintf() {
+	const name, age = "Kim", 22
+	s := fmt.Sprintf("%s is %d years old.\n", name, age)
+
+	io.WriteString(os.Stdout, s) // Ignoring error for simplicity.
+
 	// Output:
-	// "Today is 30 Aug\n"
+	// Kim is 22 years old.
 }
 
 func ExampleFprint() {
-	n, err := fmt.Fprint(os.Stdout, "there", "are", 99, "gophers", "\n")
+	const name, age = "Kim", 22
+	n, err := fmt.Fprint(os.Stdout, name, " is ", age, " years old.\n")
+
+	// The n and err return values from Fprint are
+	// those returned by the underlying io.Writer.
 	if err != nil {
-		panic(err)
+		fmt.Fprintf(os.Stderr, "Fprint: %v\n", err)
 	}
-	fmt.Print(n)
+	fmt.Print(n, " bytes written.\n")
+
 	// Output:
-	// thereare99gophers
-	// 18
+	// Kim is 22 years old.
+	// 21 bytes written.
 }
 
 func ExampleFprintln() {
-	n, err := fmt.Fprintln(os.Stdout, "there", "are", 99, "gophers")
+	const name, age = "Kim", 22
+	n, err := fmt.Fprintln(os.Stdout, name, "is", age, "years old.")
+
+	// The n and err return values from Fprintln are
+	// those returned by the underlying io.Writer.
 	if err != nil {
-		panic(err)
+		fmt.Fprintf(os.Stderr, "Fprintln: %v\n", err)
 	}
-	fmt.Print(n)
+	fmt.Println(n, "bytes written.")
+
 	// Output:
-	// there are 99 gophers
-	// 21
+	// Kim is 22 years old.
+	// 21 bytes written.
 }
 
-func ExampleFscanln() {
-	s := `dmr 1771 1.61803398875
-	ken 271828 3.14159`
-	r := strings.NewReader(s)
-	var a string
-	var b int
-	var c float64
-	for {
-		n, err := fmt.Fscanln(r, &a, &b, &c)
-		if err == io.EOF {
-			break
-		}
-		if err != nil {
-			panic(err)
-		}
-		fmt.Printf("%d: %s, %d, %f\n", n, a, b, c)
+func ExampleFprintf() {
+	const name, age = "Kim", 22
+	n, err := fmt.Fprintf(os.Stdout, "%s is %d years old.\n", name, age)
+
+	// The n and err return values from Fprintf are
+	// those returned by the underlying io.Writer.
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Fprintf: %v\n", err)
 	}
+	fmt.Printf("%d bytes written.\n", n)
+
 	// Output:
-	// 3: dmr, 1771, 1.618034
-	// 3: ken, 271828, 3.141590
+	// Kim is 22 years old.
+	// 21 bytes written.
 }
 
-func ExampleSprint() {
-	s := fmt.Sprint("there", "are", "99", "gophers")
-	fmt.Println(s)
-	fmt.Println(len(s))
+// Print, Println, and Printf lay out their arguments differently. In this example
+// we can compare their behaviors. Println always adds blanks between the items it
+// prints, while Print adds blanks only between non-string arguments and Printf
+// does exactly what it is told.
+// Sprint, Sprintln, Sprintf, Fprint, Fprintln, and Fprintf behave the same as
+// their corresponding Print, Println, and Printf functions shown here.
+func Example_printers() {
+	a, b := 3.0, 4.0
+	h := math.Hypot(a, b)
+
+	// Print inserts blanks between arguments when neither is a string.
+	// It does not add a newline to the output, so we add one explicitly.
+	fmt.Print("The vector (", a, b, ") has length ", h, ".\n")
+
+	// Println always inserts spaces between its arguments,
+	// so it cannot be used to produce the same output as Print in this case;
+	// its output has extra spaces.
+	// Also, Println always adds a newline to the output.
+	fmt.Println("The vector (", a, b, ") has length", h, ".")
+
+	// Printf provides complete control but is more complex to use.
+	// It does not add a newline to the output, so we add one explicitly
+	// at the end of the format specifier string.
+	fmt.Printf("The vector (%g %g) has length %g.\n", a, b, h)
+
 	// Output:
-	// thereare99gophers
-	// 17
+	// The vector (3 4) has length 5.
+	// The vector ( 3 4 ) has length 5 .
+	// The vector (3 4) has length 5.
 }
 
 // These examples demonstrate the basics of printing using a format string. Printf,