Generating and cleaning up our JavaDoc

[Jonathan Giles]

Hi all,

This email serves partly as a useful tip (assuming I'm correct), and
partly as a request for improving the current javadoc build situation.

Firstly, the presumed tip: to generate JavaDoc in our new gradle build
setup, it appears necessary to set BUILD_JAVADOC to true. It would seem
that to do this, you pass in the following to your preferred shell from
within the rt directory:

gradle -PBUILD_JAVADOC=true javadoc

Alternatively, you could do something like:

gradle -PBUILD_JAVADOC=true clean sdk

You can then find the generated documentation in /rt/build/javadoc

If I'm wrong, I look forward to being corrected, now that I'm trying to
clean up the javadoc output prior to 8.0 shipping.

On to the request: we have a lot of javadoc warnings. This is always the
case at this stage of the release, and I always start asking nicely (aka
nagging) so that we get things in order. I've dreamt for a long time
that we would fail the appropriate automated builds whenever a javadoc
warning or error was encountered, and whilst now is not the best time to
do this, perhaps we should look into this after 8.0 freezes.

Anywho, if anyone is keen to help improve the quality of our javadocs, I
am keen to work with you. Please drop me a note. What I really want to
do is get our warning / error count to zero (or as close to it as
possible). We have a lot of warnings like this (just to pick two):

rt\modules\controls\src\main\java\javafx\scene\control\ListView.java:854: warning
- Tag @link: can't find scrollTo(S) in javafx.scene.control.ListView
rt\modules\graphics\src\main\java\javafx\scene\input\DragEvent.java:434:
warning - @param argument "eventType" is not a parameter name.

Thanks,
-- Jonathan