javadocを活用して内部仕様書を作成

javadocを意識して、コメントを入れているが、規約に含まれていないので、内部仕様書として、javadocを活用できていない。各自の意識で、javadocを意識したコメント記述があったり、なかったりなので、javadocを利用して、内部仕様書を、ちゃんと出力できない。
javadocを活用して、ソースファイルにコメントを記述するようにプロジェクトのコーディング規約に含めたい。内部仕様書として、javadocを活用するようにして、ドキュメントとソースコードの乖離を防ぐようにしよう。

• プログラムについての概要
• 各パッケージについての説明
• ソースファイルへのコメント

ソースファイルへのコメント記述は、下記の箇所に入れる。

• クラス／インタフェイス
• フィールド
• メソッド

コメント記述の内容としては

• 概要、使用例等（クラス、メソッド、フィールド）
• メソッドの引数
• メソッドの戻り値
• メソッドで返される例外
• 作成者（クラス）
• 更新履歴（クラス）
• バージョン（クラス）
• 関連項目（クラス、メソッド、フィールド）
• リンク項目（クラス、メソッド、フィールド）
• 非推奨（クラス、メソッド）

javadocを活用するために、コメント記述に特殊タグを使用する必要がある。特殊タグは@で始まる。

コメント記述で仕様するjavadocのタグ

@author 作成者
@version バージョン
@param メソッドの引数
@return メソッドの戻り値
@throws メソッドの例外
@see 関連項目
@link リンク項目
@deprecated 非推奨を示す

詳細は、下のjavadocドキュメントを参照。
javadoc 1.4 ドキュメント