Comment contourner le Javadoc Java 8 plus strict lors de l'utilisation de Maven

Vous vous rendrez vite compte que JDK8 est beaucoup plus strict (par défaut) en ce qui concerne Javadoc. ( lien - voir le dernier point)

Si vous ne générez jamais de Javadoc, bien sûr, vous ne rencontrerez aucun problème, mais des choses comme le processus de publication de Maven et peut-être vos builds CI échoueront soudainement là où ils fonctionnaient très bien avec JDK7. Tout ce qui vérifie la valeur de sortie de l'outil Javadoc échouera désormais. JDK8 Javadoc est probablement aussi plus verbeux en termes de warningsJDK7 mais ce n'est pas la portée ici. Nous parlons errors!

Cette question existe pour recueillir des propositions sur ce qu'il faut faire à ce sujet. Quelle est la meilleure approche ? Ces erreurs doivent-elles être corrigées une fois pour toutes dans les fichiers de code source? Si vous avez une base de code énorme, cela peut demander beaucoup de travail. Quelles autres options existent?

Vous êtes également invités à commenter avec des histoires de ce qui échoue maintenant qui passerait auparavant.

Histoires d'horreur de ce qui échoue maintenant

outils wsimport

wsimporttool est un générateur de code pour créer des consommateurs de services Web. Il est inclus dans le JDK. Même si vous utilisez l' wsimportoutil de JDK8, il produira néanmoins du code source qui ne peut pas être compilé avec le compilateur javadoc de JDK8 .

balise @author

J'ouvre des fichiers de code source âgés de 3 à 4 ans et vois ceci:

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

Cela échoue maintenant à cause du caractère <. À proprement parler, cela est justifié, mais pas très indulgent.

Tableaux HTML

Tableaux HTML dans votre Javadoc? Considérez ce HTML valide:

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

Cela échoue maintenant avec un message d'erreur no summary or caption for table. Une solution rapide consiste à faire comme ceci:

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

mais pourquoi cela doit être une erreur d'arrêt du monde de l'outil Javadoc me bat ??

Des choses qui échouent maintenant pour des raisons plus évidentes

1. Liens non valides, par exemple {@link notexist}
2. HTML malformé, par exemple always returns <code>true<code> if ...

METTRE À JOUR

Liens:

Excellent blog sur le sujet par Stephen Colebourne .

Pour l'instant, le moyen le plus simple que je connaisse pour contourner le Java 8 Javadoc plus strict lors de l'utilisation de Maven est de le désactiver.

Étant donné que le paramètre -Xdoclint:nonen'existe que dans Java 8, la définition de ce paramètre interrompt la construction pour tout autre Java. Pour éviter cela, nous pouvons créer un profil qui ne sera actif que pour Java 8, en nous assurant que notre solution fonctionne quelle que soit la version de Java.

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

Ajoutez simplement cela à votre POM et vous êtes prêt à partir.

Pour les utilisateurs de maven-javadoc-plugin 3.0.0:

Remplacer

<additionalparam>-Xdoclint:none</additionalparam>

par

<doclint>none</doclint>

Merci @banterCZ!

Si vous utilisez le plugin maven javadoc, vous pouvez utiliser l' failOnErroroption pour l'empêcher de s'arrêter s'il trouve des erreurs html:

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

Ou vous pouvez désactiver complètement les options html strictes avec:

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

Pour plus d' informations .

Depuis la version 3.0.0 de maven-javadoc-plugin, le doclint est configuré via la balise XML dédiée

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

J'aime la solution de @ ThiagoPorciúncula mais elle n'est pas allée assez loin pour moi.

J'ai généralement déjà un additionalparamensemble de plugins javadoc qui n'étaient pas remplacés par le profil. Pour cette raison, j'ai dû:

• Définissez une disableDoclintpropriété comme étant vide par défaut.
• Si dans java> = 8, définissez la disableDoclintpropriété sur-Xdoclint:none
• L'utilisation de ${disableDoclint} in theadditionalparam section of themaven-javadoc-plugin`.

Cela semble bien fonctionner, quoique détaillé.

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

Ensuite, en bas, je pourrais utiliser la ${disableDoclint}variable facultative dans la additionalparamsection que j'avais déjà définie.

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

Cela fonctionne sous java 8 mais ne provoque pas d'erreurs de syntaxe sous java 7. Woo hoo!

Notez que pour l'erreur no summary or caption for table, l'utilisation <table summary="">ne fonctionnera plus. Si c'est votre situation, ajoutez un <caption>élément à votre tableau, comme ceci:

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

J'espère que cela aide quelqu'un là-bas. Il m'a fallu un certain temps avant de le découvrir.