DB/DirectDatabaseQuery: add XML documentation

[rodrigoprimo]

Description

This PR adds XML documentation for the WordPress.DB.DirectDatabaseQuery sniff.

The documentation is based on the work started by @jaymcp in #2458. I used the original commit and, in a separate commit, made the following changes to the original version of the documentation:

• Rewrite standard descriptions to explain why each rule exists.
• Add <em> tags to highlight key parts in code examples.
• Use realistic code examples.
• Replace second caching example with a write + cache invalidation pattern.
• Wrap caching examples in functions, as the sniff always generates a NoCaching warning if the caching code is not inside a function.
• Remove dbDelta() recommendation from SchemaChange section. I believe the original intent of the rule is to discourage schema changes and not suggest dbDelta() is used.
• Remove SchemaChange code comparison (no valid alternative).

I suggest squashing the 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: #2458
Closes #2458

[jrfnl]

@rodrigoprimo Thanks for working on this! Looking good and IMO the examples are helpful.

I just left a few small questions, nothing major.

[jrfnl]

Am I right to presume this doesn't include a code sample as there is no "valid" way of doing this ?

While I understand that choice, this does mean that this sentence at the end of the docs looks a bit lost and can easily be overlooked.

[rodrigoprimo]

That is indeed why I did not include a code sample, but I agree that the sentence at the end looks a bit lost.

I tried a different approach and added a code comparison with an ALTER TABLE example. For the valid side, I used a comment-only approach similar to the IniSet sniff documentation.

Let me know what you think.

[jrfnl]

It may help clarify what is meant by "Altering the database schema" if the SQL keywords the sniff looks for are mentioned ?

[rodrigoprimo]

Good point, done.

[rodrigoprimo]

Thanks for the review, @jrfnl! I believe I addressed all your suggestions.