Javadocの基礎知識 #Java

Javadocとは？

javadocとは，「ドキュメントを作るのが面倒なので，プログラム中に特定のルールに従って付けたコメントを抽出してドキュメントを作っちゃう」考え方に沿って，Java言語のソースコードからドキュメントを生成する仕組みです．これにより，ドキュメントファイルを紛失することも無くなります．

インストール方法

特にインストールしなくても，jdkに付属しています．

書式

以下のルールに則って，コメントとして記述する．

基本的にはJava言語のコメントの中に記述する．通常，Java言語のコメントは「/*」で始まり「*/」で終わるが，javadocでは「/**」で始まり「*/」で終わる．
複数行にまたがることも可能だし，1行で書くこともできる．
1. 「@」は特殊な記号として扱われる．例えば「@‌author」はプログラム製作者を表し，「@‌version」はバージョンを表すタグである．「@‌param」はメソッドのパラメータを表し，「@‌return」はメソッドの返り値を表す．その他にもさまざまなタグが存在する．
「/**」から「*/」の間の行頭には「*」を入れておく．（無くても良いが，揃えておくほうが見やすい）
複数行にまたがる場合は，ピリオドまでが概要説明でそれ以降が詳細説明である．詳細説明が複数行にまたがってもよいが，改行されない．改行したい場合は「
」を入れること．コマンドラインパラメータに何を与えればよいか？や，使用例などもここに記述すること．

以下に，与えられた数値の遇奇を判断するis_evenメソッドと，is_evenメソッドを含むMethod8クラスを記す．

通常，クラス宣言の前やメソッド宣言の前に挿入する．

1行目から始まる部分は，クラス全体に対するコメントであり，この場合は作者が「Suda」でバージョンが「1.0」であることを示す．

is_evenメソッドの前に4行のコメントが付いているが，先頭からメソッドの名称，詳しい説明，パラメータ，返り値について記述されている．

/**
 * @author Suda
 * @version 1.0
 */
public class Method8 {
    /**
     * is_evenメソッド
     * パラメータが偶数ならtrueを返し，奇数ならfalseを返す.
     * @param number 数値
     * @return 数値が偶数ならtrue
     */
    public static boolean is_even( int number ) {
        return( number % 2 == 0 );
    }
}

ドキュメントの作成方法

javadocコマンドを用いて上記のソースコードからドキュメントを作成する場合，以下のように実行すれば良い．これにより，コメント内の情報を拾い上げて，HTML形式のドキュメントが作成される．

$ javadoc -d html Method8.java

うまく実行できていれば，htmlという名前のディレクトリが作成され，ドキュメントがその下に作られる．とりあえず「index.html」をWebブラウザで開いて内容を確認して欲しい．

また，複数のソースコードをまとめてjavadoc化したい場合は，ファイル名を列挙するかワイルドカードを使えば良い．

$ javadoc -d html Test1.java Test2.java Test3.java
　または
$ javadoc -d html *.java