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

133

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 .

java  maven  java-8 
— peterh
źródło
13
Ten blog pokazuje, jak można to wyłączyć: blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
— Himanshu Bhardwaj
1
Możesz użyć -Xdoclinteven with, javacaby nakazać mu sprawdzenie dokumentów podczas kompilacji…
— Holger
1
@HimanshuBhardwaj. Dzięki za link do bloga Stephena Colebourne'a. Najlepszy jak dotąd artykuł na ten temat!
— peterh
Dodatkowo jeden z „błędów” jest również błędny: „złe użycie„> ”- jest to błędne,„> ”jest całkowicie akceptowalne w XML, z wyjątkiem określonej sekwencji„]]> ”, która nie jest akceptowana (jedna znaków musi zostać usunięty). Tylko „<” musi być zmieniony kodem ucieczki, „>” ma dla wygody mnemonik (gt), ale jego użycie jest całkowicie opcjonalne.
— StaxMan
Zastanawiam się, co jest ze zgodnością z HTML 4 zamiast HTML 5. Osobiście wolałbym prosty język znaczników, ponieważ muszę czytać kod źródłowy, a nie tylko ładne wyjście; i przynajmniej dla mnie czytelność HTML jest dyskusyjna.
— Daniel

Odpowiedzi:

56

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!

— Fred Porciúncula
źródło
3
Przyjmę to jako najbardziej prawdopodobne rozwiązanie, które większość z nas zastosuje. Podoba mi się ta <activation>część. Ale chciałbym, żeby ktoś wymyślił narzędzie, które mogłoby przejść przez te wiele plików źródłowych i pomóc deweloperowi w naprawieniu błędów ... zamiast po prostu wyłączać DocLint.
— peterh
Uważaj, używając tego rozwiązania, jeśli polegasz na tym, że inny profil jest domyślnie aktywny w tym samym czasie (używając activeByDefault = true).
— mwhs
1
@peterh: Nie ma sensu dokumentować w pełni wszystkiego, czyli bezużyteczną, powielaną pracę, zgodnie z zasadami czystego kodu zaleca się dokumentowanie tylko tego, co nieoczywiste, czyli publicznego API.
— Daniel Hári,
1
To nie działa z maven-javadoc-plugin w wersji 3.0.0. Musiałem wrócić do wersji 3.0.0-M1, aby zrobić -Xdoclint: nic nie działa.
— Mehrad Sadegh
4
@MehradSadegh Dla wtyczki maven-javadoc w wersji 3.0.0 wystarczy zastąpić <additionalparam>-Xdoclint:none</additionalparam>przez<doclint>none</doclint>
— banterCZ
53

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 .

— asylias
źródło
2
Hmm. Problem z tych rozwiązań jest to, że jeśli myślisz o tym z JDK8 Javadoc co chcesz nie niepowodzenie na błędy natomiast z JDK7 Javadoc robisz. Z tego powodu najbardziej lubię tę -Xdoclintopcję. Czy jest nadzieja, że ​​zostanie po cichu zignorowany, jeśli zostanie wykonany za pomocą JDK7 Javadoc?
— peterh
2
Możesz zastosować tę opcję warunkowo za pomocą profilu maven z kluczem w wersji Java…?
— Donal Fellows
14
Nie, z JDK7 nie udaje się z javadoc: błąd - niepoprawna flaga: -Xdoclint: brak (niezła robota Oracle).
— Giovanni Toraldo
4

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>
— Vlad Isajkin
źródło
3

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!

— Szary
źródło
2

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.

— Jeronimo Backes
źródło
1
Jaka wersja JDK? Na pewno <table summary="">sztuczka nadal działa na JDK8. (właśnie przetestowano na jdk1.8.0_201)
— peterh
@peterh Użyłem jdk 11.
— Jeronimo Backes
1
Oto aktualna odpowiedź. summary="..."atrybut nie jest już obsługiwany w HTML5 (domyślne dane wyjściowe dla JDK 11 javadoc). Jest również obsługiwany w JDK 8.
— kap
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.