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

[Joe Darcy]

On Wed, 2 Aug 2023 21:39:02 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> 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` ?

Hmm. Does the precise handling of line terminators matter enough to specify?

> src/java.compiler/share/classes/javax/lang/model/util/Elements.java line 286:
> 
>> 284:      * begins with "{@code /**}", ends with a separate
>> 285:      * "<code>*/</code>", and immediately precedes the element,
>> 286:      * ignoring white space and annotations and end-of-line-comments ({@code "//"} comments).
> 
> Turns out that simple block comments are ignored as well. Try:
> 
> /**
>  * This is HW.
>  */
> /* block comment. */
> // line comment
> public class HW { }

Will update accordingly.

> src/java.compiler/share/classes/javax/lang/model/util/Elements.java line 300:
> 
>> 298:      * if the lines start with <em>zero</em> or more white space characters followed by
>> 299:      * <em>one</em> or more "{@code *}" characters,
>> 300:      * those leading white space characters are discarded as are any
> 
> FWIW, I checked `javac` and it allows form-feed in the leading whitespace characters
> 
> As an adjective "white space" is normally a single word, at least in JDK.

Hmm. java.lang.Character contains both "whitespace" and "white space" in its textual comments.

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

PR Comment: https://git.openjdk.org/jdk/pull/15062#issuecomment-1666140009
PR Review Comment: https://git.openjdk.org/jdk/pull/15062#discussion_r1284822082
PR Review Comment: https://git.openjdk.org/jdk/pull/15062#discussion_r1284823732