doc: improve re.ReplaceAllString documentation related to Expand part

Author: eduardbme

src/regexp/example_test.go

@@ -226,13 +226,22 @@ func ExampleRegexp_ReplaceAll() {
 	re := regexp.MustCompile(`a(x*)b`)
 	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("T")))
 	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("$1")))
-	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("$1W")))
 	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("${1}W")))
+
+	// IMPORTANT
+	// $1W considered as ${1W}, NOT ${1}W. As a result you will receive ---
+	// Chances are this is not what you expect. Take a look of how Expand works.
+	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("$1W")))
+
+	re2 := regexp.MustCompile(`a(?P<1W>x*)b`)
+	fmt.Printf("%s\n", re2.ReplaceAll([]byte("-ab-axxb-"), []byte("$1W")))
+
 	// Output:
 	// -T-T-
 	// --xx-
-	// ---
 	// -W-xxW-
+	// ---
+	// --xx-
 }
 
 func ExampleRegexp_ReplaceAllLiteralString() {

src/regexp/regexp.go

@@ -565,8 +565,11 @@ func Match(pattern string, b []byte) (matched bool, err error) {
 }
 
 // ReplaceAllString returns a copy of src, replacing matches of the Regexp
-// with the replacement string repl. Inside repl, $ signs are interpreted as
-// in Expand, so for instance $1 represents the text of the first submatch.
+// with the replacement string repl.
+// 
+// Inside repl, $ signs are interpreted as in Expand,
+// so for instance $1 represents the text of the first submatch,
+// but "$1W" evaluated as "${1W}", not "${1}W"
 func (re *Regexp) ReplaceAllString(src, repl string) string {
 	n := 2
 	if strings.Contains(repl, "$") {