RFR: JDK-8241470 HtmlStyle: group and document members: description, flex, signature
Hannes Wallnöfer
hannes.wallnoefer at oracle.com
Thu Mar 26 00:01:29 UTC 2020
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