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

[Stephen Colebourne]

On 15 January 2013 16:15, Roger Riggs <Roger.Riggs at oracle.com> wrote:
> On 1/15/2013 10:06 AM, Stephen Colebourne wrote:
> 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>.
>
> Which HTML view is that?  Is it using the stylesheet.css?
>
> I used the ant script to generate the javadoc and checked the results with
> firefox.
>
> It also builds and displays correctly as part of the full JDK javadoc.

I'm using the standard generation from IntelliJ. No style is seen for
the headers in the package info (it is seen in the class/method docs).


> 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.
>
> The "specification for implementors" is similar.  Other JDK classes
> integrate this
> kind of statement and do not separate it.
>
> It is also unclear whether the implementor is someone implementing the JDK
> or a developer using the API.  A more directive statement is needed.

Both. Feel free to suggest something. These do need to be separate
sections so that regular users do not need to read them. Its advanced
specification that only 1% of users should care about (those writing
subclasses, as Oracle won't allow anyone else to implement the JDK, cf
Apache Harmony).

Stephen