こんにちは！ワーパパエトウです！
今回はJavadocの書き方とドキュメントHTMLの生成手順を解説します。
Javadocは作成したプログラムを説明するために記述するコメントのことで、下の図1.Javadocのようにクラスやメソッドの直前に記述し、そのクラスやメソッドの概要などを記載しておくものです。
Javadocを記載しておくことでプログラムを読まなくてもメソッドの仕様を把握することができますし、ドキュメントHTMLを生成することができるため現場によってはこのJavadocを詳細設計書代わりにしているところもあります。
ではさっそくJavadocの書き方とドキュメントHTMLを生成する手順についてみていきましょう！
Javadocの構成について
あくまでも主観となりますが、Javadocには対象クラスやメソッドには上図「Javadoc構成」の赤枠のように
①概要
②IN/OUTのパラメータ
③バージョンや作成者
の3点について記載しておけば問題ないでしょう。（※必ず各プロジェクトの方針に従ってください）
「①概要」では対象のクラスやメソッドの概要について記載しますが、このセクションではHTMLタグを使用することが可能です。
「②IN/OUTのパラメータ」ではアノテーション（@）を利用してIN/OUTのパラメータやスローする例外について記載します。
「③バージョンや作成者」についてはそのままですがバージョンや作成者を記載します。
簡単にですが主要なものについては下記にまとめておきます。
| # | アノテーション | 説明 | 重要度 |
| 1 | @param | Inputパラメータについて説明するときに使うアノテーション 例えば「@param roopCount ループ回数」のように書きます。 | ★★★ |
| 2 | @return | 戻り値について説明するときに使うアノテーション 例えば「@return XXXの場合はTRUEを返却、YYYの場合はFALSEを返却する」 のように書きます。 | ★★★ |
| 3 | @throws | 発生する可能性のある例外について説明するときに使うアノテーション 例えば「@throws Exception NULLが指定された場合に発生する」 のように書きます。 | ★★★ |
| 4 | @author | 作成者を記載するときに使うアノテーション 例えば「@author 作成者」のように書きます。 | ★★ |
| 5 | @see | 外部参照もしくは内部参照リンクしたい場合に使うアノテーション 例えば「@see #main(String[])」のように書きます。 | ★★ |
| 6 | @version | プログラムのバージョンを記載するときに使うアノテーション 例えば「@version 1.0」のように書きます。 | ★ |
| 7 | @since | 導入されたプログラムのバージョンを記載するときに使うアノテーション 例えば「@since 1.3」のように書きます。 | ★ |
| 8 | {@link} | 文字列中（①概要箇所）で参照リンクを埋め込みたい場合に使うアノテーション 例えば「呼び出し元{@link #main(String[])}でXXX」のように書きます。 | ★★ |
ドキュメントHTMLを作成する
ドキュメントHTMLを作成する方法は基本的に下記２パターンあります。
・Java API ドキュメントジェネレーターを使用してCUIベースで作成する
・EclipseなどのIDEを使用してGUIベースで作成する
今回はEclipseを使用してドキュメントHTMLを作成する手順を紹介します。
「ファイル」－「エクスポート」を選択し、エクスポート画面にて「Java」－「Javadoc」を選択する。
上図のJavadocを選択して「次へ」ボタンを押下してください。JavadocのドキュメントHTMLを作成するための画面が表示されます。
Javadocの生成画面にてドキュメントHTML作成対象のクラス、および、出力対象のスコープを選択して「完了」ボタンを押下する。
ドキュメントHTMLを作成する対象を選択するだけです。「次の可視性を持つメンバーのJavadocを作成」の選択項目については各プロジェクトの方針によるところが大きいので確認が必要です。
例えばprivateメソッドはその呼び出し元の一部として捉えてしまえば、ドキュメントHTMLを作成する必要がないということです。
ドキュメントHTML作成完了
特にエラーメッセージ等が表示されていなければドキュメントHTML作成完了です。
もしエラーメッセージが表示されるようならJavadocの記載を見直す必要があります。
作成されたドキュメントHTMLを確認する
上記のようなドキュメントHTMLが作成されました。
さいごにまとめ
ドキュメントHTMLはJavaのAPI仕様書と同様のフォーマットになっております。詳細設計書はどうしてもメンテが置き去りになりやすいドキュメントではありますが、今回のようにJavadocを活用することが出来ればみんなハッピーになれると思います。
詳細設計書にはJavadocを導入してみてはいかがでしょうか？
ではまた次回お会いしましょう！
コメント