plugin - Cómo trabajar en torno al Javadoc Java 8 más estricto al usar Maven

maven-compiler-plugin java 10

Question

Pronto se dará cuenta de que JDK8 es mucho más estricto (por defecto) cuando se trata de Javadoc. ( link - ver último punto)

Si nunca genera ningún Javadoc, entonces, por supuesto, no experimentará ningún problema, pero cosas como el proceso de lanzamiento de Maven y posiblemente sus compilaciones de CI fallarán repentinamente donde funcionaron bien con JDK7. Cualquier cosa que verifique el valor de salida de la herramienta Javadoc ahora fallará. JDK8 Javadoc es probablemente también más detallado en términos de warnings comparación con JDK7, pero ese no es el alcance aquí. Estamos hablando de errors !

Esta pregunta existe para recopilar propuestas sobre qué hacer al respecto. Cuál es el mejor enfoque ? ¿Deberían estos errores ser fijados de una vez por todas en los archivos de código fuente? Si tienes una gran base de código esto puede ser mucho trabajo. ¿Qué otras opciones existen?

También puedes comentar con historias de lo que ahora falla que pasaría previamente.

Historias de terror de lo que ahora falla

Herramientas de wsimport

wsimport herramienta wsimport es un generador de código para crear consumidores de servicios web. Está incluido en el JDK. Incluso si usa la herramienta wsimport de JDK8, producirá un código fuente que no se puede compilar con el compilador javadoc de JDK8 .

@author tag

Estoy abriendo archivos de código fuente de 3-4 años y veo esto:

/**
 * My very best class
 * @author John <[email protected]> 
 */

Esto ahora falla debido al <personaje. Estrictamente hablando, esto está justificado, pero no es muy indulgente.

Tablas HTML

Tablas HTML en tu Javadoc? Considere este HTML válido:

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

Esto ahora falla con el mensaje de error no summary or caption for table . Una solución rápida es hacer esto:

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

pero ¿por qué esto tiene que ser un error stop-the-world de la herramienta Javadoc me supera?

Cosas que ahora fallan por razones más obvias

1. Enlaces inválidos, por ejemplo, {@link notexist}
2. HTML mal formado, por ejemplo, always returns <code>true<code> if ...

ACTUALIZAR

Campo de golf:

Excelente blog sobre el tema de Stephen Colebourne .

Answer 1

Desde la versión 3.0.0 de maven-javadoc-plugin el doclint se configura a través de la etiqueta XML dedicada

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>

Answer 2

Me gusta la solución de @TiagoPorciúncula, pero no fue lo suficientemente lejos para mí.

Por lo general, ya tengo el complemento javadoc additionalparam set, que el perfil no anuló. Debido a esto, tuve que:

• Establezca una propiedad disableDoclint para que esté vacía de manera predeterminada.
• Si en java> = 8, establezca la propiedad disableDoclint para que sea -Xdoclint:none
• El uso ${disableDoclint} in the section of the adicionalparam section of the maven-javadoc-plugin`.

Esto parece funcionar bien aunque sea detallado.

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

Luego, a continuación, podría usar la variable opcional ${disableDoclint} en la sección de parámetros additionalparam que ya había definido.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
    </configuration>
</plugin>

Esto funciona bajo java 8 pero no causa errores de sintaxis en java 7. Woo hoo!

Answer 3

Por ahora, la manera más fácil que conozco de trabajar en torno al Javadoc Java 8 más estricto cuando uso Maven es desactivarlo.

Dado que el parámetro -Xdoclint:none solo existe en Java 8, la definición de este parámetro rompe la compilación para cualquier otra Java. Para evitar esto, podemos crear un perfil que estará activo solo para Java 8, asegurándose de que nuestra solución funcione independientemente de la versión de Java.

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

Solo agrégalo a tu POM y listo.

Para los usuarios de maven-javadoc-plugin 3.0.0:

Reemplazar

<additionalparam>-Xdoclint:none</additionalparam>

por

<doclint>none</doclint>

Gracias @banterCZ!

Answer 4

Si está utilizando el complemento maven javadoc, puede usar la opción failOnError para evitar que se detenga si encuentra algún error html:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

O puede desactivar las estrictas opciones html completamente con:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

Para más información