8000269: Cleanup javadoc warnings

[Iris Clark]

Hi, Alan.

Looks fantastic!

By fixing these javadoc warnings for @throws and @param, I'm assuming that we will be changing the generated javadoc.  Are any of these changes significant enough to warrant a ccc?  Most of the changes looked fairly innocuous but there are a couple here and there (e.g. java.lang.management.ThreadInfo, java.util.JapaneseImperialCalendar) that may warrant a closer look.

In java.util.Locale it looks like you determined that the '/' used for tag self-termination is unacceptable.  Does it need to stay there now that you've done the explicit termination?

(e.g. 
your new l86: <dt><a name="def_language"/><b>language</b></a></dt>
Proposed new: <dt><a name="def_language"><b>language</b></a></dt>
)

Thanks,
iris

-----Original Message-----
From: Alan Bateman 
Sent: Saturday, September 29, 2012 1:52 PM
To: core-libs-dev
Subject: 8000269: Cleanup javadoc warnings


A small number of javadoc warnings have sneaked into the jdk8 builds lately. They are easily fixed but it's a good opportunity to try out Jon's doccheck tool [1], built on the DocTree API, and get a better workout. I decided to mostly focus on -Xmsgs:reference, which covers references like @param and @throws. I fixed a small number of html issues along the way but that was not my focus. The webrev, which fixes up most of the reference issues in roughly the core area, is here:

http://cr.openjdk.java.net/~alanb/8000269/webrev/index.html

When I say "most" then I excluded j.u.c and java.lang.invoke.

The reason that so many files are changed is because doccheck looks at private and package-private classes and methods that wouldn't normally be in the javadoc. Also, no foray into the *Permission classes is possible without fixing up at least a few formatting issues. Note that there is one non-javadoc change in this webrev; in java.net.Inet4Address I have removed a private static field that has not been used for several releases.

The changes are trivial and easy to review. At it covers many areas then partial reviews are okay too.

Thanks,

Alan.

[1]
http://mail.openjdk.java.net/pipermail/compiler-dev/2012-September/004800.html