RFR: JDK-8300914: Allow `@` as an escape in documentation comments [v2]

[Pavel Rappo]

On Wed, 1 Feb 2023 19:43:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a moderately simple update to permit the use of `@` as the escape character in a limited set of escape sequences.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains two commits:
> 
>  - Merge with upstream/master
>  - JDK-8301294: Allow `@` as an escape in documentation comments

src/jdk.compiler/share/classes/com/sun/source/doctree/EscapeTree.java line 37:

> 35:  * <ul>
> 36:  *     <li>{@code @@}, representing {@code @}, where it would otherwise be treated as introducing a block or inline tag,
> 37:  *     <li>{@code @/}, representing {@code /}, as part of {@code *@/} to represent <code>*/</code>, and

For other reviewers. Interpret that middle bullet literally: `@` escapes `/` only if it is preceded by `*`. In other words, it's a triple `*@/`, not a pair `@/`.

`@/` without preceding `*` causes errors if it can be confused for a start of a tag.

For a block tag:

    error: no tag name after '@'
         @/
          ^

For an inline tag:

    error: no tag name after '@'
         {@/
          ^

(FWIW, @jonathan-gibbons, note that the caret positions differ: the former points to `/` while the latter points to `@`. )

`*` is a sort of looked-behind and not consumed, which can be seen from the fact that

    /**
     @*@/
     */

is translated to this in documentation

    */

Given all of the above, I'm not sure if `@/` can be technically qualified as an ordinary escape sequence.

-------------

PR: https://git.openjdk.org/jdk/pull/12372