Correctly escape Javadoc code snippets

[lunaris]

Escaping code snippets for use in Javadoc comments is non-trivial. By default, Javadoc comments are expected to be HTML markup. While HTML offers <pre> and <code> tags, these only handle formatting and do not remove the need to escape e.g. characters such as < and >. To this end, Javadoc provides options such as {@code ...} for embedding text verbatim. However, these only handle escaping and not formatting. One thus generally combines the two approaches to yield comments like <pre>{@code ...}</pre>. However, this combination itself introduces challenges around escaping:

• @, which normally indicates a Javadoc tag (such as @code itself), needs to be escaped in some situations but not others:

/**
 * <pre>
 * {@code
 * public class C {
 *   // This use of @ needs to be escaped lest Javadoc get confused and think
 *   // it's a nested tag (even though @code should explicitly prevent this).
 *   @SuppressWarnings
 *   public static void m1() {}
 *
 *   // This @ does not need to be escaped.
 *   public static void m2() {}
 * }
 * }
 * </pre>
 */

• Braces ({ and }) need to be escaped if they are not balanced, since Javadoc counts braces in order to work out when to end the @code block.
• The combination */ always needs to be escaped since it would otherwise premutately terminate the Javadoc comment.

Our escaping code is currently broken (see #1363), causing crashes because it fails to handle the case of unbalanced braces. Even in the cases where it does not cause crashes, the Javadoc generated is not necessarily faithful to the input, due to incorrect escaping of @ and */ depending on the context. For instance, while many sources state that {@literal @} is the correct escaping of @ within a @code block, this is not in general true and will result in {@literal @} being produced in the rendered output instead of the desired @.

This commit attempts to fix it once and for all. We do this by adopting a strategy whereby we leave the @code block temporarily when the need to escape a character arises. For example, given:

This contains an @ and {unbalanced braces

we now generate:

This contains an }{@literal @}{@code  and }{{@code unbalanced braces

with the expectation that this will end up inside a <pre>{@code ...}</pre> context. This results in generated comments that are harder to read, but render successfully and accurately, both as HTML Javadoc pages and e.g. hover documentation in most IDEs. We attempt to minimise the impact this will have on real-world SDKs/programs by only escaping if there is a need (that is, if a comment contains @, */, or unbalanced braces). The test suite for Javadoc processing has been bulked out so that hopefully this does not bite again (famous last words!).

Fixes #1363

[lunaris]

Having tested this manually with Azure Native and AWS, I'm going to merge this. Fingers crossed! 🤞