Javadoc：@seeおよび@link

投稿日: 2022-11-10 2022-11-10
タグ: Java, javadoc

1. 概要

Javadoc は、JavaソースコードからHTML形式で最新のJavaドキュメントを生成するための優れた方法です。

このチュートリアルでは、ドキュメントコメントの@seeタグと@linkタグに焦点を当てます。

2. @see

@seeタグの形式は非常に単純です。

@see reference

たとえば、これを使用して、公式のJavaドキュメントへの外部リンクをマークできます。

/**
 * @see <a href="https://docs.oracle.com/en/java/">Java Dcoumentation</a>
 */

つまり、参照を指すリンクまたはテキストエントリが必要な場合は、@ seeタグを使用します。このタグは、参照に「関連項目」の見出しを追加します。ドキュメントコメントには、任意の数の @see タグを含めることができ、それらはすべて同じ見出しの下にグループ化できます。 Oracle doc には、その使用方法に関する詳細な手順が記載されています。このタグは有効であり、パッケージ、概要、コンストラクター、クラス、インターフェイスなど、任意のドキュメントコメントで使用できます。 @see タグには、以下で説明する3つのバリエーションがあります。

**2.1。@see「テキスト文字列」**

これにより、リンクの種類を生成せずにテキスト文字列のテキストエントリが追加されます。文字列は、本のページや、その他のコンテキストで提供する必要のあるその他の追加情報を参照できます。 Javadocツールは、最初の文字として二重引用符（“）を探すことにより、テキスト文字列を他の場合とは異なります。例を考えてみましょう：

/**
 * @see "This method performs some function."
 */
public void someMethod() {
  // do Something...
}

これは次のようにレンダリングされます：

2.2. @見る href =” URL”> label

これにより、URLを定義するリンクが追加されます。 URLは、相対URL値または絶対URL値にすることができます。 Javadocツールは、テキスト文字列を他の場合とは異なり、最初の文字として小なり記号（<）を確認し、次に、 URL#value. The URL#value 相対URLまたは絶対URLです。 Javadocツールは、より小さい記号を探すことにより、これを他の場合と区別します（<）最初の文字として。アンカータグ内にリンクを表示する次の例について考えてみます。

/**
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 */
public void someMethodV2() {
  // do Something...
}

これにより、次のようにテキストが生成されます。

2.3. @ see package.class＃member label

これにより、関数を定義するリンクが追加されます。ラベルはオプションであり、未定義の場合はクラスの元のメンバー名を使用します。 -no qualifierオプションは、表示されているテキストからパッケージ名を削除します。 package.class＃memberは、パッケージ、クラス、インターフェイス、フィールド名などの要素名を参照します。次の例について考えてみます。

/**
 * @see String#toLowerCase() convertToLowerCase
 */
public void addingSeeToAMethod() {
  // do Something...
}

上記のアノテーション用に作成された標準のHTMLは、次のようになります。

<dl> 
<dt><b>See Also:</b> 
<dd><a href="../../java/lang/String#toLowerCase()"><code>convertToLowerCase<code></a> 
</dl>

これは、ブラウザで以下の出力に変換されます。

注：ラベル内で複数のスペースを使用できます。

3. @link

これはインラインタグです。 @linkタグの形式は非常に簡単です。

{@link  package.class#member  label}

@linkタグを使用するための以下の例を見てみましょう。

/**
 * Use the {@link String#equalsIgnoreCase(String) equalsMethod} to check if two strings are equal.
 */

これにより、テキストラベルが表示されたインラインリンクが挿入されます。テキストラベルは、指定されたパッケージ、クラス、またはメンバー名のドキュメントを指します。このタグは、概要、パッケージ、クラス、メソッド、フィールドなど、どこでも使用できます。これは、 @return 、 @param 、@deprecatedなどのタグのテキスト部分内でも使用できます。このタグは@seeと非常によく似ています。どちらも同じ参照を必要とし、 package.class＃memberとlabelに対して同じ構文を受け入れるからです。

上記のアノテーション用に作成された標準のHTMLは、次のようになります。

Use the <code>equalsMethod</code> to check if two strings are equal.

これにより、ブラウザで次のようにレンダリングされます。

4. @seeと@linkの類似点

このセクションでは、@seeタグと@linkタグの類似点を見てみましょう。

クラス、パッケージ、またはメソッドで@seeタグと@linkタグを複数回使用できます。 @see タグは、外部リンク、クラス、またはメソッドを指す参照を宣言します。 @link タグは、インラインリンクを宣言するために、または他のブロックタグとは対照的に、複数回使用することもできます。 @seeおよび@linkタグの構文を示す以下の例を検討してください。

/**
 * Use {@link String#toLowerCase()} for conversion to lower case alphabets.
 * @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
 * @return {@link String} object
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 * @see String#hashCode() hashCode
 */
public String someMethod() {
  // perform some function
  return "";
}

5. @seeと@linkの違い

このセクションでは、@seeタグと@linkタグの違いを見てみましょう。

5.1. 両方とも異なるタグに属しています

ドキュメントコメントは、次の2つのタイプに分類できます。

タグをブロックする
インラインタグ

ブロックタグには、行の先頭に表示される@tag形式があります。先頭のアスタリスク、空白、および区切り文字（ / ** ）は無視されます。 @see は、ブロックタグのそのような例の1つです。

インラインタグは中括弧内に表示され、 {@tag}の形式になります。また、テキストが許可されている場所であればどこでも許可および解釈する必要があります。インラインタグでも他のタグを使用できます。説明やコメントのどこにでも存在できます。

/**
 * Some description here.
 *
 * @see java.lang.Object
 * @return  This will return {@link #toString() string} response.
 */

@seeタグと@linkタグの主な違いは、一方がインラインリンクを生成するのに対し、もう一方は「関連項目」セクションにリンクを表示することです。また、 @link [ X182X]タグは、インラインテキストの残りの部分からタグを区切る中括弧で開始および終了します。 @see タグはブロックタグであるため、明示的に作成します。

@seeおよび@linkタグの出力を表示する次の例について考えてみます。

/**
 *
 * Use {@link String#toLowerCase()} for conversion to lower case alphabets.
 * @deprecated As of Java 1.8 {@link java.security.Certificate} is deprecated.
 * @return {@link String} object
 * @see <a href="http://www.baeldung.com">Baeldung</a>
 * @see String#hashCode() hashCode
 */
public String someMethod() {
  // perform some function
  return "";
}

これにより、Javadocに次の出力が生成されます。

5.3. @seeおよび@linkタグの使用

ブロックタグは独立して使用され、他のタグと一緒に使用することはできません。一方、インラインタグはドキュメントコメント内またはインラインリンクとして使用されます。 @linkタグを他のブロックタグと一緒に使用することもできます。@linkタグを他のブロックタグと一緒に使用している次の例を考えてみます。

/**
 * Some description here.
 *
 * @see java.lang.Object
 * This is a {@link #getClass() } method.
 * @see #getClass() Use {@link #toString()} for String conversion.
 * @deprecated As of JDK 1.1, replaced by {@link #someMethod()}
 */

6. 結論

このチュートリアルでは、@seeタグと@linkタグを正しく使用する方法について説明しました。次に、コメントタグの種類と、@seeのさまざまな使用方法について説明しました。最後に、@seeタグと@linkタグの主な違いについても説明しました。つまり、 @see タグを使用して、参照を指すリンクまたはテキストを表示できます。 @link タグは、テキストまたはその他のタグ内のリンクを記述します。インラインとして。

getdocs

13036