[解決済み] Mavenを使用する際にJava 8のJavadocの厳しさを回避する方法

2022-06-05 08:33:40

質問

JDK8はJavadocに関しては（デフォルトで）かなり厳しいことがすぐにわかると思います。( リンク - 最後の箇条書きを参照)

Javadoc を生成しないのであれば、もちろん問題は発生しませんが、Maven リリースプロセスや、おそらく CI ビルドなどが、JDK7 では問題なく動作していたのに突然失敗することになります。Javadocツールの終了値をチェックするようなものは、すべて失敗する。JDK8のJavadocは、おそらく、より冗長な warnings の点でもJDK7に比べて冗長になっていると思われますが、ここではその点については触れません。私たちが話しているのは errors !

この質問は、それについてどうしたらいいかという提案を集めるために存在します。最良の方法は何でしょうか？これらのエラーは、ソースコード・ファイル内で一旦、すべて修正されるべきでしょうか? もしあなたが巨大なコードベースを持っているならば、これは大変な作業かもしれません。他にどのようなオプションがありますか？

また、以前はパスしていたものが今は失敗しているというエピソードをコメントすることも歓迎します。

失敗したときの怖い話

wsimport ツール

wsimport ツールは、ウェブサービスコンシューマを作成するためのコードジェネレータです。JDKに含まれています。たとえ wsimport ツールを使っても、ソースコードは生成されません。でコンパイルできないソースコードが生成されます。 .

著者タグ

3-4年前のソースコードファイルを開いてみると、こんな感じです。

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

これは今、< 文字のために失敗しています。厳密に言えば、これは正当化されますが、あまり寛容ではありません。

HTML テーブル

JavadocにHTMLテーブルがありますか？これは有効な HTML と考えてください。

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

これは現在、エラーメッセージで失敗しています no summary or caption for table . 手っ取り早いのは、このようにすることです。

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

が、なぜこれがJavadocツールのStop-the-Worldエラーでなければならないのか、私には理解できないのですが？

より明白な理由のために失敗するようになったもの

無効なリンク、例えば {@link notexist}
不正なHTML、例えば always returns <code>true<code> if ...

どのように解決するのですか？

今のところ、私が知っている最も簡単な方法は Maven を使用する際に、より厳しい Java 8 Javadoc を回避する。 を非アクティブにすることです。

パラメータ -Xdoclint:none というパラメーターは Java 8 にしか存在しないため、このパラメーターを定義すると他のどの Java でもビルドが中断されます。これを防ぐには、Java 8 に対してのみ有効なプロファイルを作成し、Java のバージョンに関係なくソリューションが動作するようにします。

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

これをPOMに追加すればOKです。

maven-javadoc-plugin 3.0.0 ユーザーのために。

置き換える

<additionalparam>-Xdoclint:none</additionalparam>

で

<doclint>none</doclint>

ありがとう、@banterCZ!