Impossible de créer un lien vers JDK10 dans les commentaires Javadoc

Après la mise à niveau de Java 9 vers 10, les liens vers le JDK ne fonctionnent plus lors de la génération de documentation avec l'outil Javadoc (par exemple, pour l'importation d'un fichier java.util.Optional, {@link Optional} rend as Optional au lieu de as Optional; même problème avec @see, @param, @return, et partout ailleurs, vous voyez normalement des liens Javadoc).

J'ai un projet modularisé simple, et j'utilise Maven avec le plugin Javadoc (source et target options définies sur 10 dans la section configuration pour le compilateur plugin). Ma compréhension est que par défaut il passe -link https://docs.oracle.com/javase/10/docs/api/ à l'outil Javadoc. Je crois aussi comprendre que, historiquement, l'outil Javadoc s'attendait à ce qu'un fichier texte nommé package-list soit présent à l'URL où il a été dit de trouver des documents externes. Java 8 a un. Java 9 a un. Java 10 ne fait pas (erreur 404). Apparemment, l'outil Javadoc génère maintenant un fichier texte nommé element-list au lieu de package-list pour les projets modularisés, mais il semble que ne l'est pas fourni soit (ni pour Java 9, mais il est disponible pour les versions en accès anticipé de Java 11).

Générer Javadoc via IntelliJ avec l'option Link to JDK documentation activée produit le même résultat. Il dit qu'il passe -link https://docs.oracle.com/javase/10/docs/api/ à javadoc.exe, et il signale javadoc: error - Error fetching URL: https://docs.oracle.com/javase/10/docs/api/. Malgré l'erreur, il affiche le Javadoc, mais comme avec Maven, aucun lien JDK n'est présent.

Comment est-ce censé fonctionner? Oracle a-t-il foiré quand ils ont mis les documents JDK en ligne?

Le morceaux pertinents de mon 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>

Sortie de 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

Il y a deux parties.

  1. Dans JDK 10, le format et le nom du fichier ont changé, pour mieux prendre en charge les modules. Le nouveau nom est "element-list" et le changement de format permet à l'outil javadoc de savoir quels modules sont présents dans une API ainsi que quels packages.

  2. La copie de l'API affichée à https://docs.oracle.com/javase/10/docs/api/overview-summary.html semble bloquer le fichier "element-list", donnant un 404. Qui doit être étudié et fixé.

Notez que vous devrez utiliser une version JDK 10 de javadoc pour pointer vers l'API JDK 10. La dernière version de l'outil comprend à la fois element-list (pour les documents sur les modules) et package-list (pour les documents sur les paquets (c'est-à-dire pas de modules)).

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

Ma solution de contournement pour le moment est de pointer {[4] } vers un package-list local en utilisant le offlineLinks option du plugin Maven Javadoc (qui correspond à la linkoffline option de l'outil Javadoc). J'ai ajouté ce qui suit à la section configuration pour le plugin: 

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

Et j'ai ajouté <maven.compiler.release>10</maven.compiler.release> à la section properties de mon pom.xml afin que je puisse utiliser ${maven.compiler.release} dans la valeur du url. (Cela rend les options du compilateur source et target redondantes, mais IntelliJ ne semble pas comprendre release lors de l'importation de projets Maven, je les ai donc conservés.)

J'ai créé un fichier texte nommé package-list (pas d'extension de fichier) et l'ai mis dans le répertoire racine du projet (d'où ${project.basedir} pour le location, c'est là qu'il recherchera package-list). Ce fichier ressemble à ceci:

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

Il n'a besoin que des paquets que vous essayez de lier. J'ai également essayé de nommer le fichier {[21] } et de suivre le format que javadoc.exe utilise pour les projets modularisés, comme ceci: 

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

Mais ça n'a pas marché (Javadoc généré avec succès, mais pas de liens JDK, comme précédemment). Il s'est plaint de ne pas pouvoir trouver package-list.

Donc, encore une fois, les bits pertinents du 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 ici.

Des bits appropriés ont déjà été ajoutés au plugin Maven Javadoc dans master, mais cela n'aidera pas en raison d'un bogue dans javadoc(1) dans Java 11. Voir MJAVADOC-561 pour plus de détails. Les liens brisés ne peuvent être corrigés que par Oracle.

Edit: Le correctif est prévu pour Java 11.0.2 par Oracle.

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