8016217: More javadoc warnings

Mike Duigou mike.duigou at oracle.com
Mon Jun 10 18:04:21 UTC 2013


I took a pass through the patch and nothing leaped out at me either. I wondered about the use of   to prevent an expression from breaking across lines but decided it's OK.

On Jun 10 2013, at 03:31 , Alan Bateman wrote:

> 
> About 8 months ago I tried an early build of doclint [1] and used it to fix up a bunch issues at the time [2]. It's been awhile, so I decided to try out the latest version to see how it has progressed. All I can say is "Yikes".  The good news is that they reported against the original source and that makes it easy when compared to tools that validate the generated html.
> 
> I decided to fix up a few issues, mostly syntax (escaping of > and < in particular) and a few reference issues that were missed the last time (or are new). There are thousands of other issues for anyone that wants to jump in.
> 
> I've put the webrev with the changes here:
> 
> http://cr.openjdk.java.net/~alanb/8016217/webrev/
> 
> In total this fixes ~500 issues, although 270 of those were coming from java.sql.DatabaseMetaData due to the number of un-escaped usages of  "=>". In many cases, the changes are simply to use {@code ..} or replace <code> with {@code ...}. It is tempting to just do a global replace on existing <code></code> usages (would fixing up content that is escaped of course).

Yes, it's very tempting to do a global pass of:

<code>([^<]*)</code> -> {@code $1}
<tt>([^<]*)</tt> -> {@code $1}
<i>(.*)</i> -> <em>$1</em>

For backporting reasons it would be nice to do this simultaneously for the 7u-dev repo as well. Perhaps at the time of the JDK 9 repo split?

With the changes in definitions of i, em, b, strong elements in HTML 5 (http://html5doctor.com/i-b-em-strong-element/) it's no longer important to convert <b> tags to <strong> tags.

> I've run specdiff on the before & after to check that I didn't mess anything up. One obvious difference is that code examples that use generics now have the type parameters going through to the generated javadoc.
> 
> The webrev touches many areas but as the changes are trivial, I don't need a reviewer from every area.
> 
> -Alan.
> 
> [1] http://openjdk.java.net/jeps/172
> [2] http://hg.openjdk.java.net/jdk8/tl/jdk/rev/39cbe256c3d1




More information about the core-libs-dev mailing list