无法在 Javadoc 注释中链接到 JDK10

java maven javadoc java-10 maven-javadoc-plugin

2022-09-02 01:27:44

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

我有一个简单的模块化项目，我正在将Maven与Javadoc插件一起使用（以及编译器插件部分中设置的选项）。我的理解是，默认情况下，它会传递到Javadoc工具。我的理解是，从历史上看，Javadoc工具期望一个名为的文本文件出现在URL中，在那里它被告知要查找外部文档。Java 8有一个。Java 9有一个。Java 10 没有（404 错误）。显然，Javadoc工具现在输出一个名为而不是模块化项目的文本文件，但似乎也没有提供（Java 9也没有提供，但它可用于Java 11的早期访问版本）。sourcetarget10configuration-link https://docs.oracle.com/javase/10/docs/api/package-listelement-listpackage-list

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

这应该如何工作？甲骨文在将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"

答案 1

这有两个部分。

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

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

答案 2

目前，我的解决方法是使用Maven Javadoc插件的offlineLinks选项指向本地（对应于Javadoc工具的linkoffline选项）。我在插件的部分添加了以下内容：javadoc.exepackage-listconfiguration

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

我添加到我的部分，以便我可以在值中使用.（这使得和编译器选项变得多余，但 IntelliJ 在导入 Maven 项目时似乎不理解，所以我保留了它们。<maven.compiler.release>10</maven.compiler.release>propertiespom.xml${maven.compiler.release}urlsourcetargetrelease

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

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

它只需要您尝试链接到的包。我还尝试命名文件并遵循用于模块化项目的格式，如下所示：element-listjavadoc.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>