Javaでは、javadocというコマンドで、ソースプログラムからAPI仕様を生成することができます。 API仕様をjavadocで出力することにより、Javaの標準API仕様と、形式を統一することができます。 また、ソースから生成することで、ソースと仕様書の不整合を減らすことができます。
javadocは、/** で始まるコメントを参照して、自動的に出力されます。
そこで、1行の場合と、複数行の場合で、以下のルールで記述しています。
また、コメントの最初の1文は、概要部分にも反映されます。
ですから、最初の1文には、概要説明を記述する必要があります。
1文とは、最初に「.」や「。」が出現するまでです。
・1行で記述する場合 /** 説明文 **/ ・複数行で記述する場合 /********************************<pre> * 概要説明文。 * 詳細説明文 * 詳細説明文 </pre>*******************************/ |
コメントは、定義する前に記述します。 また、@で始まるdocタグを使って、引数や返却値の説明を付加します。 Javaのソースは、以下のような形式で記述します。
/********************************<pre> * クラスの概要説明。 * @see 参照クラス名 </pre>*******************************/ クラスの定義 /** フィールドの説明 **/ フィールドの定義 /********************************<pre> * メソッドやコンストラクタの説明。 * @param 引数の説明 * @return 返却値の説明 * @see 参照クラス名 * @exception 例外クラスの説明 </pre>*******************************/ メソッドやコンストラクタの定義 |
javadocを実行するとドキュメントを生成します。
形式 javadoc -オプション 引数 オプション -sourcepath ソースディレクトリ名 -encoding ソースのエンコーディング（ISO2022JP、EUCJIS、SJISなど） -d 生成するHTMLを出力するディレクトリ -docencoding 生成するHTMLのエンコーディング（ISO2022JP、EUCJIS、SJISなど） -charset 生成するHTMLのcharset（ISO-2022-JP、EUC-JP、Shift_JISなど） 引数 パッケージ名 パッケージ名を複数指定 ソースファイル名 ソースファイル名を複数指定 |
以下にjavadocコマンドの利用例を示します。
# javadoc -sourcepath src -d javadoc jp.ash.webapp |
Java版のメイクツールであるAntを使って、javadocを生成することもできます。 生成方法は、build.xmlに記述します。
| build.xml |
|---|
<project name="Build javadoc" default="all" basedir=".">
<!-- set property -->
<property file="build.properties" />
<property name="source" value="./src" />
<property name="javadoc" value="./javadoc" />
<property name="package" value="jp.ash.webapp" />
<target name="javadoc" />
<!-- make javadoc -->
<target name="javadoc">
<delete dir="${javadoc}" />
<mkdir dir="${javadoc}" />
<javadoc sourcepath="${source}" packagenames="${package}" destdir="${javadoc}" />
</target>
<!-- clean work file -->
<target name="clean">
<delete dir="${javadoc}" />
</target>
</project>
|
以下にjavadocの生成結果とそのサンプルソースを参照できます。