javadoc task does not support package links

[alexdmiller]

Expected Behavior

Writing {@link my.package.here} in a Javadoc should produce a link to the package.

Current Behavior

Package level links do not work. Javadoc will give the following warning:

Tag @link: reference not found: my.package.here

Context

The instructions here suggest that adding the -sourcepath and -subpackages flags could help. Here is an attempt at that:

task writeJavadocs(type: Javadoc) {
    source = sourceSets.main.allJava
    classpath = sourceSets.main.runtimeClasspath
    options.addStringOption('sourcepath', 'src/main/java')
    options.addStringOption('subpackages', 'my.package.here')
}

However, this solution fails for me with an exception:

java.lang.IllegalStateException: endPosTable already set
	at com.sun.tools.javac.util.DiagnosticSource.setEndPosTable(DiagnosticSource.java:136)
	at com.sun.tools.javac.util.Log.setEndPosTable(Log.java:350)
	at com.sun.tools.javac.main.JavaCompiler.parse(JavaCompiler.java:670)
	at com.sun.tools.javadoc.JavadocTool.parsePackageClasses(JavadocTool.java:243)
	at com.sun.tools.javadoc.JavadocTool.getRootDocImpl(JavadocTool.java:180)
	at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:346)
	at com.sun.tools.javadoc.Start.begin(Start.java:219)
	at com.sun.tools.javadoc.Start.begin(Start.java:205)
	at com.sun.tools.javadoc.Main.execute(Main.java:64)
	at com.sun.tools.javadoc.Main.main(Main.java:54)
javadoc: error - fatal exception

In summary, it doesn't seem possible to add packages to the command line options through the Gradle javadoc task.

Your Environment

$ gradle -v

------------------------------------------------------------
Gradle 6.0.1
------------------------------------------------------------

Build time:   2019-11-18 20:25:01 UTC
Revision:     fad121066a68c4701acd362daf4287a7c309a0f5

Kotlin:       1.3.50
Groovy:       2.5.8
Ant:          Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM:          10.0.1 ("Oracle Corporation" 10.0.1+10)
OS:           Mac OS X 10.15.5 x86_64

[alexdmiller]

Update:

If I manually edit the javadoc.options file that the javadoc task produces and remove the list of source files at the bottom, then the following options work when I run the javadoc CLI tool manually.

-classpath '...'
-d 'build/docs'
-doctitle 'my docs'
-notimestamp 
-quiet 
-sourcepath 'src/main/java'
-subpackages 'my.package.here'
-windowtitle 'my docs'

However, I'm not able to produce this set of options via the Gradle task. If I remove the source = sourceSets.main.allJava line from my Gradle file, then Gradle prints out the following and does not generate any docs:

> Task :compileJava UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :writeJavadocs NO-SOURCE

[soloturn]

is this related that by default the gradle javadoc task does not create the "uses of class" links, resp the "class-use" folder? hmm - no it is not, one needs to specify the option, currect?

tasks.withType<Javadoc>().configureEach {
                this as StandardJavadocDocletOptions
                addBooleanOption("Xdoclint:none", true)
                addStringOption("Xmaxwarns", "1")
+               encoding = "UTF-8"
+               isUse = true
        }