regexp: improve Regexp.ReplaceAllString documentation related to Expand part

Fixes #40329

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")))
+
+	// $1W evaluated as ${1W}
+	// $1W is not a named submatch, so the replacement is with an empty slice.
+	fmt.Printf("%s\n", re.ReplaceAll([]byte("-ab-axxb-"), []byte("$1W")))
+
+	re2 := regexp.MustCompile(`a(?P<1W>x*)b`)
+	// $1W is a named submatch, so the replacement is with a matched slice.
+	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

@@ -573,8 +573,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,
+// and "$1x" is equivalent to "${1x}", not "${1}x".
 func (re *Regexp) ReplaceAllString(src, repl string) string {
 	n := 2
 	if strings.Contains(repl, "$") {