在 Javadoc 注释中不能 link 到 JDK10

Question

从 Java 9 升级到 10 后，使用 Javadoc 工具生成文档时指向 JDK 的链接不再有效（例如，对于导入 java.util.Optional、{@link Optional} 呈现为 Optional 而不是 Optional；与 @see、@param、@return 以及您通常使用的其他任何地方的问题相同请参阅 Java 文档链接）。

我有一个简单的模块化项目，我使用带有 Javadoc 插件的 Maven（source 和 target 选项设置为 10 configuration 编译器插件部分）。我的理解是，默认情况下它会将 -link https://docs.oracle.com/javase/10/docs/api/ 传递给 Javadoc 工具。这也是我的理解，从历史上看，Javadoc 工具期望一个名为 package-list 的文本文件出现在被告知要查找外部文档的 URL 处。 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).

通过启用 Link to JDK documentation 选项的 IntelliJ 生成 Javadoc 会产生相同的结果。它说它正在将 -link https://docs.oracle.com/javase/10/docs/api/ 传递给 javadoc.exe，并报告 javadoc: error - Error fetching URL: https://docs.oracle.com/javase/10/docs/api/。尽管有错误，它确实输出 Javadoc，但与 Maven 一样，不存在 JDK 链接。

这应该如何运作？ Oracle 在将 JDK 文档放到网上时搞砸了吗？

我的相关位 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>

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

我目前的解决方法是使用 Javadoc 工具的 offlineLinks option of the Maven Javadoc plugin (which corresponds to the linkoffline 选项将 javadoc.exe 指向本地 package-list。我将以下内容添加到插件的 configuration 部分：

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

并且我将 <maven.compiler.release>10</maven.compiler.release> 添加到 pom.xml 的 properties 部分，这样我就可以在 url 的值中使用 ${maven.compiler.release}。（这使得 source 和 target 编译器选项变得多余，但是 IntelliJ 在导入 Maven 项目时似乎不理解 release，所以我保留了它们。）

我创建了一个名为 package-list 的文本文件（无文件扩展名），并将其放在项目的根目录中（因此 ${project.basedir} 代表 location，这就是它所在的位置将查找 package-list)。该文件如下所示：

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

它只需要您尝试 link 的包。我还尝试将文件命名为 element-list 并遵循 javadoc.exe 用于模块化项目的格式，如下所示：

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

但这没有用（Javadoc 成功生成，但没有 JDK links，和以前一样）。它抱怨找不到 package-list.

所以，再一次，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>

Answer 2

这有两个部分。

在JDK10 中，文件的格式和名称发生了变化，以更好地支持模块。新名称是 "element-list" 并且格式的更改允许 javadoc 工具知道 API 中存在哪些模块以及哪些包。
在 https://docs.oracle.com/javase/10/docs/api/overview-summary.html 发布的 API 的副本似乎阻止了 "element-list" 文件，给出了 404。这需要调查和固定。

请注意，您需要使用 JDK 10 版本的 javadoc 来指向 JDK 10 API。该工具的最新版本可以理解 element-list（关于模块的文档）和 package-list（关于包的文档（即没有模块））。

Answer 3

...这里是 Maven 提交者。

已经在 master 中的 Maven Javadoc 插件中添加了适当的位，但是由于 Java 11 中 javadoc(1) 中的错误，这无济于事。参见 MJAVADOC-561 了解详情。损坏的链接只能由 Oracle 修复。

编辑：Oracle 计划在 Java 11.0.2 中进行修复。

在 Javadoc 注释中不能 link 到 JDK10

Can't link to JDK10 in Javadoc comments

java

javadoc

maven

maven-javadoc-plugin

java-10