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

[Jonathan Gibbons]

On Wed, 1 Feb 2023 22:22:07 GMT, Pavel Rappo <prappo at 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/DocTree.java line 110:
> 
>> 108:          * representing some escaped documentation text.
>> 109:          */
>> 110:         ESCAPE,
> 
> We seem to add `@since` to newer kinds of tags.

Yes, ooops, I missed that one

> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 186:
> 
>> 184:      * @since 21
>> 185:      */
>> 186:     EscapeTree newEscapeTree(char ch);
> 
> For the record: I noticed this discrepancy between the `char` parameter here and the `String` return value in `EscapeTree.getBody()` while discussing CSR.
> 
> Initially, I thought that we could use `String` for the parameter too, but you provided reasonable arguments why we should keep it `char`.
> 
> I once again note that it's weird that `DocTreeFactory` is public API.

On `DocTreeFactory`
1. at the time the API was created, it was modeled on the javac AST, and yes, while it might be a bit weird here, it's less weird than the one for javac.
2. `DocTreeFactory` is used in the doclet to create comments for mandated methods, so one way or another, it needs to be public.

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

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