2つの視点からみるJavadocの足りない点

2つの視点からみるJavadocの足りない点

図3にシステム開発の流れとドキュメントを示しました。

図3：開発に必要なドキュメントをJavadocで繋げられるか
（画像をクリックすると別ウィンドウに拡大図を表示します）

Javadocに足りないもの、それは「何を作れば正しいのか」を示すところです。これには2つの視点があります。

まず1つは「どんなシステムを作るのか」ということを示すもので、仕様書やビジネスルールがそれにあたります。仕様書がなければソースコードが妥当な作りになっているのか判断できません。

もう1つは「作成したシステムをどのように検証するのか」を定めるもので、テストコードがそれに当たります。

開発のドキュメントを考えると、これら2つの関係を避けては通れません。これらのドキュメントに対しても、Javadocが実現しているように、相互の参照がとれるようになれば非常に効率が上がるのではないでしょうか。

どのクラスが仕様書のどこに対応していて、それはテストでどのように検証されるのかが明確になっていれば、問題発生時の対応はもちろん仕様の変更に素早く対応することが可能になります。残念ながら、Javadocにはここまでの対応付けの機能は備わっていません。

でも、あきらめるのはまだ早いのです。なぜなら、拡張機能を用いればこれらの点でもJavadocを活かすことができるのです。

Javadocは拡張できる

Javadocは「Doclet」と「Taglet」という2つの機能を使って実現されています。この機能にはAPIが用意されており、それぞれ拡張することができます。以下ではこれらの役割を解説し、これらのAPIを利用したツールを紹介します。

Doclet

Docletは、Doclet APIを使用してJavadocで処理する内容と出力形式を指定するものです。JavadocはデフォルトでドキュメンテーションコメントをHTML形式で出力する「標準Doclet」を使用します。

独自のDocletを作成して、HTML以外のリファレンスドキュメントを生成することはもちろん、まったく別のドキュメントを生成するといった使い方もできます。

Taglet

Tagletは、Doclet内で一部の振舞いを変えるものです。指定したクラスやメンバへのリンクの生成などもこの機能で実現されています。Taglet APIを実装して、javadocタグをオーバーライドしたり、独自のタグを定義することができます。

XDoclet

これらのAPIを使用したツールの1つに「XDoclet」があります。

このツールは、ドキュメンテーションコメントから設定ファイルやスケルトンコードなど、リファレンスドキュメント以外のファイルを自動生成することを目的としています。

ドキュメンテーションコメントにjavadocタグだけでなくXDoclet独自のタグを追加して実現しています。XDocletという名称は、これらの独自タグの解釈と独自Docletでファイル出力処理を行うツールの総称です。有名なものに「EJBDoclet」や「WebDoclet」などが あります。それぞれEJBの設定ファイルや、web.xmlファイルを生成します。

なお最近では、これらXDocletの一部の機能はJava SE 5から追加されたアノテーション機能（注2）で同様のことができるようになりました。

しかし、XDocletの一部はアノテーションに取って代わられたもののJavadocの拡張性が無用になったわけではありません。むしろドキュメント本来の目的に活用できる可能性を示唆してくれているのです。

次回は

今回は、開発現場から見たJavadocのいまいちな現状にフォーカスをあて、開発に必要なドキュメントの全体感からJavadoc（ドキュメンテーションコメント）の位置づけを再確認しました。

次回以降は、Javadocの拡張機能を活用する方法について解説していきます。