RFR: JDK-8250766: javadoc adds redundant spaces when @see program element is wrapped [v3]

[Hannes Wallnöfer]

On Mon, 3 May 2021 17:52:12 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This changes reference parsing in `DocCommentParser` to normalize whitespace in signatures to a large extent. In particular, multiple whitespace characters are coalesced into a single space character, and whitespace after opening parentheses and angle brackets are suppressed.
>
> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   JDK-8250766: Add comments

Thanks for the review, Pavel.

>     1. Is whitespace immediately preceding `(` expected to be retained? For example, in
> 
> 
> ```
> @see        java.net.URL#URL
>             (java.lang.String,
>              ...
> ```

`DocCommentParser#reference` only accepts whitespace within matching `()` or `<>`. A whitespace character before the parentheses as shown above will result in `java.net.URL#URL` being considered the reference and the part in parentheses being considered the label.

> 
>     1. Can ReferenceTree.getSignature return null? I dislike unnecessary null checks.

Yes, it can. This is covered by test/langtools/jdk/javadoc/doclet/testTagMisuse/TestTagMisuse.java
 
>     2. The test should also check for whitespace around `,` and `.`

Good point, I'll add a commit with a test covering these cases.

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

PR: https://git.openjdk.java.net/jdk/pull/3754