Question

从Java 9升级到10后，使用Javadoc工具生成文档时，指向JDK的链接不再有效（例如，对于文件导入java.util.Optional，{@link Optional}呈现为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中。 Java 8 has one。 Java 9 has one。 Java 10 does not（404错误）。显然，Javadoc工具现在为模块化项目输出一个名为element-list而不是package-list的文本文件，但它似乎也是isn't provided（也不是Java 9，但它是可用于Java 11）的早期访问版本。

通过IntelliJ生成Javadoc并启用选项Link to JDK documentation会产生相同的结果。它表示已将-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链接。

这应该如何运作？当他们将JDK文档放到网上时，Oracle是否搞砸了？

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

这有两个部分。

在JDK 10中，文件的格式和名称已更改，以便更好地支持模块。新名称是“element-list”，格式的更改允许javadoc工具知道API中存在哪些模块以及哪些包。
在https://docs.oracle.com/javase/10/docs/api/overview-summary.html发布的API副本似乎阻止了“元素列表”文件，给出了404.需要对其进行调查和修复。

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

Answer 2

我目前的解决方法是使用Maven Javadoc插件的offlineLinks选项将javadoc.exe指向本地package-list（对应于linkoffline选项Javadoc工具）。我将以下内容添加到插件的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>添加到properties的{{1}}部分，以便我可以在pom.xml的值中使用${maven.compiler.release}。（这会使url和source编译器选项变得多余，但IntelliJ在导入Maven项目时似乎不理解target，所以我保留了它们。）

我创建了一个名为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

但这不起作用（Javadoc成功生成，但没有像以前那样的JDK链接）。它抱怨找不到module:java.base java.lang java.util java.util.concurrent java.util.function java.util.stream。

所以，再一次，package-list的相关位：

pom.xml

Answer 3

...这里是Maven提交者。

已经在master的Maven Javadoc插件中添加了适当的位，但是由于Java 11中的javadoc(1)中的错误而无济于事。有关详细信息，请参见MJAVADOC-561。断开的链接只能由Oracle修复。

编辑：该修复程序已由Oracle计划用于Java 11.0.2。

无法在Javadoc评论

3 个答案: