Cannot link to javadoc from jdk11's javadoc tool

[ST-DDT]

If I try to run javadoc with the -link option I get an error for the grpc-java's javadoc page.

The issue can be reproduced like this:

Test.java

public class Test {

    public String test() {
        return null;
    }

}

Command line

javadoc -link 'https://grpc.io/grpc-java/javadoc/' Test.java

Error message with jdk 11

javadoc: error - Error fetching URL: https://grpc.io/grpc-java/javadoc/

Unfortunately I couldn't get any details why it failed.

I also tried it with other javadoc pages and that seems to work without problems, even if they are generated by an older javadoc version.

• -link 'https://docs.oracle.com/javase/7/docs/api/'
• -link 'https://docs.oracle.com/javase/8/docs/api/'
• -link 'https://docs.spring.io/spring-framework/docs/5.0.9.RELEASE/javadoc-api/'
• -link 'https://docs.spring.io/spring-security/site/docs/5.0.9.RELEASE/api/'

There aren't any issues if I use jdk 8. But jdk 8 will be EOL soon, so it would be nice if we could add support for jdk 11 there as well.

[carl-mastrangelo]

cc: @dapengzhang0

[dapengzhang0]

I just searched for similar issues on SO and found this https://stackoverflow.com/questions/33866209/linking-to-javadoc-io-using-javadoc-link-option

not tested it out yet.

[dapengzhang0]

From the above SO comments, I found a workaround using -linkoffline:

touch package-list && jdk-11.0.1/bin/javadoc -linkoffline 'https://grpc.io/grpc-java/javadoc/' .  Test.java

To fix the original issue, I think grpc javadoc need to generate a package-list.html page.

[ST-DDT]

I just searched for similar issues on SO and found this https://stackoverflow.com/questions/33866209/linking-to-javadoc-io-using-javadoc-link-option

not tested it out yet.

I tried a few things with gradle, but I was unable to change the failure behavior. I'm not sure whether this is my fault for not correctly configuring the build or the suggestion simply not working.

From the above SO comments, I found a workaround using -linkoffline:

touch package-list && jdk-11.0.1/bin/javadoc -linkoffline 'https://grpc.io/grpc-java/javadoc/' .  Test.java

If you can explain me how I can configure my build tool (gradle 5) to do that...

To fix the original issue, I think grpc javadoc need to generate a package-list.html page.

I would appreciate any server side fix, that does not require any build tool hacks in consuming lib build tool scripts.

[dapengzhang0]

If you can explain me how I can configure my build tool (gradle 5) to do that...

@ST-DDT Can you provide a simple gradle file for your Test.java, so that I can know the way you set up javadoc config in gradle? This would help me verify "server side fix".

[ST-DDT]

Here a packaged test project: test.zip

build.gradle

apply plugin: 'java'

tasks.withType(Javadoc) {
    def links = [
        'https://docs.oracle.com/javase/8/docs/api/',
        'https://grpc.io/grpc-java/javadoc/'
    ];
    options.setLinks(links)
}

Directory-Structure

• src
  • main
  • java
    • Test.java
• build.gradle
• (gradle)
  • ...
• (gradlew)
• (gradlew.bat)

I don't know whether you need the gradle stuff as well, for my tests i copied them from here.

Output-JDK8

$ ./gradlew javadoc
Starting a Gradle Daemon, 3 incompatible and 2 stopped Daemons could not be reused, use --status for details
> Task :compileJava UP-TO-DATE
> Task :processResources NO-SOURCE
> Task :classes UP-TO-DATE
> Task :javadoc UP-TO-DATE

BUILD SUCCESSFUL in 4s
2 actionable tasks: 2 up-to-date

Output-JDK11

$ ./gradlew javadoc
Starting a Gradle Daemon, 3 incompatible and 3 stopped Daemons could not be reused, use --status for details
> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes

> Task :javadoc
javadoc: error - Error fetching URL: https://grpc.io/grpc-java/javadoc/
1 error

> Task :javadoc FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':javadoc'.
> Javadoc generation failed. Generated Javadoc options file (useful for troubleshooting): 'C:\Users\Daniel\git\grpc\test\build\tmp\javadoc\javadoc.options'

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 7s
2 actionable tasks: 2 executed

[dapengzhang0]

Thank you @ST-DDT , that will be very helpful.

[dapengzhang0]

@ST-DDT I upload a workaround here

build.gradle

apply plugin: 'java'

javadoc {
    options {
        links 'https://docs.oracle.com/javase/8/docs/api/'
        linksOffline 'https://grpc.io/grpc-java/javadoc/', '.'
    }
}

Directory-Structure

• src
  • main
  • java
    • Test.java
• build.gradle
• package-list

[dapengzhang0]

@ST-DDT

Solution: Using the URL https://github.com/grpc/grpc-java/tree/gh-pages/javadoc/ instead of https://grpc.io/grpc-java/javadoc/ will work.

Edit: the above solution is not working.

jdk-11.0.1/bin/javadoc -link 'https://github.com/grpc/grpc-java/tree/gh-pages/javadoc/' Test.java

The problem with https://grpc.io/grpc-java/javadoc/ is that the website grpc.io uses Jekyll which responses GET request to https://grpc.io/grpc-java/javadoc/package-list with Content-Type:"application/octet-stream" and a browser trying to download it.

[ST-DDT]

I can confirm that using the other link it does not throw an error anymore. However it does not generate links to the grpc classes either (including jdk 8). Is that page updated yet?

You can verify that behavior by changing the return type of the example config to an grpc-java class.

[dapengzhang0]

I can confirm that using the other link it does not throw an error anymore. However it does not generate links to the grpc classes either (including jdk 8).

Right, it links to the github pages which are not in javadoc format. My mistake.

Is that page updated yet?

I tested with a few changes and reverted them back. So it is unchanged.

[dapengzhang0]

@ST-DDT Using jdk 11.0.2, the issue is gone.

$ echo "/** See {@link io.grpc.Metadata}. */ public class Test {}" > Test.java
$ ~/Downloads/jdk-11.0.2/bin/javadoc -link 'https://grpc.io/grpc-java/javadoc/' Test.java -cp ~/.m2/repository/io/grpc/grpc-core/1.19.0/grpc-core-1.19.0.jar
Loading source file Test.java...
Constructing Javadoc information...
Standard Doclet version 11.0.2
Building tree for all the packages and classes...
Generating ./Test.html...
Generating ./package-summary.html...
Generating ./package-tree.html...
Generating ./constant-values.html...
Building index for all the packages and classes...
Generating ./overview-tree.html...
Generating ./index-all.html...
Building index for all classes...
Generating ./allclasses-index.html...
Generating ./allpackages-index.html...
Generating ./deprecated-list.html...
Building index for all classes...
Generating ./allclasses.html...
Generating ./allclasses.html...
Generating ./index.html...
Generating ./help-doc.html...