strings: add note for new Go developers to TrimLeft and TrimRight

If one quickly looks at the strings package godoc, reading the name
TrimLeft, one might think it removes a prefix from the string.

The function's godoc does explain its purpose, but it's apparent that it
is not clear enough, as there have been numerous raised issues about
this confusion: #12771 #14657 #18160 #19371 #20085 #25328 #26119. These
questions are also frequent elsewhere on the internet.

Add a very short paragraph to the godoc, to hopefully point new Go
developers in the right direction faster. Do the same thing for
TrimRight and TrimSuffix.

Change-Id: I4dee5ed8dd9fba565b4755bad12ae1ee6d277959
Reviewed-on: https://go-review.googlesource.com/121637
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/strings/strings.go b/src/strings/strings.go
index adbbe742fcebe65a5d62b204113238bc57ddac67..20868be269461b181d1e3df3a27c6afac13bd8af 100644 (file)
--- a/src/strings/strings.go
+++ b/src/strings/strings.go
@@ -797,6 +797,8 @@ func Trim(s string, cutset string) string {
 
 // TrimLeft returns a slice of the string s with all leading
 // Unicode code points contained in cutset removed.
+//
+// To remove a prefix, use TrimPrefix instead.
 func TrimLeft(s string, cutset string) string {
        if s == "" || cutset == "" {
                return s
@@ -806,6 +808,8 @@ func TrimLeft(s string, cutset string) string {
 
 // TrimRight returns a slice of the string s, with all trailing
 // Unicode code points contained in cutset removed.
+//
+// To remove a suffix, use TrimSuffix instead.
 func TrimRight(s string, cutset string) string {
        if s == "" || cutset == "" {
                return s