Thanks for the review and detailed comments.
"member" is in parentheses because down the road, I would like to
generalize the concept of a signature to include class signatures, which
have a lot of similarity. But that being said, that's down the road and
maybe won't happen exactly like that, so for now, I'll remove the
parentheses. I guess I had in mind that we might be able to make a
general builder-style class called Signature, and be able to give it an
Element.
As for {@link} and {@code}, in general, the prevailing wisdom is that
the first instance in any given context should be linked, and the
following ones should not be linked. This is to prevent an overdose of
blue lines everywhere. The question, of course, in web pages like
these, is what is the "context". I guess here a useful definition of
"context" is "the documentation comment". That all being said, the point
about consistency is noted; I will review the changes based on the
guidelines I just outlined.
I'll see if I can reduce the verbosity.
-- Jon
On 3/25/20 5:01 PM, Hannes Wallnöfer wrote:
Nice to have more CSS classes documented.
Line 200: Why is „member“ in parentheses?
Line 206: "it any contain any of the following“ - first „any“ should probably
be „can“.
Line 207: Should be „parameters“ instead of „arguments“ since we renamed it;
You sometimes use {@code …} tags and sometimes {@link …} tags to refer to other
style names. It would be nice to be consistent and always use {@link …} as it
is more useful.
One think I notice is that the following „boilerplate“ code is a bit lengthy in
and not very informative:
The class of the element used to present the content generated from …
Maybe this could be replaced with something less verbose like:
The class of the element for …
Of course the long version is more precise. Feel free to keep it, it’s a
question of taste.
Otherwise looks good.
Hannes
Am 24.03.2020 um 02:25 schrieb Jonathan Gibbons <[email protected]>:
Please review a reasonably simple, mostly doc-only change to reorder and
document some groups of members of HtmlStyle.
The change is primarily to document members in the conceptual groups regarding
member signatures, flex layout, and descriptions/notes. Other potential groups
will be identified and done separately.
The only code change is to rename `arguments` to `parameters`, in accordance
with standard usage. This requires a corresponding change in the style sheet,
and some updates to tests. The test updates were all done automagically.
-- Jon
JBS: https://bugs.openjdk.java.net/browse/JDK-8241470
Webrev: http://cr.openjdk.java.net/~jjg/8241470/webrev.00/index.html
