web-dev-qa-db-fra.com

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 un fichier important Java.util.Optional, {@link Optional} S'affiche comme Optional au lieu de --- Optional ; même problème avec @see, @param, @return, et partout ailleurs, normalement voir liens Javadoc).

J'ai un projet modulaire simple et j'utilise Maven avec le plug-in Javadoc (les options source et target sont définies sur 10 Dans la section configuration pour le plugin du compilateur). Ma compréhension est que par défaut, il passe -link https://docs.Oracle.com/javase/10/docs/api/ À l'outil Javadoc. Je comprends également que, historiquement, l'outil Javadoc s'attendait à ce qu'un fichier texte nommé package-list Soit présent à l'URL où il a été demandé de trouver des documents externes. Java 8 en a un . Java 9 en a un . Java 10 ne fonctionne pas (erreur 404). Apparemment, l'outil Javadoc génère désormais un fichier texte nommé element-list Au lieu de package-list Pour les projets modulaires, mais il semble que n'est pas fourni non plus (ni pour - Java 9 , mais il est disponible pour les versions à accès anticipé de Java 11 ).

La génération de Javadoc via IntelliJ avec l'option Link to JDK documentation Activée produit le même résultat. Il indique 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 génère le Javadoc, mais comme avec Maven, aucun lien JDK n'est présent.

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

Les bits 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"
javamavenjavadocmaven-javadoc-pluginjava-10
22
gdejohn

Il y a deux parties à cela.

  1. Dans JDK 10, le format et le nom du fichier ont changé pour mieux prendre en charge les modules. Le nouveau nom est "liste d'éléments" 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 qui est publiée sur https://docs.Oracle.com/javase/10/docs/api/overview-summary.html semble bloquer le fichier "liste d'éléments" , donnant un 404. Cela doit être étudié et corrigé.

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 la liste d'éléments (pour les documents sur les modules) et la liste de packages (pour les documents sur les packages (c'est-à-dire aucun module)).

13
Jonathan Gibbons

Ma solution de contournement pour le moment est de pointer javadoc.exe dans un local package-list en utilisant l'option offlineLinks du plugin Maven Javadoc (qui correspond à l'option linkoffline de l'outil Javadoc). J'ai ajouté ce qui suit à la section configuration du 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 pour pouvoir utiliser ${maven.compiler.release} dans la valeur de 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, donc je les ai conservées.)

J'ai créé un fichier texte nommé package-list (sans extension de fichier) et placez-le dans le répertoire racine du projet (d'où ${project.basedir} pour le location, où 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 packages auxquels vous essayez de lier. J'ai également essayé de nommer le fichier element-list et suivant le format que javadoc.exe utilisations pour des projets modulaires, comme ceci:

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

Mais cela n'a pas fonctionné (Javadoc a été généré avec succès, mais aucun lien JDK, comme précédemment). Il s'est plaint de ne pas avoir pu 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
gdejohn

... Maven committer ici.

Des bits appropriés ont déjà été ajoutés au plug-in Maven Javadoc dans le maître, 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 rompus ne peuvent être réparés que par Oracle.

Modifier: le correctif est prévu pour Java 11.0.2 par Oracle.

6
Michael-O