无法在Javadoc注释中链接到JDK10

Question

从Java 9升级到10后,链接到JDK不再工作时的Javadoc工具生成的文件(例如,对于文件导入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 有一个.Java 9 有一个.Java 10 没有(404错误).显然,Javadoc工具现在输出一个名为element-list而不是package-list模块化项目的文本文件,但似乎也没有提供(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

这有两个部分.

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

2. 在https://docs.oracle.com/javase/10/docs/api/overview-summary.html上发布的API副本似乎阻止了"元素列表"文件,给出了404.这需要被调查和修复.

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

Answer 2

我目前的解决方法是使用Maven Javadoc插件的选项指向javadoc.exe本地(它对应于Javadoc工具的选项).我在插件部分添加了以下内容:package-listofflineLinkslinkofflineconfiguration

<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部分,pom.xml以便我可以使用${maven.compiler.release}的值url.(这使得source和target编译器选项变得多余,但IntelliJ release在导入Maven项目时似乎并不理解,所以我保留了它们.)

我创建了一个名为的文本文件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 3

...... Maven提交者在这里.

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

编辑:修复程序由Oracle安排在Java 11.0.2中.