On Thu, 2 Feb 2023 10:41:27 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> 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.
'/' cannot be part of a tag name.
A tag name starts with a character for which `isUnicodeIdentifierStart` is
true, followed by zero or more characters for which `isUnicodeIdentifierPart`
is true or is one of `.`, `-`, `:`. See `DocCommentParser.readTagName` for
verification. (We should update the Doc Comment Spec for that as well.)
So, the text of error messages above are correct, even if the positions require
tweaking.
-------------
PR: https://git.openjdk.org/jdk/pull/12372
