Can't link to JDK10 in Javadoc comments

问题:

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"

回答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)).

回答2:

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>

回答3:

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