Add JDK links to Javadoc

[Marcono1234]

Describe the problem you'd like to have solved

Currently the javadoc has no links to JDK classes, e.g. java.lang.Object. This makes browsing it slightly inconvenient.

Describe the ideal solution

This could be solved by specifying the JDK link the Gradle build file:

javadoc {
    options.links 'https://docs.oracle.com/javase/8/docs/api/'
}

Alternatives and current work-arounds

Alternatively, or additionally you could also specify a JDK toolchain only for the javadoc task which takes advantages of the lastest JDK javadoc features (such as a search bar), without having to change the lowest Java version this projects supports.

I have implemented an experimental implementation for this here (this also partially addresses #487), feel free to try it out:

1. Build with gradlew javadoc
2. Open lib/build/docs/javadoc/index.html in your browser

I don't have much experience with Gradle, so I am not sure if this is properly implemented. However, let me know if I should create a pull request for the branch.

[lbalmaceda]

This is a good addition. Although, I'd like us to include it in our OSS release plugin instead, in a generic way. Probably using the JDK toolchain. I see in the code you are passing the minimum java version for this project, I'd assume that the value would be available exposed as property through the java gradle plugin, for example. Let me share this internally for more visibility.

[lbalmaceda]

Would you like to send a PR with those changes you linked? The snippet below would need to go into the build.gradle file. We also tested that if the -release option is not passed later the default language version is taken from this toolchain block, which is acceptable to us. We'll wait for your reply. Thanks!

// Use latest JDK for javadoc generation
tasks.withType(Javadoc).configureEach {
    javadocTool = javaToolchains.javadocToolFor {
        languageVersion = JavaLanguageVersion.of(16)
    }
}

javadoc {
    // Exclude internal implementation package from javadoc
    excludes = ['com/auth0/jwt/impl']
    // Specify Java version this project uses
    options.addStringOption('-release', '8')
}

[Marcono1234]

The snippet below would need to go into the build.gradle file.

Do you mean the root build.gradle file? I would prefer to place it in the lib/build.gradle file (where the branch I linked also added it) since the release version specified there should be the same as the one used for compiling.

We also tested that if the -release option is not passed later the default language version is taken from this toolchain block, which is acceptable to us.

In most cases this probably does not make a difference. However, there can be cases where javac for JDK 8 succeeds but javadoc for JDK 16 fails, e.g. when calling a type (even if not publicly visible) _ or var. Therefore it would be best if the -release version always matched the one used to compile the code.