Impossibile collegarsi a JDK10 nei commenti Javadoc

Dopo l'aggiornamento da Java 9 a 10, i collegamenti a JDK non funzionano più durante la generazione di documentazione con lo strumento Javadoc (ad esempio, per l'importazione di un filejava.util.Optional, {@link Optional} rende come Optional invece di come Optional; stesso problema con @see, @param, @return, e in qualsiasi altro luogo normalmente vedi i collegamenti Javadoc).

Ho un semplice progetto modularizzato e sto usando Maven con il plugin Javadoc (source e target opzioni impostate su 10 nella sezione configuration per il compilatore plugin). La mia comprensione è che per impostazione predefinita passa -link https://docs.oracle.com/javase/10/docs/api/ allo strumento Javadoc. Ho anche capito che, storicamente, lo strumento Javadoc si aspettava che un file di testo chiamato package-list fosse presente all'URL in cui è stato detto di trovare documenti esterni. Java 8 ha uno. Java 9 ha uno. Java 10 non (errore 404). Apparentemente, lo strumento Javadoc ora emette un file di testo chiamato element-list invece di package-list per progetti modularizzati, ma sembra che non lo sia fornito o (né per Java 9, ma è disponibile per le build di accesso anticipato di Java 11).

La generazione di Javadoc tramite IntelliJ con l'opzione Link to JDK documentation abilitata produce lo stesso risultato. Dice che sta passando -link https://docs.oracle.com/javase/10/docs/api/ a javadoc.exe e riporta javadoc: error - Error fetching URL: https://docs.oracle.com/javase/10/docs/api/. Nonostante l'errore, emette il Javadoc, ma come con Maven, non sono presenti collegamenti JDK.

Come dovrebbe funzionare? Oracle ha sbagliato quando hanno messo online i documenti JDK?

Il bit rilevanti del mio 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>

Uscita di 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"
Author: gdejohn, 2018-03-23
Source

3 answers

Ci sono due parti in questo.

  1. In JDK 10, il formato e il nome del file sono cambiati, per migliorare i moduli di supporto. Il nuovo nome è "element-list" e la modifica del formato consente allo strumento javadoc di sapere quali moduli sono presenti in un'API e quali pacchetti.

  2. La copia dell'API pubblicata su https://docs.oracle.com/javase/10/docs/api/overview-summary.html sembra bloccare il file "element-list", dando un 404. Questo deve essere indagato e fissato.

Si noti che è necessario utilizzare una versione JDK 10 di javadoc per puntare all'API JDK 10. L'ultima versione dello strumento comprende sia element-list (per documenti sui moduli) che package-list (per documenti sui pacchetti (cioè nessun modulo)).

 12
Author: Jonathan Gibbons, 2018-03-26 18:25:47

La mia soluzione per il momento è puntare javadoc.exe su un package-list locale usando il offlineLinks opzione del plugin Maven Javadoc (che corrisponde al linkoffline opzione dello strumento Javadoc). Ho aggiunto quanto segue alla sezione configuration per il plugin: 

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

E ho aggiunto <maven.compiler.release>10</maven.compiler.release> alla sezione properties del mio pom.xml in modo da poter usare ${maven.compiler.release} nel valore per url. (Ciò rende le opzioni del compilatore source e target ridondanti, ma IntelliJ non sembra capire release durante l'importazione di progetti Maven, quindi li ho tenuti.)

Ho creato un file di testo chiamato package-list (senza estensione di file) e lo ho inserito nella directory principale del progetto (quindi ${project.basedir} per location, che è dove cercherà package-list). Quel file assomiglia a questo: 

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

Ha bisogno solo dei pacchetti a cui stai cercando di collegarti. Ho anche provato a nominare il file element-list e seguendo il formato che javadoc.exe utilizza per progetti modularizzati, in questo modo: 

module:java.base
java.lang
java.util
java.util.concurrent
java.util.function
java.util.stream

Ma non ha funzionato (Javadoc generato con successo, ma nessun link JDK, come prima). Si lamentava che non riusciva a trovare package-list.

Quindi, ancora una volta, i bit rilevanti del 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>
 9
Author: gdejohn, 2018-03-27 01:17:23

...Maven committer qui.

Bit appropriati sono già stati aggiunti al plugin Maven Javadoc in master, ma ciò non aiuterà a causa di un bug in javadoc(1) in Java 11. Vedi MJAVADOC-561 per i dettagli. I collegamenti interrotti possono essere risolti solo da Oracle.

Modifica: la correzione è pianificata per Java 11.0.2 da Oracle.

 6
Author: Michael-O, 2019-01-07 13:13:41