1. 概要

優れたAPIドキュメントは、ソフトウェアプロジェクトの全体的な成功に寄与する多くの要因の1つです。

幸い、JDKの最新バージョンはすべてJavadocツールを提供しており、ソースコードにあるコメントからAPIドキュメントを生成できます。

前提条件：

  1. JDK 1.4（MavenJavadocプラグインの最新バージョンにはJDK7+をお勧めします）
  2. PATH環境変数に追加されたJDK/binフォルダー
  3. （オプション）組み込みツールを備えたIDE

2. Javadocコメント

コメントから始めましょう。

Javadocコメント構造は、通常の複数行コメントと非常によく似ていますが、主な違いは、先頭に追加のアスタリスクがあることです。

// This is a single line comment

/*
 * This is a regular multi-line comment
 */

/**
 * This is a Javadoc
 */

Javadocスタイルのコメントには、HTMLタグも含まれる場合があります。

2.1. Javadoc形式

Javadocコメントは、文書化するクラス、メソッド、またはフィールドの上に配置できます。

これらのコメントは通常、2つのセクションで構成されています。

  1. コメントしている内容の説明
  2. 特定のメタデータを説明するスタンドアロンのブロックタグ（「 @ 」記号でマーク）

この例では、より一般的なブロックタグのいくつかを使用します。 ブロックタグの完全なリストについては、リファレンスガイドにアクセスしてください。

2.2. クラスレベルのJavadoc

クラスレベルのJavadocコメントがどのようになるかを見てみましょう。

/**
* Hero is the main entity we'll be using to . . .
* 
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
* 
*/
public class SuperHero extends Person {
    // fields and methods
}

簡単な説明と2つの異なるブロックタグ（スタンドアロンとインライン）があります。

  • スタンドアロンタグは、説明の後に表示され、タグは行の最初の単語になります（例： @author tag）
  • インラインタグはどこにでも表示でき、中括弧で囲まれます。たとえば、説明の@linkタグです。

この例では、2種類のブロックタグが使用されていることも確認できます。

  • {@ link} は、ソースコードの参照部分へのインラインリンクを提供します
  • @author コメントされているクラス、メソッド、またはフィールドを追加した作成者の名前

2.3. フィールドレベルでのJavadoc

SuperHero クラス内では、次のようなブロックタグなしで説明を使用することもできます。

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

-private オプションをJavadocコマンドに明示的に渡さない限り、プライベートフィールドにはJavadocが生成されません。

2.4. メソッドレベルのJavadoc

メソッドには、さまざまなJavadocブロックタグを含めることができます。

私たちが使用している方法を見てみましょう：

/**
 * <p>This is a simple description of the method. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
 * @return the amount of health hero has after attack
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // do things
    return 0;
}

successfullyAttacked メソッドには、説明と多数のスタンドアロンブロックタグの両方が含まれています。

適切なドキュメントを生成するのに役立つ多くのブロックタグがあり、あらゆる種類のさまざまな種類の情報を含めることができます。 コメントで基本的なHTMLタグを利用することもできます。

上記の例で遭遇したタグを見てみましょう。

  • @param は、メソッドのパラメーターまたは必要な入力に関する有用な説明を提供します
  • @return は、メソッドが返す、または返すことができるものの説明を提供します
  • @see は、 {@ link} タグに似たリンクを生成しますが、インラインではなく参照のコンテキストで生成されます。
  • @since は、クラス、フィールド、またはメソッドがプロジェクトに追加されたバージョンを指定します
  • @version は、%I % a nd %G% macrosで一般的に使用されるソフトウェアのバージョンを指定します
  • @throws は、ソフトウェアが例外を予期するケースをさらに説明するために使用されます
  • @deprecated は、コードが非推奨になった理由、非推奨になった可能性がある場合、および代替手段について説明しています。

どちらのセクションも技術的にはオプションですが、Javadocツールが意味のあるものを生成するには少なくとも1つ必要です。

3. Javadocの生成

Javadocページを生成するために、JDKに付属しているコマンドラインツールとMavenプラグインを確認する必要があります。

3.1. Javadocコマンドラインツール

Javadocコマンドラインツールは非常に強力ですが、多少の複雑さが伴います。

オプションやパラメータを指定せずにコマンドjavadocを実行すると、エラーが発生し、予期したパラメータが出力されます。

少なくとも、ドキュメントを生成するパッケージまたはクラスを指定する必要があります。

コマンドラインを開いて、プロジェクトディレクトリに移動しましょう。

クラスがすべてプロジェクトディレクトリのsrcフォルダにあると仮定します。

user@baeldung:~$ javadoc -d doc src\*

これにより、– d フラグで指定されたように、docというディレクトリにドキュメントが生成されます。 複数のパッケージまたはファイルが存在する場合は、それらすべてを提供する必要があります。

もちろん、組み込み機能を備えたIDEを利用する方が簡単で、一般的に推奨されています。

3.2. Mavenプラグインを使用したJavadoc

MavenJavadocプラグインを利用することもできます。

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

プロジェクトのベースディレクトリで、コマンドを実行して、target\siteのディレクトリにJavadocを生成します。

user@baeldung:~$ mvn javadoc:javadoc

Mavenプラグインは非常に強力で、複雑なドキュメントの生成をシームレスに促進します。

生成されたJavadocページがどのようになるかを見てみましょう。

SuperHeroクラスが拡張するクラスのツリービューを見ることができます。 説明、フィールド、および方法を確認できます。詳細については、リンクをクリックしてください。

メソッドの詳細は次のようになります。

3.3. カスタムJavadocタグ

事前定義されたブロックタグを使用してドキュメントをフォーマットすることに加えて、 カスタムブロックタグを作成することもできます。

そうするために、私たちはただ含める必要があります -鬼ごっこ次の形式のJavadocコマンドラインへのオプション ： ：

。

生成されたドキュメントの「NotableLocations」ヘッダーに表示される、どこでも許可される @location というカスタムタグを作成するには、次のコマンドを実行する必要があります。

user@baeldung:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

このタグを使用するために、Javadocコメントのブロックセクションに追加できます。

/**
 * This is an example...
 * @location New York
 * @returns blah blah
 */

Maven Javadocプラグインは、pom.xmlでカスタムタグを定義することもできるほど柔軟です。

私たちのプロジェクトに上記と同じタグを設定するために、以下を追加することができますプラグインのセクション：

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag> 
</tags>
...

このようにして、カスタムタグを毎回指定するのではなく、一度指定することができます。

4. 結論

この簡単な紹介チュートリアルでは、基本的なJavadocを作成し、Javadocコマンドラインを使用してそれらを生成する方法について説明しました。

ドキュメントを生成する簡単な方法は、組み込みのIDEオプションを使用するか、Mavenプラグインを pom.xml ファイルに含めて、適切なコマンドを実行することです。

コードサンプルは、いつものように、GitHubのにあります。