Document pytest.warns that matching things with parenthesis needs to be escaped.

[BurnzZ]

There are some cases where we mention a function in a UserWarning with the parenthesis. A simple string matching wouldn't work despite the annotation being match: Optional[Union[str, Pattern[str]]].

Example on pytest==7.2.0:

>>> with pytest.warns(UserWarning, match="issue with foo() func"):
...     warnings.warn("issue with foo() func")
Traceback (most recent call last):
  ...
Failed: DID NOT WARN. No warnings of type (<class 'UserWarning'>,) matching the regex were emitted.
 Regex: issue with foo() func
 Emitted warnings: [UserWarning('issue with foo() func')]

>>> with pytest.warns(UserWarning, match="issue with foo\(\) func"):
...     warnings.warn("issue with foo() func")

[The-Compiler]

The docs indeed are rather confusing about this, surprisingly! Both the how-to and the reference say:

[...] the keyword argument match to assert that the warning matches a text or regex:

and show a rather confusing example:

with warns(UserWarning, match='must be 0 or None'):
    warnings.warn("value must be 0 or None", UserWarning)

with warns(UserWarning, match=r'must be \d+$'):
    warnings.warn("value must be 42", UserWarning)

This seems to have been fixed for pytest.raises in 8b34d98 for #5208, looks like we should do a very similar change for pytest.warns as well.