So umgehen Sie das strengere Java 8 Javadoc bei Verwendung von Maven

Sie werden schnell feststellen, dass JDK8 in Bezug auf Javadoc (standardmäßig) viel strenger ist. ( Link - siehe letzter Aufzählungspunkt)

Wenn Sie niemals Javadoc generieren, treten natürlich keine Probleme auf, aber Dinge wie der Maven-Release-Prozess und möglicherweise Ihre CI-Builds schlagen plötzlich fehl, wenn sie mit JDK7 einwandfrei funktionieren. Alles, was den Exit-Wert des Javadoc-Tools überprüft, schlägt jetzt fehl. JDK8 Javadoc ist im warningsVergleich zu JDK7 wahrscheinlich auch ausführlicher , aber das ist hier nicht der Umfang. Wir reden über errors!

Diese Frage besteht darin, Vorschläge zu sammeln, was dagegen zu tun ist. Was ist der beste Ansatz? Sollten diese Fehler ein für alle Mal in den Quellcodedateien behoben werden? Wenn Sie eine riesige Codebasis haben, kann dies eine Menge Arbeit sein. Welche anderen Möglichkeiten gibt es?

Sie können auch gerne Kommentare zu dem abgeben, was jetzt fehlschlägt und was zuvor vergangen wäre.

Horrorgeschichten von dem, was jetzt scheitert

wsimport tools

wsimportDas Tool ist ein Codegenerator zum Erstellen von Webdienstkonsumenten. Es ist im JDK enthalten. Selbst wenn Sie das wsimportTool von JDK8 verwenden, wird dennoch Quellcode erzeugt , der nicht mit dem Javadoc-Compiler von JDK8 kompiliert werden kann .

@author tag

Ich öffne Quellcodedateien, die 3-4 Jahre alt sind, und sehe Folgendes:

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

Dies schlägt nun aufgrund des Zeichens <fehl. Genau genommen ist dies gerechtfertigt, aber nicht sehr verzeihend.

HTML-Tabellen

HTML-Tabellen in Ihrem Javadoc? Betrachten Sie diesen gültigen HTML-Code:

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

Dies schlägt nun mit einer Fehlermeldung fehl no summary or caption for table. Eine schnelle Lösung besteht darin, Folgendes zu tun:

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

Aber warum muss dies ein Stop-the-World-Fehler des Javadoc-Tools sein?

Dinge, die jetzt aus offensichtlichen Gründen scheitern

1. Ungültige Links, z {@link notexist}
2. Fehlgeformtes HTML, z always returns <code>true<code> if ...

AKTUALISIEREN

Links:

Ausgezeichneter Blog zu diesem Thema von Stephen Colebourne .

Im Moment ist es am einfachsten, das strengere Java 8 Javadoc zu umgehen, wenn ich Maven verwende, es zu deaktivieren.

Da der Parameter -Xdoclint:nonenur in Java 8 vorhanden ist, wird durch das Definieren dieses Parameters der Build für jedes andere Java unterbrochen. Um dies zu verhindern, können wir ein Profil erstellen, das nur für Java 8 aktiv ist, um sicherzustellen, dass unsere Lösung unabhängig von der Java-Version funktioniert.

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

Fügen Sie das einfach Ihrem POM hinzu und Sie können loslegen.

Für Benutzer von maven-javadoc-plugin 3.0.0:

Ersetzen

<additionalparam>-Xdoclint:none</additionalparam>

durch

<doclint>none</doclint>

Danke @banterCZ!

Wenn Sie das Maven-Javadoc-Plugin verwenden, können Sie die failOnErrorOption verwenden, um zu verhindern, dass es gestoppt wird, wenn HTML-Fehler gefunden werden:

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

Oder Sie können die strengen HTML-Optionen vollständig deaktivieren mit:

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

Für weitere Informationen .

Seit Version 3.0.0 des maven-javadoc-plugins wird der doclint über das dedizierte XML-Tag konfiguriert

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

Ich mag die Lösung von @ ThiagoPorciúncula, aber sie ist mir nicht weit genug gegangen.

Normalerweise habe ich bereits ein Javadoc-Plugin- additionalparamSet, das vom Profil nicht überschrieben wurde. Aus diesem Grund musste ich:

• Legen Sie fest, dass eine disableDoclintEigenschaft standardmäßig leer ist.
• Wenn in Java> = 8, setzen Sie die disableDoclintEigenschaft auf-Xdoclint:none
• Die Verwendung ${disableDoclint} in theadditionalparam section of themaven-javadoc-plugin`.

Dies scheint gut zu funktionieren, wenn auch ausführlich.

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

Dann könnte ich unten die optionale ${disableDoclint}Variable in dem additionalparamAbschnitt verwenden, den ich bereits definiert hatte.

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

Dies funktioniert unter Java 8, verursacht aber unter Java 7 keine Syntaxfehler. Woo hoo!

Beachten Sie, dass die no summary or caption for tableVerwendung für den Fehler <table summary="">nicht mehr funktioniert. Wenn dies Ihre Situation ist, fügen Sie <caption>Ihrer Tabelle ein Element wie folgt hinzu:

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

Hoffe das hilft jemandem da draußen. Es dauerte eine Weile, bis ich das herausfand.