usar - javadoc tags

No se puede enlazar a JDK10 en los comentarios de Javadoc

Question

Después de actualizar de Java 9 a 10, los enlaces al JDK ya no funcionan cuando se genera documentación con la herramienta Javadoc (por ejemplo, para un archivo que importa java.util.Optional , {@link Optional} como Optional lugar de como Optional ; el mismo problema con @see , @param , @return , y en cualquier otro lugar donde normalmente vea los enlaces de Javadoc).

Tengo un proyecto modular simple, y estoy usando Maven con el complemento Javadoc (opciones de source y target establecidas en 10 en la sección de configuration del complemento del compilador). Tengo entendido que, de forma predeterminada, pasa el -link https://docs.oracle.com/javase/10/docs/api/ a la herramienta Javadoc. También entiendo que, históricamente, la herramienta Javadoc esperaba que un archivo de texto llamado package-list estuviera presente en la URL donde se le indicaba que buscara documentos externos. Java 8 tiene uno . Java 9 tiene uno . Java 10 no (error 404). Aparentemente, la herramienta Javadoc ahora genera un archivo de texto llamado element-list lugar de package-list para proyectos modularizados, pero parece que tampoco se proporciona (ni para Java 9 , pero está disponible para versiones de Java de acceso anticipado) 11 ).

La generación de Javadoc a través de IntelliJ con la opción Link to JDK documentation habilitada produce el mismo resultado. Dice que está pasando el -link https://docs.oracle.com/javase/10/docs/api/ a javadoc.exe , e informa javadoc: error - Error fetching URL: https://docs.oracle.com/javase/10/docs/api/ . A pesar del error, genera el Javadoc, pero al igual que con Maven, no hay enlaces JDK presentes.

¿Cómo se supone que esto funcione? ¿Se equivocó Oracle cuando pusieron los documentos JDK en línea?

Los bits relevantes de mi 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>

Salida 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"

Answer 1

... Comandante de Maven aquí.

Los bits apropiados ya se han agregado a Maven Javadoc Plugin en el master, pero eso no ayudará debido a un error en javadoc(1) en Java 11. Consulte MJAVADOC-561 para obtener más información. Los enlaces rotos solo pueden ser arreglados por Oracle.

Edición: la corrección está programada para Java 11.0.2 por Oracle.

Answer 2

Hay dos partes en esto.

1. En JDK 10, el formato y el nombre del archivo han cambiado, para soportar mejor los módulos. El nuevo nombre es "element-list" y el cambio de formato permite que la herramienta javadoc sepa qué módulos están presentes en una API, así como qué paquetes.

2. La copia de la API que se publica en https://docs.oracle.com/javase/10/docs/api/overview-summary.html parece estar bloqueando el archivo "element-list", dando un 404 que necesita Para ser investigado y arreglado.

Tenga en cuenta que necesitará usar una versión JDK 10 de javadoc para apuntar a la API JDK 10. La última versión de la herramienta comprende tanto la lista de elementos (para documentos sobre módulos) como la lista de paquetes (para documentos sobre paquetes (es decir, sin módulos)).

Answer 3

Mi solución por el momento es apuntar javadoc.exe a una package-list local usando la opción offlineLinks del complemento Javadoc de Maven (que corresponde a la opción de linkoffline de línea de la herramienta Javadoc). Agregué lo siguiente a la sección de configuration para el complemento:

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

Y agregué <maven.compiler.release>10</maven.compiler.release> a la sección de properties de mi pom.xml para poder usar ${maven.compiler.release} en el valor de la url . (Eso hace que las opciones del compilador de source y target redundantes, pero IntelliJ no parece entender el release cuando se importan proyectos de Maven, así que los mantuve).

Creé un archivo de texto llamado package-list (sin extensión de archivo) y lo puse en el directorio raíz del proyecto (de ahí ${project.basedir} para la location , que es donde buscará package-list de package-list ). Ese archivo se ve así:

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

Solo necesita los paquetes a los que intentas enlazar. También intenté nombrar la element-list del archivo y seguir el formato que utiliza javadoc.exe para proyectos modularizados, como por ejemplo:

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

Pero eso no funcionó (Javadoc se generó con éxito, pero no enlaces JDK, como antes). Se quejó de que no pudo encontrar package-list .

Así que, una vez más, los bits relevantes 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>