Javadocとは決まったルールでクラスやメソッドのコメントに引数などを記述することで、簡単にリファレンスマニュアルを作成することができるツールです。
※AOSPのコーディング規約にもJavadocを使うようにと書かれています
リファレンスマニュアルはHTML形式として生成されるため、ブラウザがあれば閲覧することができます。
今回はJavadocの記述方法と、eclipseを使って仕様書を作成する方法を説明します。
それでは続きへどうぞ
Javadocの対象となるコメント記述方法
Javadocの対象となるにはコメントの記述方法もルールに従った形にする必要があります。
そしてコメントの中に後述するタグ（@paramなど）を記述します。
※HTMLタグも利用することができます
通常のJavaのコメントとの違いは「/」の後に「*」が2つ書かれているところがポイントです。
Javaのコメントの記載のルールとしては｢*｣が1つでも正しいですが、Javadocの対象にはならないので要注意です。
1行のコメント
/** コメント */
複数行のコメント
/** コメント コメント コメント */
または
/** * コメント * コメント * コメント */
タグ
Javadocで定義されているタグの中から主に使うものを挙げます。
[table “194” not found /]
記述例
それでは実際にJavadocに対応したコメントが書かれているソースの例を挙げます。
■src/JavadocSampleActivity.java
package org.techbooster.sample.javadocsample;
import android.app.Activity;
import android.os.Bundle;
import android.view.View;
import android.view.View.OnClickListener;
import android.widget.Button;
import android.widget.EditText;
import android.widget.TextView;
/**
* Javadocのためのサンプルクラス
*
* @author TechBooster
* @version 1.0
*/
public class JavadocSampleActivity extends Activity implements OnClickListener {
/**
* 1つ目の入力エリア
*/
EditText mNumberTextView1;
/**
* 2つ目の入力エリア
*/
EditText mNumberTextView2;
/**
* 結果を表示するTextView
*/
TextView mResultTextView;
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
mNumberTextView1 = (EditText) findViewById(R.id.editText1);
mNumberTextView2 = (EditText) findViewById(R.id.editText2);
mResultTextView = (TextView) findViewById(R.id.resultTextView);
Button performButton = (Button) findViewById(R.id.performButton);
performButton.setOnClickListener(this);
}
/**
* 計算の実行
*
* @since 1.0
*/
private void performCalculations() {
int number1 = Integer.valueOf(mNumberTextView1.getText().toString());
int number2 = Integer.valueOf(mNumberTextView2.getText().toString());
int result = add(number1, number2);
mResultTextView.setText(String.valueOf(result));
}
/**
* 2つの引数を足す
*
* @param number1
* @param number2
* @return 計算結果
* @since 1.0
*/
private int add(int number1, int number2) {
return number1 + number2;
}
/**
* OnClickListenerのメソッド
*
* @param v View
*/
@Override
public void onClick(View v) {
performCalculations();
}
}
クラスのコメントとして説明、著者名（作成者名）、バージョンを、メソッドのコメントとして説明、引数、戻り値、追加されたバージョンと最低限の項目だけを記述しています。
どのような内容をコメントに書けば良いかは開発の現場によってことなりますが、最低限今回のような項目があれば問題ないでしょう。
Javadocを生成する
それではJavadocを生成しましょう。コマンドラインから実行する方法もありますが、今回はeclipseのメニューから実行します。
まずeclipseのメニューの[プロジェクト]->[Javadocの生成]を選択します。
※日本語化していない場合は[project] -> [Generate javadoc…] -> [Next] -> [Next]
次に開くウインドウでJavadocを生成する対象のクラスと可視性を選択します。
privateを指定すると全てのメンバが生成の対象となります。もし、生成するクラスがライブラリとして提供するものであった場合、publicだけのメンバを生成の対象とした方が良いかもしれません。必要に応じて選択すると良いでしょう。
通常、「完了」ボタンを選択すればHTML形式のリファレンスが生成されます。
しかし、Javaファイルのテキストエンコーディングの関係でエラーが出て生成に失敗したり、生成されても文字化けしてしまうことがあります。
その場合は、生成時にJavadocのオプションを指定する必要があります。オプションを指定する時は上記の画面で「完了」ではなく、「次へ」を選択し、さらに次の画面でも「次へ」を選択します。
Javadocのオプションを指定するウインドウが開くので「-encoding “文字コード”」を入力します。ここでは合わせて「-charset “文字コード”」で生成されるHTML形式のリファレンスの文字 コードも指定しています。
- -encoding “utf-8” -charset “utf-8” ：生成元のJavaファイルの文字コードがUTF-8、HTMLファイルの文字コードをUTF-8で生成
オプションを指定して「完了」ボタンを押せば無事、リファレンスが生成されます。
eclipseによるコメント入力の手助け
リファレンスの生成まで完了したわけですが、各メソッドごとにJavadoc用のコメントを記述していくのは意外と手間になります。
そこで、少しでもそのコメントの記述を楽にするためにeclipseの便利な機能を使ってみましょう。
メソッドを追加したら、そのメソッドの上で右クリックしてメニューを開き、[ソース]->[要素コメントの生成]を選びます。
そうすると、eclipseがコメントを生成してくれます。後は説明を記述するだけです。
まとめ
コメントをちょっとしたJavadocのルールに従って書くだけで簡単にリファレンスを生成できるようになります。
eclipseのはJavadocの実行やコメントの記述をお手軽にしてくれる機能もあります。リファレンスを生成する必要がある場合はもちろんのこと、そうでない場合も将来に備えてJavadocのルールに従ってコメントを書いておいて損はないと思います。
eclipseならメソッドをマウスオーバー(マウスカーソルを重ねる)することによってJavadocのコメントを表示してくれるので便利です。