Gradle Javadoc documentation missing methods

[big-guy]

The Javadoc for StandardJavadocDocletOptions contained a setTagletPath(java.util.List) in 3.4:
https://docs.gradle.org/3.4/javadoc/org/gradle/external/javadoc/StandardJavadocDocletOptions.html#setTagletPath(java.util.List)

But in 3.5, it doesn't:
https://docs.gradle.org/3.5/javadoc/org/gradle/external/javadoc/StandardJavadocDocletOptions.html

This method wasn't removed, but it has never had any Javadoc:
https://github.com/gradle/gradle/blob/master/subprojects/language-java/src/main/java/org/gradle/external/javadoc/StandardJavadocDocletOptions.java#L941

I'm not sure what changed between 3.4 and 3.5. Maybe the minor version of Java 7 we usually build with? /cc @wolfs @donat

Since the Javadoc is the source of truth for our public APIs, this is a serious problem. @eriwen We should fix this before 4.1 final and regenerate the docs for 3.5, 4.0 and 4.0.1.

[big-guy]

I just noticed that it's worse than that. The inherited methods are missing and the methods that do exist, don't have a "full" entry like you see in 3.4.

[jjohannes]

It's not a general problem with our Javadoc. So it is not a serious problem as feared.

It is only with the javadoc of StandardJavadocDocletOptions. Everything is actually there in the page sources of 3.4.

The problem is that 4a091a4 moved Javadoc from private fields to public methods in StandardJavadocDocletOptions.java. So it actually added more Javadoc. Unfortunately, one of these doc blogs contains an unescaped <title>. This breaks the rendering of the page.

[wolfs]

Can't we fail the build on invalid Javadoc?

[wolfs]

Seems like we could build our Javadoc with Java 8 in some test build: http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

[jjohannes]

Yes. We just need to turn it on before... 🙈

gradle/subprojects/docs/docs.gradle

Line 429 in 3c89e4c

options.addStringOption 'Xdoclint:none', '-quiet'

[big-guy]

Awesome, much relieved.

[jjohannes]

The Javadoc fix/improvement for StandardJavadocDocletOptions and CoreJavadocOptions are now on release.

As for activating doclint(Java 8): I activated it now (not yet on CI) for the categories syntax and reference. I also would like to activate it for html, but that fails on our autoTested attribute in <pre> blocks (error: unknown attribute: autoTested).

I fixed all warnings and errors by running locally, including the html warnings except for the autoTested thing. It actually found a few things that were formatted wrong. The fixes are on release as well.

[big-guy]

Thanks @jjohannes -- could we change <pre autoTested=''> into something supported like <pre class="autoTested">?

If doclint supported HTML5, we could use data-*, but we have to use HTML4.

[jjohannes]

@big-guy Yes we could. Good idea. We just detect it like this:

file.text.eachMatch(/(?ms).*?<pre autoTested.*?>(.*?)<\/pre>(.*?)/)

[jjohannes]

Done: 907a4e7

[jjohannes]

Java 8 javadoc is now part of Sanity Check (fd3486c) executing the syntax, html and reference checks.

[big-guy]

Awesome, thanks @jjohannes