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
