RFR: 8214126: Method signatures not formatted correctly in browser

[Jonathan Gibbons]

Hmmm, comments/questions/reservations.

Ironically, your RFR email is hard to read in the mail archive[1] 
because the text doesn't flow properly. I think there's a message in that!

Looking at the .png files, In the list of type parameters, there's no 
(visible) space after ",", even though there are spaces within each type 
paramwter. That seems wrong, and should be fixed.

Reading the review was mildly confusing at first, because webrev does 
not correctly encode the entity for zero-width space, and so it renders 
as, well, a zero-width space!  The patch files show the correct text.

You're not changing this, but I will say I dislike using RawHtml as a 
way of handling entities. I've long felt that Entity should be its own 
new subtype of Content.  Maybe one of these days we'll fix that ...

I like the enforced newlines between annotations and the signature, and 
after a long series of type parameters.  I'm less of a fan of the 
newline after each argument, and even less a fan of the coding style 
that indents everything relative to the left parenthesis, resulting, in 
this case, in huge amounts of whitespace on the left.  Why do lots of 
type parameters get displayed "horizontally" but method parameters get 
displayed "vertically"?  I know you've posted .png files, but my browser 
auto-scales them. It would be more interesting to see the underlying API 
(i.e. html files), so that we could see how those pages react on small 
screens, such as an 11" laptop (not shooting for tablet size, yet)   
Although uncommon in JDK code, what if the method parameters had 
annotations on them as well?

Looking at the "bad" .png files again, I agree that the problem is "not 
enough newlines", but I would suggest the solution is just to put 
newlines when the preceding text or list has become too long, but to let 
each list flow (with indentation). So, looking at the bad 
bigGenericAnnotatedMethod, I think it needs newline after the long 
annotations, newline after the long list of type paremeters, maybe 
newline after the left-parenthesis, and then newline after the right 
parenthesis. I think this could be done by considering the signature as 
a series of "chunks" :   annotations, modifiers, type-parameters, name, 
parameters, throws   and then proactively inserting a newline before 
each chunk if the line-length so far plus the length of the line would 
exceed the conventional line length.

-- Jon

[1] 
https://mail.openjdk.java.net/pipermail/javadoc-dev/2019-April/000996.html


On 04/02/2019 07:48 AM, Hannes Wallnöfer wrote:
> Please review:
>
> Issue: https://bugs.openjdk.java.net/browse/JDK-8214126
> Webrev: http://cr.openjdk.java.net/~hannesw/8214126/webrev.00/
>
> In JDK 11 we changed rendering of method signatures in the method details section of class pages to non-preformatted rendering. The reason was that long list of type parameters would completely derail the rendering of signatures (see JDK-8187288).
>
> Since I think the preformatting is actually quite valuable for more complex signatures I reintroduced it and added code to insert line breaks for very long type parameter lists. This also fixes a bug in RawHtml::charCount so that the zero-width-space entity is not counted as adding to the character count.
>
> You can see before/after screenshots attached to the Jira issue. (These screenshots are generated from the test in this patch.)
>
> https://bugs.openjdk.java.net/secure/attachment/81939/simple-methods-bad.png
> https://bugs.openjdk.java.net/secure/attachment/81940/simple-methods-fixed.png
> https://bugs.openjdk.java.net/secure/attachment/81937/generic-annotated-bad.png
> https://bugs.openjdk.java.net/secure/attachment/81938/generic-annotated-fixed.png
>
> Thanks,
> Hannes