[threeten-dev] [threeten-develop] Review for updates to javadoc

[Stephen Colebourne]

On 15 January 2013 02:01, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> The <h5> with the normal stylesheet used in the JDK is a bold font just a
> bit larger.
> The individual packages have no control over the style sheet.
> If the H5 is being used for the appearance then it is a mis-use of the
> header.
>
> The HTML accessibility guides (Oracle's anyway) dictate that headers start
> with H1 and be sequential.
>
> With respect to other paackage use of Hx, I have not yet seen what clean
> up will need to be done.
> That may result in the conventions being clarified and updated.

Well, the strong <p> you changed it to has no effect in the Javadoc
HTML view, so it looks like we have no headings at all now. This
change needs putting back or fixing - everywhere else in the JDK is
using <hx>.


> One of the items that came up in the internal review is that the content
> of the "implementation notes"
> is in many cases normative.  The interpretation of "implementation notes"
> in the JDK is informative,
> an implementation may follow the advice but is not required to.  We will
> have to review all
> of the implementation notes and change the language to be specific about
> whether it is a must, should or may.
> The headings themselves need to make it clear whether the paragraph is
> normative or informative.

The only "implementation notes" remaining in hg are on non-public classes.
Stephen