Skip to content
This repository has been archived by the owner on Apr 9, 2021. It is now read-only.

Cannot link to javadoc from jdk11's javadoc tool #801

Open
ST-DDT opened this issue Dec 28, 2018 · 12 comments
Open

Cannot link to javadoc from jdk11's javadoc tool #801

ST-DDT opened this issue Dec 28, 2018 · 12 comments

Comments

@ST-DDT
Copy link

ST-DDT commented Dec 28, 2018

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
Copy link

cc: @dapengzhang0

@dapengzhang0
Copy link
Member

dapengzhang0 commented Jan 3, 2019

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
Copy link
Member

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
Copy link
Author

ST-DDT commented Jan 3, 2019

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
Copy link
Member

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
Copy link
Author

ST-DDT commented Jan 4, 2019

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
Copy link
Member

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

@dapengzhang0
Copy link
Member

@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
Copy link
Member

dapengzhang0 commented Jan 7, 2019

@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
Copy link
Author

ST-DDT commented Jan 7, 2019

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
Copy link
Member

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
Copy link
Member

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants