Cannot link to javadoc from jdk11's javadoc tool

Question

Cannot link to javadoc from jdk11's javadoc tool

ST-DDT opened this issue 5 years ago · comments

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 · Answer 1 · Fri Jan 04 2019 00:21:24 GMT+0800 (China Standard Time)

cc: @dapengzhang0

ZHANG Dapeng · Answer 2 · Fri Jan 04 2019 02:18:01 GMT+0800 (China Standard Time)

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.

ZHANG Dapeng · Answer 3 · Fri Jan 04 2019 03:40:47 GMT+0800 (China Standard Time)

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 · Answer 4 · Fri Jan 04 2019 07:42:44 GMT+0800 (China Standard Time)

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.

ZHANG Dapeng · Answer 5 · Fri Jan 04 2019 08:22:33 GMT+0800 (China Standard Time)

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 · Answer 6 · Fri Jan 04 2019 20:47:48 GMT+0800 (China Standard Time)

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

ZHANG Dapeng · Answer 7 · Sat Jan 05 2019 01:02:34 GMT+0800 (China Standard Time)

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

ZHANG Dapeng · Answer 8 · Sat Jan 05 2019 02:47:26 GMT+0800 (China Standard Time)

@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

ZHANG Dapeng · Answer 9 · Tue Jan 08 2019 06:42:01 GMT+0800 (China Standard Time)

@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 · Answer 10 · Tue Jan 08 2019 06:53:12 GMT+0800 (China Standard Time)

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.

ZHANG Dapeng · Answer 11 · Tue Jan 08 2019 07:08:11 GMT+0800 (China Standard Time)

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.

ZHANG Dapeng · Answer 12 · Sat Apr 06 2019 01:44:16 GMT+0800 (China Standard Time)

@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...