Java ドキュメントのコメント


Java には 3 つのアノテーション方法しかありません。最初の 2 つは // と /* */ で、3 番目のタイプは説明コメントと呼ばれ、/**皮切りに*/ で終わります。

説明コメントを使用すると、プログラムに関する情報をプログラム内に埋め込むことができます。 javadoc ツール ソフトウェアを使用して情報を生成し、HTML ファイルに出力できます。

説明コメントを使用すると、プログラムに関する情報をより包括的な方法で記録できます。

javadoc タグ

javadoc ツール ソフトウェアは次のタグを認識します:

タグ 説明 例
@作者 クラスの作成者を特定する @著者の説明
@deprecated 期限切れのクラスまたはメンバーに名前を付けます @非推奨の説明
{@docRoot} 現在のドキュメントのルート ディレクトリへのパスを指定します ディレクトリ パス
@例外 クラスによってスローされた例外をマークします @例外例外名の説明
{@inheritDoc} 直接の親クラスから継承されたアノテーション 直接の上位クラスからコメントを継承します。
{@link} 別のトピックへのリンクを挿入します {@リンク名テキスト}
{@linkplain} 別のトピックへのリンクを挿入しますが、リンクはプレーン テキスト フォントで表示されます 別のトピックへのインライン リンクを挿入します。
@param メソッドのパラメーターを説明します @paramパラメータ名の説明
@return 戻り値の型を記述します @return 説明
@see 別のトピックへのリンクを指定します @アンカーを参照
@serial シリアル化属性を説明します @シリアル説明
@serialData writeObject() メソッドと writeExternal() メソッドを通じて書き込まれるデータについて説明します @serialData 説明
@serialField ObjectStreamField コンポーネントを説明します @serialField 名前の種類の説明
@since 特定の変更が導入されたときにマークを付けます @リリース以来
@throws @Exception タグと同じです @throws タグは @Exception タグと同じ意味を持ちます。
{@value} 定数の値を表示します。定数は静的プロパティである必要があります。 定数の値を表示します。定数は静的フィールドである必要があります。
@version クラスのバージョンを指定します @バージョン情報

ドキュメントコメント

冒頭の /** の後の最初の行は、クラス、変数、メソッドに関する主な説明です

その後、1 つ以上のさまざまな @ を含めることができます。タグ。各 @ タグは、新しい行の先頭に配置するか、行の先頭にアスタリスク (*) を続けて配置する必要があります。

同じ種類の複数のタグはグループ化する必要があります。たとえば、@see タグが 3 つある場合は、順番に配置します。

以下はクラス記述コメントの例です: 

/*** This class draws a bar chart.
* @author Zara Ali
* @version 1.2
*/

javadoc は何を出力しますか?

javadoc ツールは Java プログラムのソース コードを入力として受け取り、プログラムに関するコメントを含む HTML ファイルを出力します。

各クラスの情報は別の HTML ファイルに記載されます。 Javadoc は、継承されたツリー構造とインデックスを出力することもできます。

Javadoc の実装が異なるため、作業も異なる場合があります。Java 開発システムのバージョンとその他の詳細を確認し、適切な Javadoc バージョンを選択する必要があります。

例

以下は、命令アノテーションを使用する簡単な例です。各コメントは、説明する項目の前にあることに注意してください。

Javadoc 処理後、SquareNum クラスのコメントが SquareNum.html に見つかります。 

import java.io.*;
 
/**
* This class demonstrates documentation comments.
* @author Ayan Amhed
* @version 1.2
*/
public class SquareNum {
   /**
   * This method returns the square of num.
   * This is a multiline description. You can use
   * as many lines as you like.
   * @param num The value to be squared.
   * @return num squared.
   */
   public double square(double num) {
      return num * num;
   }
   /**
   * This method inputs a number from the user.
   * @return The value input as a double.
   * @exception IOException On input error.
   * @see IOException
   */
   public double getNumber() throws IOException {
      InputStreamReader isr = new InputStreamReader(System.in);
      BufferedReader inData = new BufferedReader(isr);
      String str;
      str = inData.readLine();
      return (new Double(str)).doubleValue();
   }
   /**
   * This method demonstrates square().
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */
   public static void main(String args[]) throws IOException
   {
      SquareNum ob = new SquareNum();
      double val;
      System.out.println("Enter value to be squared: ");
      val = ob.getNumber();
      val = ob.square(val);
      System.out.println("Squared value is " + val);
   }
}

次のように、javadoc ツールを使用して SquareNum.java ファイルを処理します。

←
→