RFR: 8214126: Method signatures not formatted correctly in browser

Tue Apr 16 14:41:08 UTC 2019

Jon,

I think these are interesting suggestions, and we should definitely explore using CSS to format method signatures.

However, I think this should be a separate issue from the one we’re discussing here, and probably one with a bigger time frame. My change basically just fixes the preformatted layout of method signatures that has been used for (I suppose) a very long time, and was given up for not being able to handle very long lists of type parameters in generic methods. Although that’s not a very frequent concern, it now handles that case decently. All the other formatting properties such as vertically aligned parameters were there before (I agree it’s not essential for two-parameter methods, but it’s very useful for methods with more parameters).

On the other hand, using CSS block formatting for method signatures might might be trickier than it seems. First, there’s inconsistencies in browser implementations, and I’m quite sure we’d have to raise our browser requirements (thinking about IE and Edge, but possibly older versions of other browsers as well). And then there’s other variables such as font size and other user preferences that may easily mess up what otherwise looks fine.

So I’m all for exploring these CSS features, but I think it should be an enhancement with enough time to make sure it works everywhere, and it shouldn’t stop us from fixing the current implementation.

Hannes

> Am 05.04.2019 um 19:51 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>:
> 
> 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 
>> 