Javadoc destination directory being deleted

[davidbokor]

One of our projects uses an external SDK and we want to have our Javadocs include the classes from that external project. We copy the javadocs into a subdirectory of $buildDir/javadocs and link to them as follows:

task unzipOtherProjectDocs(type:Copy) {
	into "$buildDir/javadocs/someOtherProject"
	from zipTree(configurations.someOtherProjectDocs.singleFile)
}

javadoc {
	...
	dependsOn unzipOtherProjectDocs
	options.links("https://docs.oracle.com/javase/8/docs/api/")
	options.links("/someOtherProject")
}

Starting with Gradle 5 and verified with 5.1.1 and 5.2, we get the following warning while building:

javadoc: warning - Error reading file: c:\MyProject\build\javadocs\someOtherProject\package-list

...and the links to the javadocs in /someOtherProject no longer work.

I thought it might be related to Issue #8183 but since has been fixed, perhaps not.

[davidbokor]

It turns out that starting with Gradle 5, the Javadoc plugin is deleting the destination directory before executing.. There doesn't seem to be a way to disable that. Is there a reason for this behavior change?

[thc202]

That was changed per #6168.

[davidbokor]

It doesn't look like there's a way to disable the cleaning of the directory or to inject some task that runs after the clean. Perhaps either could be added?

I'm a little surprised that #6168 was implemented instead of just suggesting adding a doFirst() to the task declaration.

[big-guy]

This is intentional behavior for the reasons in #6168. The Javadoc task should just work out-of-the-box, so asking users to add a doFirst wouldn't work. Making sure the output represents only the output from the javadoc task lets Gradle cache the output in the build cache.

Could you get by with something like:

task unzipOtherProjectDocs(type: Sync) { 
    into "$buildDir/extdocs/someOtherProject" 
    from zipTree(configurations.someOtherProjectDocs.singleFile) 
} 

javadoc { 
    dependsOn unzipOtherProjectDocs 
    options.links("https://docs.oracle.com/javase/8/docs/api/") 
    options.links("../extdocs/someOtherProject") 
}