Fix(47969): String.prototypr.replace docs fix

[navya9singh]

Fixes #47969

[typescript-bot]

This PR doesn't have any linked issues. Please open an issue that references this PR. From there we can discuss and prioritise.

[amcasey]

@sandersn Shouldn't this be Author: Team?

[Josh-Cena]

There's an "interesting" aspect where "aaa-a".replace(/a/gy, "x") is xxx-a. I don't know how detailed we want it to be, but "all matches are replaced if the g flag is set" is technically not correct—and arguably less correct than before.

[sandersn]

MDN's documentation for the sticky flag says that it ignores the global flag. If that's true, then I think it's fine to document it as-is, since you'll presumably find out about y long after g and hopefully read about the override.

However, is that consistent with your example? If there's some kind of interaction, it might be worth documenting.

[Josh-Cena]

There's an open issue for it: mdn/content#1454 I just haven't gotten around to fix it.

[orta]

Shouldn't this be Author: Team?

edit: https://github.com/microsoft/TypeScript/blob/main/.github/pr_owners.txt to update this (comes from here)

[amcasey]

Shouldn't this be Author: Team?

edit: https://github.com/microsoft/TypeScript/blob/main/.github/pr_owners.txt to update this (comes from here)

Done. Thanks, @orta!

[sandersn]

Looks pretty good but I'd like to address @Josh-Cena 's point about the sticky flag before merging.

[Josh-Cena]

Suggested change

	* Passes a string and {@linkcode replaceValue} to the [Symbol.replace] method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.
	* Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm.

(Suggestion, dunno if the stdlib has its own style rules about JSDoc. Also @@replace is technically the name for the method—it's only accessed via Symbol.replace)

[sandersn]

I like the formatting improvement, but I think @@replace is only useful for people who have read the spec.

[Josh-Cena]

Yeah, I'm fine with [Symbol.replace]. FWIW, on MDN we consistently use RegExp.prototype[@@replace]() so I hope it's not that obscure, but I can understand.

[sandersn]

I think I would reword this to highlight the interesting global regex case first, and try to cover strings and sticky regexes later.

Suggested change

	* @param replaceValue A string containing the text to replace. When the {@linkcode searchValue} is a string, only the first match is replaced. If the {@linkcode searchValue} is a RegExp, all matches are replaced if the g flag is set. Otherwise only the first one is.
	* @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 (taking into account the y flag if present). Otherwise {@linkcode searchValue} only the first match is replaced.

[sandersn]

Once @Josh-Cena's latest suggestion is adopted (along with my if -> is fix)

[graphemecluster]

@sandersn I can hardly understand that how come the documentation of only 2 out of 4 overloads are updated.
And replaceAll is not touched at all.
Anyway I have updated them in my PR (#50452).