javadocを活用して内部仕様書を作成
javadocを意識して、コメントを入れているが、規約に含まれていないので、内部仕様書として、javadocを活用できていない。各自の意識で、javadocを意識したコメント記述があったり、なかったりなので、javadocを利用して、内部仕様書を、ちゃんと出力できない。
javadocを活用して、ソースファイルにコメントを記述するようにプロジェクトのコーディング規約に含めたい。内部仕様書として、javadocを活用するようにして、ドキュメントとソースコードの乖離を防ぐようにしよう。
- プログラムについての概要
- 各パッケージについての説明
- ソースファイルへのコメント
ソースファイルへのコメント記述は、下記の箇所に入れる。
- クラス/インタフェイス
- フィールド
- メソッド
コメント記述の内容としては
- 概要、使用例等(クラス、メソッド、フィールド)
- メソッドの引数
- メソッドの戻り値
- メソッドで返される例外
- 作成者(クラス)
- 更新履歴(クラス)
- バージョン(クラス)
- 関連項目(クラス、メソッド、フィールド)
- リンク項目(クラス、メソッド、フィールド)
- 非推奨(クラス、メソッド)
javadocを活用するために、コメント記述に特殊タグを使用する必要がある。特殊タグは@で始まる。
コメント記述で仕様するjavadocのタグ
@author 作成者 @version バージョン @param メソッドの引数 @return メソッドの戻り値 @throws メソッドの例外 @see 関連項目 @link リンク項目 @deprecated 非推奨を示す
詳細は、下のjavadocドキュメントを参照。
javadoc 1.4 ドキュメント