Cara bekerja di sekitar Java 8 Javadoc yang lebih ketat saat menggunakan Maven

Anda akan segera menyadari bahwa JDK8 jauh lebih ketat (secara default) ketika datang ke Javadoc. ( tautan - lihat poin terakhir)

Jika Anda tidak pernah menghasilkan Javadoc maka tentu saja Anda tidak akan mengalami masalah tetapi hal-hal seperti proses rilis Maven dan mungkin membangun CI Anda tiba-tiba akan gagal di mana mereka bekerja dengan baik dengan JDK7. Apa pun yang memeriksa nilai keluar dari alat Javadoc sekarang akan gagal. JDK8 Javadoc mungkin juga lebih verbose dalam hal warningsdibandingkan dengan JDK7 tapi itu bukan cakupannya di sini. Kita bicarakan errors!

Pertanyaan ini ada untuk mengumpulkan proposal tentang apa yang harus dilakukan. Apa pendekatan terbaik? Haruskah kesalahan ini diperbaiki sekali dan untuk semua dalam file kode sumber? Jika Anda memiliki basis kode yang besar ini mungkin banyak pekerjaan. Apa pilihan lain yang ada?

Anda juga dipersilakan untuk berkomentar dengan cerita-cerita tentang apa yang sekarang gagal yang sebelumnya akan berlalu.

Kisah-kisah horor tentang apa yang sekarang gagal

alat bantu

wsimportalat adalah penghasil kode untuk menciptakan konsumen layanan web. Itu termasuk dalam JDK. Bahkan jika Anda menggunakan wsimportalat dari JDK8 itu akan tetap menghasilkan kode sumber yang tidak dapat dikompilasi dengan kompilator javadoc dari JDK8 .

@ tag penulis

Saya membuka file kode sumber berusia 3-4 tahun dan melihat ini:

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

Ini sekarang gagal karena <karakter. Sebenarnya ini dibenarkan, tapi tidak terlalu pemaaf.

Tabel HTML

Tabel HTML di Javadoc Anda? Pertimbangkan HTML yang valid ini:

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

Ini sekarang gagal dengan pesan kesalahan no summary or caption for table. Satu perbaikan cepat adalah melakukan seperti ini:

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

tetapi mengapa ini harus menjadi stop-the-world error dari alat Javadoc mengalahkan saya ??

Hal-hal yang sekarang gagal karena alasan yang lebih jelas

1. Tautan tidak valid, mis {@link notexist}
2. HTML salah format, mis always returns <code>true<code> if ...

MEMPERBARUI

Tautan:

Baik blog pada subjek oleh Stephen Colebourne .

Untuk saat ini, cara termudah yang saya tahu untuk bekerja di sekitar Java 8 Javadoc yang lebih ketat saat menggunakan Maven adalah menonaktifkannya.

Karena parameter -Xdoclint:nonehanya ada di Java 8, mendefinisikan parameter ini memecah build untuk Java lainnya. Untuk mencegah hal ini, kita dapat membuat profil yang hanya akan aktif untuk Java 8, memastikan solusi kami berfungsi terlepas dari versi Java.

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

Cukup tambahkan itu ke POM Anda dan Anda siap melakukannya.

Untuk pengguna maven-javadoc-plugin 3.0.0:

Menggantikan

<additionalparam>-Xdoclint:none</additionalparam>

oleh

<doclint>none</doclint>

Terima kasih @banterCZ!

Jika Anda menggunakan plugin maven javadoc, Anda dapat menggunakan failOnErroropsi untuk mencegahnya berhenti jika menemukan kesalahan html:

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

Atau Anda dapat menonaktifkan opsi html ketat sepenuhnya dengan:

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

Untuk info lebih lanjut .

Sejak versi 3.0.0 dari maven-javadoc-plugin doclint dikonfigurasi melalui tag XML khusus

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

Saya suka solusi @ ThiagoPorciúncula tetapi tidak cukup jauh bagi saya.

Saya biasanya sudah memiliki additionalparamset plugin javadoc yang tidak ditimpa oleh profil. Karena itu saya harus:

• Setel disableDoclintproperti menjadi kosong secara default.
• Jika dalam java> = 8, atur disableDoclintproperti menjadi-Xdoclint:none
• Penggunaan ${disableDoclint} in thetambahanparam section of themaven-javadoc-plugin`.

Ini tampaknya bekerja dengan baik meskipun bertele-tele.

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

Kemudian di bawah saya bisa menggunakan ${disableDoclint}variabel opsional di additionalparambagian yang sudah saya definisikan.

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

Ini berfungsi di bawah java 8 tetapi tidak menyebabkan kesalahan sintaksis di bawah java 7. Woo hoo!

Perhatikan bahwa untuk kesalahan no summary or caption for table, menggunakan <table summary="">tidak akan berfungsi lagi. Jika itu situasi Anda, tambahkan <caption>elemen ke tabel Anda, seperti ini:

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

Semoga ini bisa membantu seseorang di luar sana. Butuh beberapa saat sampai saya mengetahui hal ini.