Javadocコメントでのメソッドの参照

1. 序章

このチュートリアルでは、JavadocコメントでJavaメソッドを参照する方法について説明します。 さらに、さまざまなクラスやパッケージのメソッドを参照する方法についても説明します。

2. @linkタグ

Javadocは、Javaクラスのメンバーを参照するための@linkインラインタグを提供します。 @link タグは、ハイパーリンクを介して1つのページを別のページにリンクするために使用されるHTMLのアンカータグに似ていると考えることができます。

@linkタグを使用してJavadocコメントのメソッドを参照するための構文を見てみましょう。

{@link path_to_member label}

アンカータグと同様に、 path_to_member が宛先であり、labelが表示テキストです。

ラベルはオプションですが、メソッドを参照するにはpath_to_memberが必要です。 ただし、複雑な参照リンクを避けるために、常にラベル名を使用することをお勧めします。 path_to_member の構文は、参照しているメソッドが同じクラスにあるかどうかによって異なります。

中括弧{と@linkの間にスペースがあってはならないことに注意してください。Javadocツールは、間にスペースがあると参照を正しく生成しません。 ただし、 path_to_member 、 label 、および閉じ中括弧の間にスペース制限はありません。

3. 同じクラスのメソッドを参照する

メソッドを参照する最も簡単な方法は、同じクラス内からです。

{@link #methodName() LabelName}

メソッドを文書化していて、同じクラス内から別のメソッドを参照したいとします。

/**
 * Also, check the {@link #move() Move} method for more movement details.
 */
public void walk() {
}

public void move() {
}

この場合、 walk（）メソッドは、同じクラス内の move（）インスタンスメソッドを参照します。

参照されているメソッドに引数がある場合、オーバーロードまたはパラメーター化されたメソッドを参照するときは常に、それに応じて引数のタイプを指定する必要があります。

オーバーロードされたメソッドを参照する次の例について考えてみます。

/**
 * Check this {@link #move(String) Move} method for direction-oriented movement.
 */
public void move() {

}

public void move(String direction) {

}

move（）メソッドは、1つのString引数を取るオーバーロードされたメソッドを参照します。

4. 別のクラスのメソッドを参照する

別のクラスのメソッドを参照するには、クラス名、ハッシュタグ、メソッド名の順に使用します。

{@link ClassName#methodName() LabelName}

構文は、＃シンボルの前にクラス名を記載することに加えて、同じクラスのメソッドを参照するのと似ています。

次に、別のクラスのメソッドを参照する例を考えてみましょう。

/**
 * Additionally, check this {@link Animal#run(String) Run} method for direction based run.
 */
public void run() {

}

参照されるメソッドはAnimalクラスにあり、同じパッケージのにあります。

public void run(String direction) {

}

別のパッケージにあるメソッドを参照する場合は、2つのオプションがあります。 1つの方法は、クラス名とともにパッケージを直接指定することです。

/**
 * Also consider checking {@link com.baeldung.sealed.classes.Vehicle#Vehicle() Vehicle} 
 * constructor to initialize vehicle object.
 */
public void goToWork() {

}

この場合、 Vehicle（）メソッドを参照するために、Vehicleクラスが完全なパッケージ名で言及されています。

さらに、パッケージをインポートして、クラス名だけを言及することができます：

import com.baeldung.sealed.records.Car;

/**
 * Have a look at {@link Car#getNumberOfSeats() SeatsAvailability} 
 * method for checking the available seats needed for driving.
 */
public void drive() {

}

ここでは、別のパッケージにあるCarクラスがインポートされています。 したがって、 @link には、クラス名とメソッドのみを含める必要があります。

別のパッケージのメソッドを参照するには、2つの方法のいずれかを選択できます。 パッケージを1回だけ使用する場合は、最初の方法を使用できます。それ以外の場合は、複数の依存関係がある場合は2番目の方法を選択する必要があります。

5. @linkplainタグ

コメントでメソッドを参照するための@linkJavadocタグを見てきました。 Javadocは、コメント内のメソッドを参照するための @linkplain という名前の別のタグを提供します。これは、@linkタグに似ています。 主な違いは、ドキュメントの生成中に、 @linkは等幅フォーマットのテキストでラベル値を生成するのに対し、@linkplainはプレーンテキストのような標準フォーマットでラベル値を生成することです。

6. 結論

この記事では、Javadocコメントでメソッドを参照する方法について説明し、他のクラスやパッケージでメソッドを参照する方法についても説明しました。 最後に、@linkタグと@linkplainタグの違いを調べました。

いつものように、この記事のコード例はGitHubのにあります。