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

[Roger Riggs]

Hi Stephen,

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.

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.

Roger


On 01/14/2013 06:52 PM, Stephen Colebourne wrote:
> I've taken a look. I agree with most of it, but I can't say that I 
> agree with replacing <h5>. The <p class="strong"> provides less 
> semantic information to the HTML and would generally be considered bad 
> HTML. It is also worse for disabled accessibility (non visual readers 
> get less information to interpret). If this is a new Oracle 
> requirement, then so be it. However, I do believe that there are 
> numerous other examples of header tags being used in the JDK.
>
> Stephen
>
>
>
>
> On 14 January 2013 21:03, Roger Riggs <Roger.Riggs at oracle.com 
> <mailto:Roger.Riggs at oracle.com>> wrote:
>
>     Please review updates to Javadoc to satisfy DocLint
>     http://cr.openjdk.java.net/~rriggs/webrev-issue202/
>     <http://cr.openjdk.java.net/%7Erriggs/webrev-issue202/>
>
>         remove '/' from '<'br / '>'
>           use html not xhtml
>         change use of H4 and H5 to use P style="strong" paragraphs.
>           (I18N of html requires starting at H1 but that doesn't make
>         sense.
>         Add missing @param tags
>         Add missing @return tags
>         Change package.html to package-info.java
>         Add Caption tags to tables
>         Close unclosed PRE tags
>         Correct the ChronoLocalDate examples
>
>
>     -- 
>     Thanks, Roger
>
>     Oracle Java Platform Group
>
>     Green Oracle <http://www.oracle.com/commitment> Oracle is
>     committed to developing practices and products that help protect
>     the environment
>
>
>     ------------------------------------------------------------------------------
>     Master Visual Studio, SharePoint, SQL, ASP.NET <http://ASP.NET>,
>     C# 2012, HTML5, CSS,
>     MVC, Windows 8 Apps, JavaScript and much more. Keep your skills
>     current
>     with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
>     MVPs and experts. SALE $99.99 this month only -- learn more at:
>     http://p.sf.net/sfu/learnmore_122412
>     _______________________________________________
>     threeten-develop mailing list
>     threeten-develop at lists.sourceforge.net
>     <mailto:threeten-develop at lists.sourceforge.net>
>     https://lists.sourceforge.net/lists/listinfo/threeten-develop
>
>
>
> ------------------------------------------------------------------------------
> Master Visual Studio, SharePoint, SQL, ASP.NET, C# 2012, HTML5, CSS,
> MVC, Windows 8 Apps, JavaScript and much more. Keep your skills current
> with LearnDevNow - 3,200 step-by-step video tutorials by Microsoft
> MVPs and experts. SALE $99.99 this month only -- learn more at:
> http://p.sf.net/sfu/learnmore_122412
>
>
> _______________________________________________
> threeten-develop mailing list
> threeten-develop at lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/threeten-develop