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

Below are my initial comments on the API; I'll have a look at the implementation soon.

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.

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

> 47:      *
> 48:      * <p>Note: this method returns the escaped character, not the original escape sequence.
> 49:      *

Remove newline.

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.

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeScanner.java line 296:

> 294:     }
> 295: 
> 296: 

Remove newline.

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

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