Jak obejść bardziej rygorystyczne Java 8 Javadoc podczas korzystania z Maven

Szybko zdasz sobie sprawę, że JDK8 jest dużo bardziej rygorystyczny (domyślnie), jeśli chodzi o Javadoc. ( link - patrz ostatni podpunkt)

Jeśli nigdy nie wygenerujesz żadnego Javadoc, to oczywiście nie napotkasz żadnych problemów, ale rzeczy takie jak proces wydawania Maven i możliwe, że kompilacje CI nagle zawiodą, gdy działały dobrze z JDK7. Wszystko, co sprawdza wartość wyjścia narzędzia Javadoc, teraz zakończy się niepowodzeniem. JDK8 Javadoc jest prawdopodobnie również bardziej warningsrozwlekły w porównaniu z JDK7, ale nie o to tutaj chodzi. Mówimy o errors!

To pytanie istnieje po to, aby zebrać propozycje, co z tym zrobić. Jakie jest najlepsze podejście? Czy te błędy powinny zostać naprawione raz na zawsze w plikach kodu źródłowego? Jeśli masz ogromną bazę kodu, może to być dużo pracy. Jakie są inne opcje?

Możesz również komentować historie o tym, co teraz zawodzi, a które wcześniej minęło.

Przerażające historie o tym, co teraz zawodzi

narzędzia wsimport

wsimporttool to generator kodu do tworzenia konsumentów usług internetowych. Jest zawarty w JDK. Nawet jeśli użyjesz wsimportnarzędzia z JDK8, mimo to wygeneruje kod źródłowy , którego nie można skompilować za pomocą kompilatora javadoc z JDK8 .

Znacznik @author

Otwieram pliki z kodem źródłowym sprzed 3-4 lat i widzę to:

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

To teraz kończy się niepowodzeniem z powodu znaku <. Ściśle mówiąc jest to uzasadnione, ale niezbyt wybaczające.

Tabele HTML

Tabele HTML w Twoim Javadoc? Rozważ ten prawidłowy kod HTML:

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

To teraz kończy się niepowodzeniem i pojawia się komunikat o błędzie no summary or caption for table. Szybką naprawę można zrobić w ten sposób:

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

ale dlaczego to musi być błąd typu stop-the-world z narzędzia Javadoc, bije mnie?

Rzeczy, które teraz zawodzą z bardziej oczywistych powodów

1. Nieprawidłowe linki, np {@link notexist}
2. Nieprawidłowy format HTML, np always returns <code>true<code> if ...

AKTUALIZACJA

Spinki do mankietów:

Znakomity blog na ten temat autorstwa Stephena Colebourne'a .

Na razie najłatwiejszym sposobem obejścia ostrzejszego Java 8 Javadoc podczas korzystania z Maven jest jego dezaktywacja.

Ponieważ parametr -Xdoclint:noneistnieje tylko w Javie 8, zdefiniowanie tego parametru przerywa kompilację dla dowolnej innej Javy. Aby temu zapobiec, możemy stworzyć profil, który będzie aktywny tylko dla Java 8, upewniając się, że nasze rozwiązanie działa niezależnie od wersji Javy.

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

Po prostu dodaj to do swojego POM i gotowe.

Dla użytkowników maven-javadoc-plugin 3.0.0:

Zastąpić

<additionalparam>-Xdoclint:none</additionalparam>

przez

<doclint>none</doclint>

Dzięki @banterCZ!

Jeśli korzystasz z wtyczki maven javadoc, możesz użyć failOnErroropcji, aby zapobiec jej zatrzymaniu, jeśli wykryje jakiekolwiek błędy HTML:

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

Lub możesz całkowicie wyłączyć ścisłe opcje HTML za pomocą:

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

Więcej informacji .

Od wersji 3.0.0 wtyczki maven-javadoc-plugin doclint jest konfigurowany poprzez dedykowany tag XML

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

Podoba mi się rozwiązanie @ ThiagoPorciúncula, ale nie wyszło mi ono wystarczająco daleko.

Zwykle mam już additionalparamzestaw wtyczek javadoc, które nie były zastępowane przez profil. Z tego powodu musiałem:

• Ustaw disableDoclintwłaściwość tak, aby była domyślnie pusta.
• Jeśli w java> = 8, ustaw disableDoclintwłaściwość na-Xdoclint:none
• Użyj ${disableDoclint} in theadditionalparam section of themaven-javadoc-plugin`.

Wydaje się, że działa to dobrze, choć jest szczegółowe.

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

Następnie poniżej mogłem użyć opcjonalnej ${disableDoclint}zmiennej w additionalparamsekcji, którą już zdefiniowałem.

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

Działa to w Javie 8, ale nie powoduje błędów składniowych w Javie 7. Woo hoo!

Zauważ, że z powodu błędu no summary or caption for tableużywanie <table summary="">nie będzie już działać. Jeśli tak jest, dodaj <caption>element do swojej tabeli, na przykład:

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

Mam nadzieję, że to komuś pomoże. Zajęło mi trochę czasu, zanim się tego dowiedziałem.