Come aggirare il Java 8 Javadoc più rigoroso quando si utilizza Maven

Ti accorgerai rapidamente che JDK8 è molto più rigoroso (per impostazione predefinita) quando si tratta di Javadoc. ( link - vedi l'ultimo punto elenco)

Se non si genera mai Javadoc, ovviamente non si verificheranno problemi, ma cose come il processo di rilascio di Maven e probabilmente i build CI non funzioneranno improvvisamente dove hanno funzionato perfettamente con JDK7. Tutto ciò che controlla il valore di uscita dello strumento Javadoc ora fallirà. JDK8 Javadoc è probabilmente anche più dettagliato warningsrispetto a JDK7, ma non è questo lo scopo. Stiamo parlando errors!

Questa domanda esiste per raccogliere proposte su cosa fare al riguardo. Qual è l'approccio migliore ? Questi errori dovrebbero essere corretti una volta per tutte nei file di codice sorgente? Se hai una base di codice enorme questo potrebbe richiedere molto lavoro. Quali altre opzioni esistono?

Sei anche invitato a commentare con storie di ciò che ora fallisce e che in precedenza sarebbe passato.

Storie horror di ciò che ora fallisce

strumenti wsimport

wsimporttool è un generatore di codice per la creazione di utenti di servizi web. È incluso nel JDK. Anche se si utilizza lo wsimportstrumento di JDK8, ciò produrrà comunque un codice sorgente che non può essere compilato con il compilatore javadoc di JDK8 .

@author tag

Sto aprendo i file del codice sorgente di 3-4 anni e vedo questo:

/**
 * My very best class
 * @author John <john.doe@mine.com> 
 */

Questo ora non riesce a causa del carattere <. A rigor di termini questo è giustificato, ma non molto indulgente.

Tabelle HTML

Tabelle HTML nel tuo Javadoc? Considera questo HTML valido:

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

Questo ora non riesce con messaggio di errore no summary or caption for table. Una soluzione rapida è fare in questo modo:

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

ma perché questo deve essere un errore irreversibile dallo strumento Javadoc mi batte ??

Cose che ora falliscono per ragioni più ovvie

1. Link non validi, ad es {@link notexist}
2. HTML non valido, ad es always returns <code>true<code> if ...

AGGIORNARE

link:

Ottimo blog sull'argomento di Stephen Colebourne .

Per ora, il modo più semplice che conosco per aggirare il Java 8 Javadoc più rigoroso quando utilizzo Maven è disattivarlo.

Poiché il parametro -Xdoclint:noneesiste solo in Java 8, la definizione di questo parametro interrompe la generazione per qualsiasi altro Java. Per evitarlo, possiamo creare un profilo che sarà attivo solo per Java 8, assicurandoci che la nostra soluzione funzioni indipendentemente dalla versione di Java.

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

Aggiungilo al tuo POM e sei a posto.

Per gli utenti di maven-javadoc-plugin 3.0.0:

Sostituire

<additionalparam>-Xdoclint:none</additionalparam>

di

<doclint>none</doclint>

Grazie @banterCZ!

Se stai usando il plugin javadoc di maven, puoi usare l' failOnErroropzione per impedirne l'arresto se trova errori html:

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

Oppure puoi disattivare completamente le rigide opzioni html con:

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

Per maggiori informazioni .

Dalla versione 3.0.0 di maven-javadoc-plugin il doclint è configurato tramite il tag XML dedicato

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

Mi piace la soluzione di @ ThiagoPorciúncula ma non è andata abbastanza lontano per me.

Di solito ho già un additionalparamset di plugin javadoc che non sono stati sovrascritti dal profilo. Per questo motivo ho dovuto:

• Impostare una disableDoclintproprietà su vuota per impostazione predefinita.
• Se in java> = 8, imposta la disableDoclintproprietà su-Xdoclint:none
• Usa il parametro ${disableDoclint} in theaggiuntivo section of themaven-javadoc-plugin`.

Questo sembra funzionare bene anche se dettagliato.

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

Quindi in basso potrei usare la ${disableDoclint}variabile opzionale nella additionalparamsezione che avevo già definito.

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

Funziona con Java 8 ma non causa errori di sintassi con Java 7. Woo hoo!

Si noti che per l'errore no summary or caption for table, l'utilizzo <table summary="">non funzionerà più. In questo caso, aggiungi un <caption>elemento alla tabella, in questo modo:

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

Spero che questo aiuti qualcuno là fuori. Mi ci è voluto un po 'prima che lo scoprissi.