作成 2002/11/27
更新 2002/11/28
使ってる人がいて、面白そうなので調べてみました。
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は(標準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はもうちょっと凝りたいときに使うのだろうと思われます。