Generating and cleaning up our JavaDoc

[Richard Bair]

Another approach is to have a local copy of gradle.properties and put the BUILD_JAVADOC=true line in that file.

> On Nov 11, 2013, at 7:52 AM, Kevin Rushforth <kevin.rushforth at oracle.com> wrote:
> 
> Thanks, Jonathan, I think this is a worthy effort. I usually use the latter (... clean sdk) to build the javadoc at the same time I build the SDK when I want to look at the javadoc-generated API docs, but either should work.
> 
> -- Kevin
> 
> 
> Jonathan Giles wrote:
>> 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
>>