Javadocに標準でないタグを無視させる

アノテーション使うとJavadocが大量に警告を吐く問題の対処法を見つけた。覚え書き。

XDocletやらEJBGenやらDbCやら、Javadocに特殊なタグを書き込むことでいろんなパラメータを設定し、ソースコードの自動生成やらを行うというテクがすでに一般化している。特にXDoclet無しでEJBを作るというのはもはや考えられない。Remoteインタフェースやらをガリガリ手書きする時代はとうの昔に終焉を迎えている。以下はXDocletのサイトからもってきた例。

/**
 * This is the Account entity bean. It is an example of how to use the
 * EJBDoclet tags.
 *
 * @see Customer
 *
 * @ejb.bean
 *     name="bank/Account"
 *     type="CMP"
 *     jndi-name="ejb/bank/Account"
 *     local-jndi-name="ejb/bank/LocalAccount"
 *     primkey-field="id"
 *
 * @ejb.finder
 *     signature="java.util.Collection findAll()"
 *     unchecked="true"
 *
 * @ejb.transaction
 *     type="Required"
 *
 * @ejb.interface
 *     remote-class="test.interfaces.Account"
 *
 * @ejb.value-object
 *     match="*"
 *
 * @version 1.5
 */

ところが、ここで一つ問題がある。先ほどあげたツールが要求するタグ（@ejb.beanとか）は、Javadocからすれば未知のタグである。そのため、ドキュメントを生成する際に「そんな腐れタグなんぞ知らねーよ、ぺっ！」といった警告を大量にはき出してくれる（本当はもうちょっと柔らかいメッセージです）。エラーではなく警告なので、ドキュメント自体は作成されるのだが、やはり気持ちが悪い。Javadocを使ってドキュメントを作る際は、標準タグ以外は無視するようにしたい。

これは、Javadocのオプションに-tagを使用することで実現できる。本来は、カスタムタグの設定につかうオプションだ。

tagオプションを、次のように使用する。

javadoc -tag ejb.bean:X

これは@ejb.beanにパラメータXを与える（Xは無効を意味する）、という記述である。これで、@ejb.beanは無効化される。このオプションを、無効にしたタグの数だけ書けばよいのである。

javadoc -tag ejb.bean:X -tag ejb.persistence:X -tag ejb.finder:X ...

しかし、これではセパレータであるコロン（:）をタグ名に含めることができない。そこで、JDK1.4からダッシュ（-）もセパレータとして使えるようになっている。たとえば、コロンを含むタグ@ejb:beanを無効化するには、次のようにする。

javadoc -tag ejb:bean-X

これがまずい。名称にダッシュ（ハイフン）を含むタグを無効化しようとすると・・・。

javadoc -tag ejb.value-object:X

本当は@ejb.value-objectを無効にしたいのに、これが@ejb.valueというタグに与えるパラメータがobject:Xである、と解釈されてしまう。このせいで、名称にハイフンを含むタグは無効化できない。これを回避する方法はカスタムタグレットを作る以外に無い。

ところが、俺とおなじ目に遭った人がたくさんいたようで、JDK1.5で修正された。再びセパレータにダッシュを使うことができなくなり、代わりにタグ名にコロンを使いたい場合はバックスラッシュ（\）でエスケープすることとなった。

javadoc -tag ejb\:bean:X

これにより、名前にハイフンが使われていても問題なく無効化できるようになった。つまり、JDK1.5のjavadocコマンドを使うようにすれば問題解決である。

ところで、今時javadocコマンドを直接叩く物好きもそうはいまい。おそらく、Apache Antを利用することだろう。

1.6.3以降のantであれば、javadocタスクにexecutableパラメータを与えることができる。こいつで使用するjavadocコマンドを設定できるのだ。よって、開発にはJDK1.4を使っているんだが・・・という環境でも安心。javadocタスクにだけ1.5を使わせることができる。

<javadoc executable="C:/Program Files/Java/JDK1.5.0_06/bin/javadoc.exe">

そして、-tagオプション相当のタスク<tag>を食わせれば良い。

<javadoc executable="C:/Program Files/Java/JDK1.5.0_06/bin/javadoc.exe">
  <tag name="ejb.bean" enabled="false">
  <tag name="ejb.persistence" enabled="false">
  <tag name="ejb.finder" enabled="false">
  ...
</javadoc>

tagタスクを大量に書くのが面倒な場合は、dir属性を使う。

<javadoc executable="C:/Program Files/Java/JDK1.5.0_06/bin/javadoc.exe">
  <tag dir="${resource.dir}">
    <include name="javadoc_tag_def.txt">
  </tag>
</javadoc></code>

dir属性を与えると、tagタスクはfilesetと同じ扱いになる。その中で、-tagに引き渡すパラメータを書き込んだファイルを参照させる。ここでは${resource.dir}/javadoc_tag_def.txtである（filesetなので、当然複数のファイルを設定することも可能）。この中身は次のようになっている。

ejb.bean:X
ejb.finder:X
ejb.value-object:X

たくさん書くのは同じだが、タグを書くよりはこのほうが簡単だ。なにより、外に切り出せるのが良い。