Невозможно связаться с JDK10 в комментариях Javadoc

После обновления с 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 вместо element-list package-list для модульных проектов, но, похоже, он не предоставляется ни (или для Java 9, но доступен для ранних версий сборки Java 11).

Сгенерирование Javadoc через IntelliJ с возможностью включения 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 отсутствуют.

Как это должно работать? Завершил ли Oracle, когда они размещают документы 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

Для этого есть две части.

  1. В JDK 10 формат и имя файла изменились, чтобы лучше поддерживать модули. Новое имя - "список элементов", а изменение формата позволяет инструменту javadoc знать, какие модули присутствуют в API, а также какие пакеты.

  2. Копия API, опубликованная на https://docs.oracle.com/javase/10/docs/api/overview-summary.html, кажется, блокирует файл "список элементов", давая 404. Это необходимо для изучения и исправления.

Обратите внимание, что вам нужно будет использовать версию javadoc JDK 10 для указания API JDK 10. Последняя версия инструмента понимает как список элементов (для документов о модулях), так и список пакетов (для документов о пакетах (то есть без модулей)).

Ответ 2

Моим обходным javadoc.exe на данный момент является точка javadoc.exe в локальном package-list с использованием опции offlineLinks плагина Maven Javadoc (что соответствует опции 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 моего pom.xml чтобы использовать значение ${maven.compiler.release} в значении для url ${maven.compiler.release}. (Это делает параметры 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>