web-dev-qa-db-ja.com

Mavenを使用する場合、より厳密なJava 8 Javadocを回避する方法

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

Javadocを生成しない場合、もちろん問題は発生しませんが、Mavenリリースプロセスや、おそらくJDK7で正常に機能したCIビルドが突然失敗します。 Javadocツールの終了値をチェックするものはすべて失敗します。 JDK8のJavadocは、JDK7と比較してwarningsの観点からもおそらくより冗長ですが、それはここでの範囲ではありません。私たちはerrorsについて話している！

この質問は、それについて何をすべきかの提案を収集するために存在します。最善のアプローチは何ですか？これらのエラーは、ソースコードファイルで一度だけ修正する必要がありますか？巨大なコードベースがある場合、これは多くの作業になる可能性があります。他にどんなオプションがありますか？

また、以前は成功していた現在の失敗についてのストーリーをコメントすることもできます。

今失敗したもののホラーストーリー

wsimportツール

wsimportツールは、Webサービスコンシューマを作成するためのコードジェネレーターです。 JDKに含まれています。 JDK8のwsimportツールを使用しても、ソースコードは生成されます JDK8のjavadocコンパイラではコンパイルできません 。

@authorタグ

私は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で失敗します。 1つの簡単な修正方法は次のとおりです。

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

しかし、なぜこれがJavadocツールからの世界停止エラーでなければならないのですか??

より明白な理由で今失敗するもの

  1. 無効なリンク、たとえば{@link notexist}
  2. 不正な形式のHTML、例： always returns <code>true<code> if ...

更新

リンク：

すばらしい テーマに関するブログ by Stephen Colebourne 。

javamavenjava-8
128
peterh

今のところ、私が知っている最も簡単な方法は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に追加するだけで準備完了です。

Maven-javadoc-plugin 3.0.0ユーザーの場合：

交換

<additionalparam>-Xdoclint:none</additionalparam>

沿って

<doclint>none</doclint>

ありがとう@banterCZ！

55
Fred Porciúncula

Maven javadocプラグインを使用している場合、failOnErrorオプションを使用して、htmlエラーが見つかった場合に停止しないようにすることができます。

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

または、次のようにして厳密なhtmlオプションを完全に無効にすることができます。

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

詳細については、 info 。

50
assylias

Maven-javadoc-pluginのバージョン3.0.0以降、doclintは専用のXMLタグを介して設定されます

<plugin>
    <groupId>org.Apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>
3
Vlad Isajkin

私は@ThiagoPorciúnculaのソリューションが好きですが、それは私には十分ではありませんでした。

私は通常、プロファイルによってオーバーライドされないjavadocプラグインadditionalparamセットをすでに持っています。このために私はしなければなりませんでした：

  • disableDoclintプロパティをデフォルトで空に設定します。
  • Java> = 8の場合、disableDoclintプロパティを-Xdoclint:noneに設定します
  • ${disableDoclint} in theadditionalparamsection of themaven-javadoc-plugin`を使用します。

これは冗長ではありますがうまくいくようです。

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

次に、下で、すでに定義したadditionalparamセクションでオプションの${disableDoclint}変数を使用できます。

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

これはJava 8の下で機能しますが、Java 7の下で構文エラーを引き起こすことはありません。

3
Gray

エラーno summary or caption for tableでは、<table summary="">を使用しても機能しなくなることに注意してください。それがあなたの状況であれば、次のように<caption>要素をテーブルに追加します：

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

これが誰かに役立つことを願っています。これを見つけるまで、しばらく時間がかかりました。

1
Jeronimo Backes