RFR: 8342808: Javadoc should add whitespace between type parameters

[Hannes Wallnöfer]

On Tue, 29 Oct 2024 11:14:54 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

> Please review this patch to render javadocs as `<K, V, T>` rather than `<K,V,T>` to match naming conventions and make the rendered output slighly nicer to read.
> 
> Passes langtool tests.
> 
> The[ generated docs](https://cr.openjdk.org/~nbenalla/GeneratedDocs/TypeParams/docs/api/index.html) only includes `java.base/lang`, `java.base/util` and `java.compiler/javax`

> Not all reviewers might realise it, but javadoc currently outputs generics both ways, with whitespace and without. For example, have a look at [Map.of](https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Map.html#of()). The first occurrence of generic parameters (i.e. declaration), immediately after the `static` keyword, has whitespace. The second occurrence (i.e. use) does not. I think we need to make up our mind on what we should do.

I just looked into this, and what actually happens is that we have a special `HtmlLinkInfo.addLineBreaksInTypeParameters` flag to insert a newline character after the comma just for this particular case, but the CSS for this particular span of the method signature uses `white-space: normal;`, so the newline character is displayed as space. 

The code to add the newline in this particular position is rather ancient (previously encoded as `HtmlLinkInfo.Kind.MEMBER_TYPE_PARAMS`), and it was certainly never meant to be displayed with preformatted whitespace, so IMO the most likely reason to do this was to add a line break opportunity before we used `<wbr>`. Therefore, regardless of whether we decide to add a space or not, that flag and special case can be safely removed.

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

PR Comment: https://git.openjdk.org/jdk/pull/21759#issuecomment-2450498640