Can't link to JDK10 in Javadoc comments

Question

After upgrading from Java 9 to 10, links to the JDK no longer work when generating documentation with the Javadoc tool (e.g., for a file importing java.util.Optional, {@link Optional} renders as Optional instead of as Optional; same issue with @see, @param, @return, and anywhere else you normally see Javadoc links).

I have a simple modularized project, and I'm using Maven with the Javadoc plugin (source and target options set to 10 in the configuration section for the compiler plugin). My understanding is that by default it passes -link https://docs.oracle.com/javase/10/docs/api/ to the Javadoc tool. It's also my understanding that, historically, the Javadoc tool expected a text file named package-list to be present at the URL where it was told to find external docs. Java 8 has one. Java 9 has one. Java 10 does not (404 error). Apparently, the Javadoc tool now outputs a text file named element-list instead of package-list for modularized projects, but it seems like that isn't provided either (nor for Java 9, but it is available for early-access builds of Java 11).

Generating Javadoc through IntelliJ with the option Link to JDK documentation enabled produces the same result. It says it's passing -link https://docs.oracle.com/javase/10/docs/api/ to javadoc.exe, and it reports javadoc: error - Error fetching URL: https://docs.oracle.com/javase/10/docs/api/. Despite the error, it does output the Javadoc, but as with Maven, no JDK links are present.

How is this supposed to work? Did Oracle screw up when they put the JDK docs online?

The relevant bits of my pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.7.0</version>
            <configuration>
                <source>10</source>
                <target>10</target>
            </configuration>
            <dependencies>
                <dependency>
                    <groupId>org.ow2.asm</groupId>
                    <artifactId>asm</artifactId>
                    <version>6.1</version> <!--update dependency for Java 10 compatibility-->
                </dependency>
            </dependencies>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Output of mvn -version:

Apache Maven 3.5.3 (3383c37e1f9e9b3bc3df5050c29c8aff9f295297; 2018-02-24T12:49:05-07:00)
Maven home: C:\Program Files\apache-maven-3.5.3\bin\..
Java version: 10, vendor: Oracle Corporation
Java home: C:\Program Files\Java\jdk-10
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"

