[doc] Improve documentation for Suppression

Part of #1139

• Some formulations in the first section are confusing
• State clearly which languages support // NOPMD suppressions
• Provide a better index for suppression alternatives by language?
  I guess people say "how do I suppress this in Java" rather than
  "let's see if I can suppress this with an annotation…"
• At least cross-link with CPD Suppressions section, as people may look for it here.

Original request:

Affects PMD Version:
6.0.1

Rule:
Documenation. No specific rule.

Description:
The use of Violation Suppress Regex and Violation Suppress XPath needs better examples.

For the regex, it's not clear which message has to be matched (html?, xml?, what delimits "a" message?).

For XPath, a tutorial of how to use the "designer" would be great, plus a few real live examples that show how to find the right XPath expression for a specific rule.

And an explanation where in the AST the rule will match, so that one knows where a construct like ".[typeof(...)]" matches.

Read the current Suppression documentation and the linked CPD Suppressions section first. Clarify the wording, document which languages support // NOPMD, organize suppression alternatives by language, and add understandable regex and XPath examples, including guidance for the designer. Done means the documentation addresses the listed confusion and provides the requested cross-link and examples.