RFR: JDK-8241470 HtmlStyle: group and document members: description, flex, signature

[Jonathan Gibbons]

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 <jonathan.gibbons at oracle.com>:
>>
>> 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
>>
>>