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

[Jonathan Gibbons]

On Tue, 7 Feb 2023 17:33:02 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Improve spec wording
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 364:
> 
>> 362:     @Override @DefinedBy(Api.COMPILER_TREE)
>> 363:     public Void visitEscape(EscapeTree tree, Void ignore) {
>> 364:         hasNonWhitespaceText = true;
> 
> What's the significance of setting this flag here? It doesn't seem to be set in `visitEntity`, for example.
> 
> Anyway, when I commented L364 out, no tests failed.

It's part of the HTML checking, for [palpable content](https://html.spec.whatwg.org/dev/dom.html#palpable-content)

Some HTML nodes, typically "containers" like `<table>` `<tr>` `<ul>` etc just permit child nodes and whitespace, but no non-white text.  The code here is establishing that the escape characters are treated as non-whitespace characters in any enclosing context.

It is a useful/relevant observation that entities don't set the flag.   I'd have to dig deeper to see if all entities are treated as palpable content in HTML ... the questionable ones being entities like zero-width-space, non-breaking-space etc.  It would be "less wrong" to assume that all entities are not whitespace than to not set the flag at all.

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

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