logo标签列表

无法在Javadoc注释中链接到JDK10

javamavenjavadocmaven-javadoc-pluginjava-10
22
升级到Java 10后，使用Javadoc工具生成文档时（例如，对于导入java.util.Optional的文件，{@link Optional}显示为Optional而不是Optional；在@see、@param、@return和任何其他通常看到Javadoc链接的地方也存在相同的问题），从Java 9升级到10后，与JDK的链接不再起作用。
我有一个简单的模块化项目，我正在使用带有Javadoc插件的Maven（在编译器插件的configuration部分中将source和target选项设置为10）。据我了解，它默认会将-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的文本文件，但似乎element-list也没有提供（对于Java 9也是如此，但它可用于Java 11的早期访问版本中）。
启用IntelliJ选项Link to JDK documentation生成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链接。
这应该如何工作？当他们将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"
@JacobG。文档本身存在且正常工作。问题出现在尝试使用Javadoc标签链接到它们时。 - gdejohn
6
Java 10在三天前发布时，文档从download.java.net转移到了docs.oracle.com。 - gdejohn
1
@nullpointer mvn clean test javadoc:javadoc（我有一些JUnit 5测试，并且我正在使用Maven Surefire插件的2.19.1版本）。没有异常，构建成功。对我来说，mvn clean package也很好用。我已经将mvn -version的输出添加到问题底部。 - gdejohn
1
@gdejohn 可能我遇到了另一个连续的错误场景，这个问题在3.0.1中已经修复。但是我同意，与Java-9相比，文档链接的生成似乎有问题。同时也同意之前链接的问题即使使用最新的3.0.1-SNAPSHOT版本的maven-javadoc-plugin进行测试，也不包含10的package-list。我的一些直觉一直在提醒我并指向删除旧标准doclet可能会影响插件。 - Naman
2
我猜也是因为...我的理解是默认情况下它会将-link https://docs.oracle.com/javase/10/docs/api传递给Javadoc工具。我也了解到，在过去，Javadoc工具期望在告诉它查找外部文档的URL上存在一个名为package-list的文本文件。请注意Java10中的更改，如果javadoc无法访问-link的URL内容，则应该报错。 - Naman
显示剩余2条评论
3个回答
12

这里有两个部分。

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

  2. 发布在https://docs.oracle.com/javase/10/docs/api/overview-summary.html 的 API 副本似乎阻止了 “element-list” 文件，产生了 404 错误。需要进行调查和修复。

请注意，您需要使用 JDK 10 版本的 javadoc 来指向 JDK 10 API。最新版本的工具同时理解 element-list（用于关于模块的文档）和 package-list（用于关于包的文档（即无模块））。

我能够通过Maven Javadoc插件使用-linkoffline选项和本地package-file解决问题，但是当我尝试使用element-list时，它没有起作用（请参见我的答案）。有什么想法吗？ mvn -version显示正在使用Java 10。 - gdejohn
3
我们正在调查404错误。 - Jonathan Gibbons
1
我也很好奇为什么Java 9没有element-list（404错误），但有一个[package-list](https://docs.oracle.com/javase/9/docs/api/package-list）。 - gdejohn
1
导致.../element-list返回404的问题已经解决。 - Jonathan Gibbons
现在element-list可用，Oracle的问题已经解决。但是Maven仍然存在一些问题。Javadoc插件配置选项detectJavaApiLink（默认启用）应该为您找出JDK Javadoc URL，但是如果我不使用插件选项links显式提供URL，则生成的Javadoc中只会得到JDK链接。 - gdejohn
10

目前我的解决方法是使用 Maven Javadoc 插件的 offlineLinks 选项（对应于 Javadoc 工具的 linkoffline 选项），将 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>
2
我建议同时将此问题提交到maven问题跟踪器，以便他们可以：要么将其进一步提升到JDK并了解为什么Java10中缺少package-list，要么提供替代解决方案，如果这是计划从JDK发布中更改的话。 - Naman
6

我是一名Maven的贡献者。

适当的代码已经添加到了Maven Javadoc插件中，但由于Java 11中javadoc(1)存在一个bug，这并没有帮助。有关详细信息，请参见MJAVADOC-561。只有Oracle才能修复这些错误链接。

编辑：Oracle计划在Java 11.0.2中修复此问题。

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接