Javadoc task doesn't generate package links

Old Forum Archive Bugs
1

My team’s doc comments use links to package documentation, not just class documentation. Gradle’s javadoc task fails the generate these links.

Steps to reproduce:

  1. Download and extract gradle_javadoc_bug.zip (14.9 KB)
  2. Run gradle javadoc. (I’m using gradle 2.5)

Actual Result:

…\src\main\java\pkga\A.java:7: warning - Tag @see: reference not found: pkgb

and the link is not actually generated.

Expected Result:

No warning and the link is actually generated. Try running javadoc -d jdout -sourcepath src/main/java -subpackages pkga:pkgb to see it work properly.

2

You’ll need to configure the javadoc task with the -subpackages argument. Gradle doesn’t set this automatically.

3

Thanks for the response.

I tried updating my build.gradle to the following:

apply plugin: 'java'

javadoc {
    options.addStringOption('sourcepath', 'src/main/java')
    options.addStringOption('subpackages', 'pkga:pkgb')
}

That produced the following options to javadoc:

-classpath 'C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\build\\classes\\main;C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\build\\resources\\main'
-d 'C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\build\\docs\\javadoc'
-doctitle 'gradle_javadoc_bug API'
-quiet 
-sourcepath 'src/main/java'
-subpackages 'pkga:pkgb'
-windowtitle 'gradle_javadoc_bug API'
'C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\src\\main\\java\\pkga\\A.java'
'C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\src\\main\\java\\pkgb\\B.java'
'C:\\Users\\david\\Documents\\projects\\bugs\\gradle_javadoc_bug\\src\\main\\java\\pkgb\\package-info.java'

This did produce the package link properly, but resulted in duplicate Javadocs for all of my classes, which is even worse. I couldn’t figure out how to get Gradle to stop listing all the individual source files.

4

Same problem here, but adding ‘subpackages’ option didn’t help in my case.

Gradle 2.6

Build time: 2015-08-10 13:15:06 UTC
Build number: none
Revision: 233bbf8e47c82f72cb898b3e0a96b85d0aad166e

Groovy: 2.3.10
Ant: Apache Ant™ version 1.9.3 compiled on December 23 2013
JVM: 1.8.0_60 (Oracle Corporation 25.60-b23)
OS: Mac OS X 10.10.5 x86_64

5

It looks like this may be because gradle feeds javadoc individual files rather than packages. After I applied the fix I’m proposing on gradle-dev, the links started working for me. Does this track with what others are seeing?

(Observed with Gradle 2.11.)

6

Ross, your fix certainly looks like it would work but I didn’t try it since it was not readily patch-able.

7

Yeah, unfortunately the Gradle Javadoc task does contain a bit of private code around the part that needs to be changed, so the patch has to include some of that. Here’s the source code you can copy into your build.gradle, and then use FullProcessingJavadoc instead of Javadoc:

You can probably comment out the parts dealing with Pegdown if you’re using the standard doclet. That’s the first if block on lines 280-285, and the Files.copy call on lines 295-297

Note that I’m no longer specifying subpackages; instead the latest version just grabs package names from the files included in the SourceTask.

8

Also import java.nio.file.Path as JPath, and in addition to rel.parent != null, it looks like we’d also need to && sourcePath.parent.fileName as String != "doc-files" if commenting out the doc-files copy logic.

9

Ah, thanks for that! I’ll try it out on my old project when I get a chance.

10

Hey, I just wanted to follow up.

I’m having some trouble running your code under my current version of Gradle (2.5). I suppose you’re using a different version. I can’t spend any more time on this right now, but if I ever start working on the affected project again I’ll try this out. Thanks again for the help.