Docletにさわる

作成 2002/11/27 更新 2002/11/28 使ってる人がいて、面白そうなので調べてみました。 ●JavaDoc ●Doclet ●Taglet

Doclet

Docletって？

DocletはJavaDoc作成に使用されるプログラムです。普通にjavadocした場合はSunの標準Docletが使われますが、 -docletオプションに自分で作ったDocletを渡すことで、 JavaDocの表示形式をカスタマイズできます。単にJavaDocの表示形式をカスタマイズしたいのであれば、標準Docletのソースに手を加えるのがいいらしいです (JavaDoc作るのって複雑なので)。 Doclet作成にはDocletAPIを使います。 JavaDocコメントに関するリフレクションAPIみたいな感じです。独自DocletはJavaDoc出力以外にも、コーディングルールチェックやメソッド数計算(?)などいろいろ使い道はあるようです。参考文献は、とりあえずJDKドキュメントに説明が載ってました。辿り順‥SDKのツール->Javadoc(Win32)->Javadocのドクレット->Javadocのドクレット

作ってみる

とりあえずドキュメントのサンプルを見ながら作ってみました。 MyDoclet.java(Docletサンプル) MyClass.java(javadocにかけるクラスサンプル) Docletクラスは特に何かを継承するってわけでもなく、

    public static boolean start(RootDoc root) {
 //...

というメソッドがあればいいみたいです。このメソッドがDoclet実行のエントリーポイントになります。

コンパイル

Docletクラスのコンパイル、実行にはtools.jarをクラスパスに含める必要があります。

実行

DOSコマンドプロンプトでの実行例

javadoc -doclet hoge.MyDoclet -docletpath classes 
-classpath classes;%JAVA_HOME%\lib\tools.jar -sourcepath src -private aaa

(実際は1行で記述) hoge.MyDocletドクレットを使ってaaa.MyClassをjavadocしています。 Docletクラスは -docletpathオプションでドクレットクラスパスに含める必要があります(クラスパスじゃダメ)。

実行結果

C:\apps\eclipse\workspace\doclet01>javadoc -doclet hoge.MyDoclet -docletpath clsses -classpath classes;C:\apps\j2sdk1.4.0_01\lib\tools.jar -sourcepath src -private aaa
パッケージ aaa のソースファイルを読み込んでいます...
Javadoc 情報を構築しています...
[MyClass]
クラスだ
@author:Muimin
[aaa]
フィールドだ
[hoge]
メソッドだ
@hoge:p1 ほげぇ
@return:かえり血
@param:p1 パラメタ

何作るって明確な目標もないので、とりあえずこんなもん。

Taglet

Tagletとは？

Tagletは(標準Docletで普通に)JavaDocするとき、新たなTagをJavaDocに表示するのに使います。 JavaDocのカスタマイズで最もありそうなものは独自タグの追加なので、それに簡単に対応するために作られた仕組みです(たぶん)。 Docletの説明と一緒にのってたので、ちょっとだけ使ってみました。

作ってみる

ROSEの@roseidをJavaDocで表示してみます (そういうの既に提供されてそうですが、まあ、簡単な実験として作ってみました。ほとんどJDKサンプルまま)。 RoseIdTaglet.java(Tagletサンプル) MyClass2.java(Tagletにかけるクラスサンプル)

実行

標準Tagletを使うので、tools.jarをクラスパスに含める必要はないようです。 -tagletと-tagletpathオプションを指定します。

javadoc -d doc -taglet hoge.RoseIdTaglet -tagletpath classes 
-classpath classes;%JAVA_HOME%\lib\tools.jar -sourcepath src aaa

実行結果

こんな感じ(MyClass2.html)のJavaDoc が出来ました。とても簡単ですね。 Tagletの導入バージョンがJDK1.4と書いてるので、昔のJDKでは使えないかな。なお、上記と同じことは-tagオプション(-tag roseid:a:"roseid:") で可能なので、Tagletはもうちょっと凝りたいときに使うのだろうと思われます。

TOP