PHP/PregQuoteDelimiter: add XML documentation

[rodrigoprimo]

Description

This PR adds XML documentation for the WordPress.PHP.PregQuoteDelimiter sniff.

The documentation is based on the work started by @tikifez in #2487. I squashed the original commits and, in a separate commit, made subsequent changes based on the review left in #2487.

I suggest squashing those two commits before merging. I'm opening the PR without doing that to make it easier to tell my changes apart from the original changes.

Suggested changelog entry

N/A

Related issues/external references

Related to: #1722
Supersedes: #2487

[jrfnl]

@rodrigoprimo Thanks for picking this up!

I do think this needs more work though to ensure that the documentation isn't just technically correct, but also helps people to understand why they should follow this best practice.

[jrfnl]

Suggested change

	Passing the $delimiter parameter to preg_quote() is strongly recommended to ensure the delimiter used in the regex is properly escaped.
	Passing the $delimiter parameter to preg_quote() is strongly recommended to ensure the regular expression delimiter is properly escaped if it occurs in the arbitrary text string passed to `preg_quote()`.

Just to be clear: The $delimiter is not used in the regex, it is used to deliminate the regex (outside boundaries). The whole point of passing the deliminator to preg_quote() is to prevent that character from ending up in the regex without escaping (which will often break the regex and can lead to security issues/fatal errors/etc).

This part of the original description was not wrong in that respect:

If it is not passed, the default delimiter / is presumed, which is often wrong.

[rodrigoprimo]

I implemented your suggestion with a small change to avoid using preg_quote() twice.

This part of the original description was not wrong in that respect:

If it is not passed, the default delimiter / is presumed, which is often wrong.

I'm not sure whether we are interpreting the above statement differently, but I don't think it is correct. I read it as saying that if the $delimiter parameter is not passed, the function uses / as the default value, which is not the case.

[jrfnl]

This part of the original description was not wrong in that respect:

If it is not passed, the default delimiter / is presumed, which is often wrong.

I'm not sure whether we are interpreting the above statement differently, but I don't think it is correct. I read it as saying that if the $delimiter parameter is not passed, the function uses / as the default value, which is not the case.

Ah, good point. All the more reason for the $delimiter needing to be passed.

[rodrigoprimo]

Thanks for your review, @jrfnl. I implemented the changes you suggested, with a few minor modifications.

[jrfnl]

Thanks @rodrigoprimo ! Happy with it as it is now.

Just left one non-blocking suggestion inline to consider.

[rodrigoprimo]

Just documenting that I squashed all the commits into one without changes.