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" 

Answer 1

There are two parts to this.

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

2. 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)).