RFR: JDK-8300914: Allow `@` as an escape in documentation comments [v2]
Jonathan Gibbons
jjg at openjdk.org
Fri Feb 3 00:28:05 UTC 2023
On Thu, 2 Feb 2023 19:38:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:
>> 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.
Note that all the proposed escape sequences are context-sensitive, and are only enabled in appropriate circumstances.
-------------
PR: https://git.openjdk.org/jdk/pull/12372
More information about the compiler-dev
mailing list