Cannot link to javadoc from jdk11's javadoc tool about grpc.github.io

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