web-dev-qa-db-fra.com

Comment contourner la Javadoc Java 8 plus stricte avec Maven

Vous réaliserez rapidement que JDK8 est beaucoup plus strict (par défaut) en ce qui concerne Javadoc. ( lien - voir dernier point)

Si vous ne générez jamais de Javadoc, vous ne rencontrerez bien entendu aucun problème, mais des processus tels que le processus de publication de Maven et éventuellement vos versions de CI échoueront brusquement là où ils fonctionnaient parfaitement avec JDK7. Tout ce qui vérifie la valeur de sortie de l'outil Javadoc va maintenant échouer. JDK8 Javadoc est probablement aussi plus bavard en termes de warnings par rapport à JDK7, mais ce n’est pas la portée ici. Nous parlons de 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 représenter beaucoup de travail. Quelles autres options existent?

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

Histoires d'horreur de ce qui échoue maintenant

wsimport outils

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

@author tag

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

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

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

Tableaux HTML

Tables HTML dans votre Javadoc? Considérons ce code HTML valide:

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

Cela échoue maintenant avec le 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 de stop-the-world 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 mal formé, par exemple always returns <code>true<code> if ...

METTRE À JOUR

Liens:

Excellent blog sur le sujet par Stephen Colebourne .

javamavenjava-8
126
peterh

Pour le moment, le moyen le plus simple que je connaisse de contourner le javadoc Java 8 plus strict lorsque Maven est utilisé est le désactiver.

Étant donné que le paramètre -Xdoclint:none n'existe que dans Java 8, sa définition interrompt la construction de 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!

53
Fred Porciúncula

Si vous utilisez le plugin maven javadoc, vous pouvez utiliser l'option failOnError 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 info .

50
assylias

Depuis la version 3.0.0 de maven-javadoc-plugin, 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>
3
Vlad Isajkin

J'aime bien la solution de @TiagoPorciúncula mais elle ne m'a pas suffisamment poussée. 

J'ai généralement déjà javadoc plugin additionalparam set qui n'a pas été remplacé par le profil. Pour cette raison, j'ai dû:

  • Définissez une propriété disableDoclint pour qu'elle soit vide par défaut.
  • Si vous utilisez Java> = 8, définissez la propriété disableDoclint sur -Xdoclint:none.
  • L'utilisation ${disableDoclint} in theadditionalparamsection of themaven-javadoc-plugin`.

Cela semble bien fonctionner bien que verbeux.

<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, je pouvais utiliser la variable optionnelle ${disableDoclint} dans la section additionalparam 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'erreur de syntaxe sous Java 7. Woo hoo!

3
Gray

Notez que pour l'erreur no summary or caption for table, l'utilisation de <table summary=""> ne fonctionnera plus. Si c'est votre cas, ajoutez un élément <caption> à votre table, 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 que je découvre cela.

0
Jeronimo Backes