无法在Javadoc注释中链接到JDK10 [英] Can't link to JDK10 in Javadoc comments

问题描述

从Java 9升级到10后，使用Javadoc工具生成文档时，到JDK的链接不再起作用(例如，对于导入java.util.Optional的文件，{@link Optional}呈现为Optional而不是 Optional ；与@see，@param，@return以及通常可以看到Javadoc链接的其他任何地方).

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

我有一个简单的模块化项目，并且将Maven与Javadoc插件一起使用(在configuration部分的10和target选项设置为编译器插件).我的理解是，默认情况下，它将-link https://docs.oracle.com/javase/10/docs/api/传递给Javadoc工具.根据我的理解，从历史上看，Javadoc工具希望在URL处存在一个名为package-list的文本文件，该文件被告知查找外部文档. Java 8 有一个. Java 9 有一个. Java 10 没有(404错误).显然，Javadoc工具现在为模块化项目输出一个名为element-list而不是package-list的文本文件，但是 Java 9 ，但可用于

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

在启用了选项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链接.

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.

这应该如何工作?当Oracle将JDK文档放在网上时，Oracle搞砸了吗?

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

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

推荐答案

这有两部分.

1. 在JDK 10中，文件的格式和名称已更改，以更好地支持模块.新名称为"element-list"，格式的更改使javadoc工具可以知道API中存在哪些模块以及哪些软件包.

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.

发布在上的API的副本https://docs.oracle.com/javase/10/docs/api/overview-summary.html 似乎正在阻止元素列表"文件，并提供了404.需要对此进行调查并解决.

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.

请注意，您将需要使用Javadoc的JDK 10版本来指向JDK 10 API.该工具的最新版本可以理解element-list(对于有关模块的文档)和package-list(对于有关软件包的文档(即，无模块)).

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

这篇关于无法在Javadoc注释中链接到JDK10的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！