[threeten-dev] [threeten-develop] Review for updates to javadoc
Roger Riggs
Roger.Riggs at oracle.com
Tue Jan 15 08:15:33 PST 2013
Hi Stephen,
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.
>
>
>> 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.
Roger
More information about the threeten-dev
mailing list