Cómo evitar el Javadoc Java 8 más estricto cuando se utiliza Maven

Te darás cuenta rápidamente de que JDK8 es mucho más estricto (por defecto) cuando se trata de Javadoc. ( enlace - ver el último punto)

Si nunca genera ningún Javadoc, por supuesto, no experimentará ningún problema, pero cosas como el proceso de lanzamiento de Maven y posiblemente sus compilaciones de CI fallarán de repente 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 warningscomparación con JDK7, pero ese no es el alcance aquí. Estamos hablando errors!

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

También puede comentar con historias de lo que ahora falla y que anteriormente pasaría.

Historias de terror de lo que ahora falla

herramientas wsimport

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

Etiqueta @author

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

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

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

Tablas HTML

Tablas HTML en su 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 de detener el mundo de la herramienta Javadoc me gana?

Cosas que ahora fallan por razones más obvias

1. Enlaces inválidos, p. Ej. {@link notexist}
2. HTML con formato incorrecto, p. Ej. always returns <code>true<code> if ...

ACTUALIZAR

Enlaces:

Excelente blog sobre el tema de Stephen Colebourne .

Por ahora, la forma más fácil que sé para evitar el Javadoc Javadoc más estricto cuando uso Maven es desactivarlo.

Dado que el parámetro -Xdoclint:nonesolo existe en Java 8, la definición de este parámetro rompe la compilación para cualquier otro Java. Para evitar esto, podemos crear un perfil que estará activo solo para Java 8, asegurándonos 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 usuarios de maven-javadoc-plugin 3.0.0:

Reemplazar

<additionalparam>-Xdoclint:none</additionalparam>

por

<doclint>none</doclint>

Gracias @banterCZ!

Si está utilizando el complemento maven javadoc, puede usar la failOnErroropción 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 completamente las estrictas opciones html con:

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

Para obtener más información .

Desde la versión 3.0.0 de maven-javadoc-plugin, 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>

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

Por lo general, ya tengo el additionalparamconjunto de complementos javadoc que el perfil no anula. Debido a esto tuve que:

• Establecer una disableDoclintpropiedad para que esté vacía de forma predeterminada.
• Si en Java> = 8, establezca la disableDoclintpropiedad en-Xdoclint:none
• El uso ${disableDoclint} in theadicionalparam section of themaven-javadoc-plugin`.

Esto parece funcionar bien aunque 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, abajo, podría usar la ${disableDoclint}variable opcional en la additionalparamsección 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 en Java 8 pero no causa errores de sintaxis en Java 7. ¡Guau!

Tenga en cuenta que para el error no summary or caption for table, el uso <table summary="">ya no funcionará. Si esa es su situación, agregue un <caption>elemento a su tabla, como este:

<table>
    <caption>Examples</caption>
    ...
</table>

Espero que esto ayude a alguien por ahí. Me tomó un tiempo hasta que descubrí esto.