java无法在Javadoc注释中链接到JDK10

Question

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

我有一个简单的模块化项目，我使用Maven和Javadoc插件（source和target选项设置为10，在编译器插件的configuration部分）。我的理解是，默认情况下，它将-link https://docs.oracle.com/javase/10/docs/api/传递给Javadoc工具。我的理解是，从历史上看，Javadoc工具希望一个名为package-list的文本文件出现在它被告知查找外部文档的URL上。爪哇8has one。爪哇9has one。Java 10does not（404错误）。显然，Javadoc工具现在为模块化项目输出一个名为element-list的文本文件，而不是package-list的文本文件，但它似乎是isn't provided（也不是Java 9，但它可用于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文档放到网上的时候搞砸了吗

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

目前我的解决方法是使用Maven Javadoc插件的^{}选项（对应于Javadoc工具的^{}选项）将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>

我在我的pom.xml的properties部分添加了<maven.compiler.release>10</maven.compiler.release>，这样我就可以在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

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

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

但这并没有起作用（Javadoc成功生成，但没有JDK链接，就像以前一样）。它抱怨说它找不到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

这有两个部分

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

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

注意，您需要使用JDK10版本的javadoc来指向JDK10API。该工具的最新版本既可以理解元素列表（对于关于模块的文档）也可以理解包列表（对于关于包的文档（即没有模块））

Answer 3

。。。这里是Maven committer

master中的Maven Javadoc插件已经添加了适当的位，但由于Java11中的javadoc(1)中有一个bug，这不会有帮助。详见MJAVADOC-561。断开的链接只能由Oracle修复

编辑：Oracle计划对Java 11.0.2进行修复