JavaDocLint - 開発者ドキュメント

1. 概要

Javadocを使用することをお勧めする理由はたくさんあります。たとえば、JavaコードからHTMLを生成し、それらの定義をトラバースして、それらに関連するさまざまなプロパティを見つけることができます。

さらに、は開発者間のコミュニケーションを促進し、は保守性を向上させます。 Java DocLint は、Javadocを分析するためのツールです。構文が正しくない場合は、警告とエラーがスローされます。

このチュートリアルでは、それをどのように使用できるかに焦点を当てます。後で、特定の状況で発生する可能性のある問題と、それらを回避する方法に関するガイドラインについて説明します。

2. DocLintの使用方法

Sample.javaという名前のクラスファイルがあるとします。

/**
 * This sample file creates a class that
 * just displays sample string on standard output.
 *
 * @autho  Baeldung
 * @version 0.9
 * @since   2020-06-13 
 */
public class Sample {

    public static void main(String[] args) {
        // Prints Sample! on standard output.
        System.out.println("Sample!");
    }
}

意図的に、ここにタイプミスがあります。@authorパラメーターは@authoと記述されています。 DocLint ：なしでJavadocを作成しようとするとどうなるか見てみましょう。

コンソール出力からわかるように、Javadocエンジンはドキュメントの間違いを理解できず、エラーや警告を返しませんでした。

Java DocLintがこのタイプの警告を返すようにするには、– Xdoclintオプションを指定してjavadocコマンドを実行する必要があります。（これについては後で詳しく説明します）：

出力からわかるように、Javaファイルの5行目のエラーに直接言及しています。

Sample.java:5: error: unknown tag: autho
 * @autho  Baeldung
   ^

3. -Xdoclint

-Xdoclint パラメーターには、さまざまな目的のための3つのオプションがあります。それぞれについて簡単に説明します。

3.1. なし

none オプションは、-Xdoclintオプションを無効にします。

javadoc -Xdoclint:none Sample.java

3.2. グループ

このオプションは、特定のグループに関連する特定のチェックを適用する場合に役立ちます。次に例を示します。

javadoc -Xdoclint:syntax Sample.java

グループ変数にはいくつかの種類があります。

アクセシビリティ–アクセシビリティチェッカーによって検出される問題をチェックします（たとえば、テーブルタグでキャプションまたは要約属性が指定されていない）
html –ブロック要素をインライン要素内に配置したり、終了タグを必要とする要素を閉じなかったりするなど、高レベルのHTMLの問題を検出します
missing –欠落しているJavadocコメントまたはタグをチェックします（たとえば、欠落しているコメントまたはクラス、または欠落している @return タグまたはメソッド上の同様のタグ）
reference –JavadocタグからのJavaAPI要素への参照に関連する問題をチェックします（たとえば、 @see にないアイテム、または @param[の後の不正な名前） X182X]）
構文 –エスケープされていない山括弧（<および>）、アンパサンド（＆）、無効なJavadocタグなどの低レベルの問題をチェックします

一度に複数のグループを適用することが可能です。

javadoc -Xdoclint:html,syntax,accessibility Sample.java

3.3. すべて

このオプションはすべてのグループを一度に有効にしますが、それらの一部を除外したい場合はどうなりますか？

-group構文を使用できます。

javadoc -Xdoclint:all,-missing

4. DocLintを無効にする方法

JavaDocLintはJava8より前には存在しなかったため、特に古いサードパーティライブラリでは、これにより望ましくない問題が発生する可能性があります。

前のセクションでjavadocコマンドを使用したnoneオプションについてはすでに説明しました。さらに、Maven、GradleなどのビルドシステムからDocLintを無効にするオプションがあります。、蟻。これらについては、次のいくつかのサブセクションで説明します。

4.1. Maven

maven-javadoc-plugin では、バージョン3.0.0以降、新しいdoclint構成が追加されています。 DocLintを無効にするように構成する方法を見てみましょう。

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.1.1</version>
        <configuration>
            <doclint>none</doclint> <!-- Turn off all checks -->
        </configuration>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
            </execution>
        </executions>
    </plugin>
</plugins>

ただし、通常、noneオプションを使用することはお勧めしません。これは、すべてのタイプのチェックをスキップするためです。代わりにall、-missingを使用する必要があります。

以前のバージョン（v3.0.0より前）を使用する場合は、別の設定を使用する必要があります。

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

4.2. Gradle

簡単なスクリプトを使用して、GradleプロジェクトでDocLintを非アクティブ化できます。

if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
        tasks.withType(Javadoc) {
            options.addStringOption('Xdoclint:none', '-quiet')
        }
    }
}

残念ながら、Gradleは上記の例のMavenのように additionalparam をサポートしていないため、手動でサポートする必要があります。