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

Jonathan Gibbons jonathan.gibbons at oracle.com
Fri Mar 27 03:23:26 UTC 2020


Hannes,

I believe I have addressed all your comments.

I fixed all the longer boilerplate text that appears in doc comments, 
and left one
instance of the more detailed text in the introductory '//' comment at 
the beginning
of the group.

Thanks again for your feedback.

-- 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
>>
>>


More information about the javadoc-dev mailing list