Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Correctly escape Javadoc code snippets (#1397)
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:
```java
/**
* <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:
```java
This contains an @ and {unbalanced braces
```
we now generate:
```java
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- Loading branch information
