strings: clarify usage of Title and ToTitle

This is intended to help clear up confusion around the usage of the
Title and ToTitle functions. It includes a link to define title case
to distinguish it from upper case. It also includes an additional
example for the ToTitle function to showcase the difference in behavior
between it and the Title function.

Fixes #33302

Change-Id: I44e62962fb04d0d22966a39eda3a2d16de7a2291
Reviewed-on: https://go-review.googlesource.com/c/go/+/187825
Reviewed-by: Rob Pike <r@golang.org>

1 files changed, 10 insertions, 1 deletions

diff --git a/src/strings/example_test.go b/src/strings/example_test.go
index 4f3a1ce8c6..375f9cac65 100644
--- a/src/strings/example_test.go
+++ b/src/strings/example_test.go
@@ -247,14 +247,23 @@ func ExampleSplitAfterN() {
 }
 
 func ExampleTitle() {
+	// Compare this example to the ToTitle example.
 	fmt.Println(strings.Title("her royal highness"))
-	// Output: Her Royal Highness
+	fmt.Println(strings.Title("loud noises"))
+	fmt.Println(strings.Title("хлеб"))
+	// Output:
+	// Her Royal Highness
+	// Loud Noises
+	// Хлеб
 }
 
 func ExampleToTitle() {
+	// Compare this example to the Title example.
+	fmt.Println(strings.ToTitle("her royal highness"))
 	fmt.Println(strings.ToTitle("loud noises"))
 	fmt.Println(strings.ToTitle("хлеб"))
 	// Output:
+	// HER ROYAL HIGHNESS
 	// LOUD NOISES
 	// ХЛЕБ
 }