Merge pull request #50041 from microsoft/fix/47969

Fix(47969): String.prototypr.replace docs fix
microsoft · Sep 28, 2022 · b09e93d · b09e93d
2 parents 0ac12bb + 8e71f42
commit b09e93d
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 7 deletions.
diff --git a/src/lib/es2015.symbol.wellknown.d.ts b/src/lib/es2015.symbol.wellknown.d.ts
@@ -219,9 +219,9 @@ interface String {
     match(matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null;
 
     /**
-     * Replaces first match with string or all matches with RegExp.
-     * @param searchValue A string or RegExp search value.
-     * @param replaceValue A string containing the text to replace for match.
+     * Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.
+     * @param searchValue An object that supports searching for and replacing matches within a string.
+     * @param replaceValue The replacement text.
      */
     replace(searchValue: { [Symbol.replace](string: string, replaceValue: string): string; }, replaceValue: string): string;
 

diff --git a/src/lib/es5.d.ts b/src/lib/es5.d.ts
@@ -423,8 +423,8 @@ interface String {
 
     /**
      * Replaces text in a string, using a regular expression or search string.
-     * @param searchValue A string to search for.
-     * @param replaceValue A string containing the text to replace for every successful match of searchValue in this string.
+     * @param searchValue A string or regular expression to search for.
+     * @param replaceValue A string containing the text to replace. When the {@linkcode searchValue} is a `RegExp`, all matches are replaced if the `g` flag is set (or only those matches at the beginning, if the `y` flag is also present). Otherwise, only the first match of {@linkcode searchValue} is replaced.
      */
     replace(searchValue: string | RegExp, replaceValue: string): string;
 

diff --git a/tests/baselines/reference/completionsStringMethods.baseline b/tests/baselines/reference/completionsStringMethods.baseline
@@ -1048,7 +1048,7 @@
                   "kind": "space"
                 },
                 {
-                  "text": "A string to search for.",
+                  "text": "A string or regular expression to search for.",
                   "kind": "text"
                 }
               ]
@@ -1065,7 +1065,53 @@
                   "kind": "space"
                 },
                 {
-                  "text": "A string containing the text to replace for every successful match of searchValue in this string.",
+                  "text": "A string containing the text to replace. When the ",
+                  "kind": "text"
+                },
+                {
+                  "text": "{@linkcode ",
+                  "kind": "link"
+                },
+                {
+                  "text": "searchValue",
+                  "kind": "linkName",
+                  "target": {
+                    "fileName": "lib.d.ts",
+                    "textSpan": {
+                      "start": 18880,
+                      "length": 28
+                    }
+                  }
+                },
+                {
+                  "text": "}",
+                  "kind": "link"
+                },
+                {
+                  "text": " is a `RegExp`, all matches are replaced if the `g` flag is set (or only those matches at the beginning, if the `y` flag is also present). Otherwise, only the first match of ",
+                  "kind": "text"
+                },
+                {
+                  "text": "{@linkcode ",
+                  "kind": "link"
+                },
+                {
+                  "text": "searchValue",
+                  "kind": "linkName",
+                  "target": {
+                    "fileName": "lib.d.ts",
+                    "textSpan": {
+                      "start": 18880,
+                      "length": 28
+                    }
+                  }
+                },
+                {
+                  "text": "}",
+                  "kind": "link"
+                },
+                {
+                  "text": " is replaced.",
                   "kind": "text"
                 }
               ]