无法在Javadoc注释中链接到JDK10

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

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

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

我有一个简单的模块化项目，我正在使用Maven和Javadoc插件（在编译器插件的配置部分中将源和目标选项设置为10）。我的理解是默认情况下它将-link https://docs.oracle.com/javase/10/docs/api/传递给Javadoc工具。这也是我的理解，从历史上看，Javadoc工具期望一个名为package-list的文本文件出现在它被告知要查找外部文档的URL中。 Java 8有一个。 Java 9有一个。 Java 10没有（404错误）。显然，Javadoc工具现在为模块化项目输出一个名为element-list而不是package-list的文本文件，但似乎也没有提供（Java9也没有提供，但它可用于早期访问的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.

通过IntelliJ生成Javadoc，并启用了启用JDK文档的选项，可以产生相同的结果。它说传递链接https://docs.oracle.com/javase/10/docs/api/到javadoc.exe，它报告javadoc：错误 - 获取URL时出错：https：//docs.oracle.com/ JavaSE的/ 10 /文档/ API /。尽管有错误，它确实输出了Javadoc，但与Maven一样，没有JDK链接。

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

这应该怎么样？当他们将JDK文档放到网上时，Oracle是否搞砸了？

The relevant bits of my pom.xml:

我的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:

输出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"

2 个解决方案

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

   在JDK 10中，文件的格式和名称已更改，以更好地支持模块。新名称是“element-list”，格式的更改允许javadoc工具知道API中存在哪些模块以及哪些包。

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.

   在https://docs.oracle.com/javase/10/docs/api/overview-summary.html上发布的API副本似乎阻止了“元素列表”文件，给出了404.这需要被调查和修复。

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

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

#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:

我目前的解决方法是使用Maven Javadoc插件的offlineLinks选项（与Javadoc工具的linkoffline选项相对应）将javadoc.exe指向本地程序包列表。我在插件的配置部分添加了以下内容：

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

我将 10 添加到我的pom.xml的属性部分，以便我可以在url的值中使用$ {maven.compiler.release}。 （这使得源和目标编译器选项变得多余，但IntelliJ在导入Maven项目时似乎不理解发布，所以我保留了它们。）

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:

我创建了一个名为package-list（没有文件扩展名）的文本文件，并将其放在项目的根目录中（因此$ {project.basedir}为该位置，它将查找package-list）。那个文件看起来像这样：

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:

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

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.

但这不起作用（Javadoc成功生成，但没有像以前那样的JDK链接）。它抱怨它无法找到包裹清单。

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

那么，再一次，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>