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
