TOP
＞
システム開発
＞ Javadocの特徴
Javadocから考える開発ドキュメンテーション
第１回：Javadoc、どのくらい活用していますか？
著者：
ウルシステムズ 足立 祐一
2007/8/17
前のページ
1
2
3
次のページ
Javadocの特徴
「Javadoc」というと、大抵2つの意味で使われます。ソースコード中のコメントで「/**」ではじまり「*/」で終わる形で書くものやその内容を指す場合があります。そしてもう1つは、それを基にしてHTML形式のドキュメントを生成するツールを指す場合です。
前者は「Javadocを書く」というときに相当します。つまり「/**」ではじまり「*/」で終わるコメントを記述することをいい、Java言語の構文としてはコメントの一種として扱われます。
後者は「Javadocを生成する」といったときに相当しますが、具体的には前述のドキュメンテーションコメントとソースコードを基にJavadocコマンドを使ってドキュメントを作成することを指しています。このコマンドはJava SE SDKに同梱されています。
このあたりは普段気にせず使っていますが、連載ではそれぞれを区別するために以下のように定義します。
ドキュメンテーションコメント
ソースコードに埋め込まれた「/**」ではじまって「*/」で終わるコメント
リファレンスドキュメント
ドキュメンテーションコメントとソースコードを基に生成されたドキュメント
Javadoc
リファレンスドキュメントを作るツール
表2：本連載での定義
Javadocは、ドキュメンテーションコメントとその直後に宣言されたクラスやメンバの宣言を解析してリファレンスドキュメントを生成します。ドキュメンテーションコメントはクラスやメンバの直前に書くため、クラスやメンバのリードコメント（冒頭の説明）として関連づけてJavadocに解釈されます。
つまり、Javadocは計算機に読ませるための部分と開発者に読んでもらう部分を持つJavaのソースコードから、開発者のためのドキュメントだけを取り出して見せるビューであるといえます(図1)。
図1：JavadocはJavaコードの人間向けのビュー
（画像をクリックすると別ウィンドウに拡大図を表示します）
ドキュメンテーションコメントの記述にはHTMLタグの一部を使い、表を書いたり文字を修飾することができます。また、HTMLタグとは別にJavadocが解釈して処理を行うjavadocタグ（注1）を使うことができます。javadocタグを使うことによって、関連するクラスやメンバへの参照や使用を推奨されない要素のマーキングなどが定義できます。
では、その内容にどのようなことが書けるのか、ソースコードやリファレンスドキュメント以外のドキュメントとの関連も含めてみていきましょう。
注1：
javadocタグ
http://java.sun.com/javase/ja/6/docs/ja/technotes/tools/windows/javadoc.html#tagsection
Javadocのドキュメンテーションコメントで書けること、書けないこと
Javadocでうれしい点は、クラスやメソッド、フィールドなどJava言語の構成要素とその説明が対応づけられていることです。図2のように、作る人はJavaソースコード中にコードとドキュメントの両方を同時に意識しながら作成でき、使う人（コンパイラと他の開発者）はそこから自分に適したところだけを抽出してみることができます。
図2：Javadocは設計書とソースコードを繋ぐ
特に他の開発者にとっては、概要をリファレンスドキュメントで調べて詳しくソースをみることや、逆にソースを理解するためにリファレンスをみることができる点がメリットです。例えば、Java SEやJava EEのクラスライブラリ・リファレンスは、Javadocをどう書いたらよいかについてお手本になる非常に優れたものです。
ライブラリの作成とその活用という観点ではソースコードとその説明がリンクしていることで十分ですが、システム開発の現場はそれだけでは足りない面があります。それでは、Javadocには何が足りないのでしょうか。システム開発の視点に少し立ち戻って考えてみます。
前のページ
1
2
3
次のページ
著者プロフィール
ウルシステムズ株式会社 足立 祐一
コンサルタント
Javaを中心にアーキテクチャ設計〜アプリケーション開発に従事し、製造業界、金融業界のSIerを経て現職。新しい技術、古い技術を駆使し、お客様の課題をITによって解決できるシステムを提供すべく、日々奮闘中。
INDEX
第1回：Javadoc、どのくらい活用していますか？
Java開発に役立つ「Javadoc」
Javadocの特徴
2つの視点からみるJavadocの足りない点
