RFR: JDK-8307184: Incorrect/inconsistent specification and implementation for Elements.getDocComment [v5]

[Jonathan Gibbons]

On Fri, 28 Jul 2023 05:51:58 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> Start by just reformatting the existing specs to highlight subsequent spec changes.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Appease jcheck.

General feedback: while the text is good at describing when non-newline characters are removed, it is less good at describing the treatment of newlines ... are they line-terminators or line-separators; how do such characters in the result of `getDocComment` relate to the characters in the source file?  For example, does `getDocComment` "copy" the newline characters found in the source file or are they always normalized to `\n` ?

test/langtools/tools/javac/processing/model/util/elements/TestGetDocComments.java line 143:

> 141:      * eiusmod tempor incididunt ut labore et dolore magna aliqua.
> 142:      */
> 143:     @ExpectedComment( // Cannot used a text block here since leading spaces are removed

You could use a text block, by carefully adjusting the indentation of the trailing `"""`

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

PR Comment: https://git.openjdk.org/jdk/pull/15062#issuecomment-1662997672
PR Review Comment: https://git.openjdk.org/jdk/pull/15062#discussion_r1282447161