@JacobG. The docs themselves are present and working fine. The problem occurs when trying to link to them using Javadoc tags. — gdejohn, Mar 23 '18 at 20:38
Where? The links on my question are dead at the moment. I did just find this link: https://docs.oracle.com/javase/10/docs/toc.htm — Jacob G., Mar 23 '18 at 20:38
When Java 10 was released three days ago, the docs moved from [download.java.net](https://download.java.net/java/jdk10/docs/api/) to [docs.oracle.com](https://docs.oracle.com/javase/10/docs/api/). — gdejohn, Mar 23 '18 at 20:40
1. What command did you execute to successfully generate those docs? 2. Did you not face an [NPE while executing the same](https://stackoverflow.com/questions/49460751/execution-attach-javadocs-of-goal-org-apache-maven-pluginsmaven-javadoc-plugin)? — Naman, Mar 24 '18 at 03:00
@nullpointer `mvn clean test javadoc:javadoc` (I have some JUnit 5 tests, and I'm using version 2.19.1 of the Maven Surefire plugin). No exceptions, build succeeds. `mvn clean package` also works fine for me. I've added the output of `mvn -version` to the bottom of the question. — gdejohn, Mar 24 '18 at 04:00
@gdejohn Possibly I met another consequent error scenario which is fixed for 3.0.1. But I agree, the generation of the doc links seems broken as compared to Java-9. Also agreeing to the point that even the latest `3.0.1-SNAPSHOT` for maven-javadoc-plugin I used to test the previously linked question doesn't consist of the `package-list` for 10 either. Some instinct of mine just keep pitching in and points me to the direction of [Removal of the old standard doclet](http://www.oracle.com/technetwork/java/javase/10-relnote-issues-4108729.html#JDK-8177511) which could be impacting the plugin. — Naman, Mar 24 '18 at 14:53
I guess also to the fact that... *My understanding is that by default it passes -link https://docs.oracle.com/javase/10/docs/api to the Javadoc tool.It's also my understanding that in the past, the Javadoc tool expected a text file named package-list to be present at the URL where it was told to find external docs* .... Please note a change in Java10, [It should be an error if javadoc cannot access the contents of aURL for -link.](https://bugs.java.com/view_bug.do?bug_id=JDK-8180019) — Naman, Mar 24 '18 at 14:58

score 12 · Accepted Answer · answered Mar 26 '18 at 18:25

12

There are two parts to this.

In JDK 10, the format and name of the file have changed, to better support modules. The new name is "element-list" and the change in format allows the javadoc tool to know what modules are present in an API as well as what packages.
The copy of the API that is posted at https://docs.oracle.com/javase/10/docs/api/overview-summary.html seems to be blocking the "element-list" file, giving a 404. That needs to be investigated and fixed.

Note that you will need to use a JDK 10 version of javadoc to point to the JDK 10 API. The latest version of the tool understands both element-list (for docs about modules) and package-list (for docs about packages (i.e. no modules)).

answered Mar 26 '18 at 18:25

Jonathan Gibbons

676
3
5

I was able to work around the problem with a local `package-file` using the `-linkoffline` option for `javadoc.exe` via the Maven Javadoc plugin, but when I tried with an `element-list`, it didn't work (see [my answer](https://stackoverflow.com/a/49482502/464306)). Any idea why that is? `mvn -version` says it's using Java 10. – gdejohn Mar 26 '18 at 18:36
2

We are investigating the 404. – Jonathan Gibbons Mar 26 '18 at 18:50
1

I'm also curious why there's no [`element-list`](https://docs.oracle.com/javase/9/docs/api/element-list) for Java 9 (404 error), but there is a [`package-list`](https://docs.oracle.com/javase/9/docs/api/package-list). – gdejohn Mar 26 '18 at 18:51
1

The problem that was causing .../element-list to give 404 has been fixed. – Jonathan Gibbons Mar 29 '18 at 18:50
Now that `element-list` is available, the problem is fixed from Oracle's end. But there's still something going wrong with Maven. The Javadoc plugin configuration option [`detectJavaApiLink`](https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#detectJavaApiLink) (enabled by default) is supposed to figure out the JDK Javadoc URL for you, but I only get JDK links in the generated Javadoc if I explicitly provide the URL with the plugin option [`links`](https://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#links). – gdejohn Mar 29 '18 at 19:59

gdejohn · Answer 2 · 2018-03-27T01:17:23.203

My workaround for the moment is to point javadoc.exe at a local package-list using the offlineLinks option of the Maven Javadoc plugin (which corresponds to the linkoffline option of the Javadoc tool). I added the following to the configuration section for the plugin:

<detectJavaApiLink>false</detectJavaApiLink>
<offlineLinks>
    <offlineLink>
        <url>https://docs.oracle.com/javase/${maven.compiler.release}/docs/api/</url>
        <location>${project.basedir}</location>
    </offlineLink>
</offlineLinks>

And I added <maven.compiler.release>10</maven.compiler.release> to the properties section of my pom.xml so that I could use ${maven.compiler.release} in the value for the url. (That makes the source and target compiler options redundant, but IntelliJ doesn't seem to understand release when importing Maven projects, so I kept them.)

I created a text file named package-list (no file extension) and put it in the root directory of the project (hence ${project.basedir} for the location, which is where it will look for package-list). That file looks like this:

java.lang
java.util
java.util.concurrent
java.util.function
java.util.stream

It only needs the packages that you're trying to link to. I also tried naming the file element-list and following the format that javadoc.exe uses for modularized projects, like so:

module:java.base
java.lang
java.util
java.util.concurrent
java.util.function
java.util.stream

But that didn't work (Javadoc successfully generated, but no JDK links, as before). It complained that it couldn't find package-list.

So, once again, the relevant bits of the pom.xml:

<properties>
    <maven.compiler.release>10</maven.compiler.release> <!--release makes source and target-->
    <maven.compiler.source>10</maven.compiler.source> <!--redundant, but IntelliJ doesn't-->
    <maven.compiler.target>10</maven.compiler.target> <!--use release when importing-->
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.7.0</version>
            <dependencies>
                <dependency>
                    <groupId>org.ow2.asm</groupId>
                    <artifactId>asm</artifactId>
                    <version>6.1</version> <!--update dependency for Java 10 compatibility-->
                </dependency>
            </dependencies>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <detectJavaApiLink>false</detectJavaApiLink>
                <offlineLinks>
                    <offlineLink>
                        <url>https://docs.oracle.com/javase/${maven.compiler.release}/docs/api/</url>
                        <location>${project.basedir}</location>
                    </offlineLink>
                </offlineLinks>
            </configuration>
            <executions>
                <execution>
                    <id>attach-javadocs</id>
                    <goals>
                        <goal>jar</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
</build>

I would also suggest at the same time to raise it to [maven issue tracker](https://issues.apache.org/jira/projects/MJAVADOC) so that they can either - further raise it to JDK and get to know why package-list is missing from Java10 or - provide an alternate solution if this was planned to be changing from JDK release. — Naman, Mar 26 '18 at 03:42

Michael-O · Answer 3 · 2019-01-07T13:13:41.480

6

...Maven committer here.

Appropriate bits have been added to Maven Javadoc Plugin in master already, but that won't help due to a bug in javadoc(1) in Java 11. See MJAVADOC-561 for details. The broken links can only be fixed by Oracle.

Edit: The fix is scheduled for Java 11.0.2 by Oracle.

edited Jan 07 '19 at 13:13

answered Jan 03 '19 at 14:55

Michael-O

17,130
6
51
108

Can't link to JDK10 in Javadoc comments

3 Answers3

Linked