Javadocの基本的な書き方

投稿日:

こんにちは、okuzawatsです。
Javaをジャバジャバ書いています。

Javadocの基本的な書き方についてまとめておきます。
Javadocは、Javaのソースコード内に書く、特別なコメントです。
publicなメソッドなどに関する説明を書いておきます。

Javadocは、特別にフォーマットされたドキュメンテーションコメント(documentation comment)、より一般的にはドキュメントコメント(doc comment)と呼ばれるもので、ソースコードから自動的にAPIドキュメンテーションを生成します。

出典:Effective Java 第2版、p.196

Effective Javaに寄れば、「すべての公開されているクラス、インターフェース、コンストラクタ、メソッド、フィールド宣言の前にドキュメントコメントを書かなければならない」そうです。

具体的には、引数、戻り値、例外などについて書きます。

メソッドに対するドキュメントコメントには、すべてのパラメータに対する@paramタグ、メソッドに戻り値があれば@returnタグ、そして、チェックされるされないに関係なくそのメソッドがスローするすべての例外に対する@throwsタグが書かれるべきです。

出典:Effective Java 第2版、pp.196-197

Javadocの基本的な書き方

Javadocの最初に、全体的な説明を書いておきます。
この説明文は、後で説明する「タグセクション」の前に書かなければなりません。

/**
 * ここに説明を書く。
 */

以下、タグセクションの説明です。
タグセクションでは、@から始まるタグを使って、各項目に関する説明を書いていきます。

authorタグには、作成者(あなたのことです)を書きます。

/**
 * @author okuzawats //作者の名前を書く
 */

paramタグには、引数(パラメータ)の説明を書きます。
引数が複数ある場合には、それぞれの引数について書いていきます。

/**
 * @param title 表示するタイトル //パラメータの説明を書く
 * @param message 表示する文字列 //パラメータの説明を書く
 */

returnタグには、戻り値の説明を書きます。
戻り値がない場合(voidの場合)はreturnタグの記述を省略します。

/**
 * @return //戻り値の説明を書く
 */

throwsタグでは、メソッドが投げるすべての例外について、例外がスローされる条件に関する説明を書きます。

/**
 * @throws Exception //投げられる例外について書く
 */

ここまで出てきた内容をまとめてJavadocに書くと、こんな感じになります。

 /**
 * ここに説明を書く。
 * @author okuzawats //作者の名前を書く
 * @param title 表示するタイトル //パラメータの説明を書く
 * @param message 表示する文字列 //パラメータの説明を書く
 * @return //戻り値の説明を書く
 * @throws Exception //投げられる例外について書く
 */

Javadocには他にもタグがあるんですが、基本的な使い方としてはこれくらいでいいでしょうか。

参考書籍

茨城県つくば市在住のAndroidアプリエンジニアです。Androidアプリ開発に関して何かあれば、メールフォームからお問い合わせください。できる範囲でお答えします。

メールフォーム

-プログラミング

Copyright© Androidアプリ開発@つくば , 2017 AllRights Reserved Powered by AFFINGER4.