RFR: 8214126: Method signatures not formatted correctly in browser

Fri Apr 5 17:51:56 UTC 2019

I've been thinking about this some more ...

It seems you prefer to present method arguments in an "aligned vertical 
style" while I personally prefer to see a "flowing horizontal style" 
..and therein lies the possibility of supporting both. The key is that 
these are just different styles, and so we should be leveraging CSS as 
much as possible, instead of hard-baking the presentation style into the 
doclet code and generated docs.   Now, I realize that we cannot do 
everything that you are trying to do in this changeset with CSS, but we 
can certainly do more ... instead of backtracking and removing the use 
of the one style that was previously present!

In particular, the main restriction I see is that different styles (i.e. 
stylesheets) cannot be selected by the end-user, but they /can/ be 
selected by the API author or other person generating the docs when 
running javadoc, assuming the existence of a reasonable specification on 
the use of styles in the docs!. Another restriction is the lack of 
ability to change the style depending on the amount of content in any 
node, but maybe we can workaround that.

With that in mind, I noted yesterday that a method signature was like a 
series of chunks: annotations, modifiers, type-parameters, name, 
parameters, throws.   Let me rephrase that and you'll maybe see where I 
am going ... a method signature is a span of content containing a series 
of spans of content of different kinds: annotations, modifiers, etc. In 
other words:

<span class=methodSignature><span class="annos">...</span><span 
class="modifiers>...</span> etc </span>

Now consider how those styles may be presented ...

  * a style of "aligned vertical block" could be display:inline-block ;
    content-after:&x0a;
  * a style of "flowing horizontal style: could be display:block ;
    text-indent: 3em; margin-left: -3em;
  * etc

To get around the lack of ability to set the style depending on the 
amount of content, maybe javadoc generates different styles for "small 
signatures" and "big signatures".  For example, maybe a small signature 
is just written with a single enclosing span of "methodSignature", but a 
signature with long components uses those nested span elements as well.

I think an interesting experiment would be to create a small demo 
document and an associated stylesheet, so that we can see how far we can 
go in terms of simplifying the HTML and leveraging the CSS.

One final point, I note that in responsive web design [1], you can 
select/use different CSS within a single stylesheet depending on the 
size of the viewport. So maybe large screens get to use your "aligned 
vertical block with lots of left-whitespace" and smaller screens get to 
use "flowing horizontal text". That would be most cool.

-- Jon

[1] https://www.w3schools.com/css/css_rwd_intro.asp

On 4/4/19 3:23 PM, Jonathan Gibbons wrote:
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20190405/d0fd2af4/attachment-0001.html>