Javadocの特徴

Javadocの特徴

「Javadoc」というと、大抵2つの意味で使われます。ソースコード中のコメントで「/**」ではじまり「*/」で終わる形で書くものやその内容を指す場合があります。そしてもう1つは、それを基にしてHTML形式のドキュメントを生成するツールを指す場合です。

前者は「Javadocを書く」というときに相当します。つまり「/**」ではじまり「*/」で終わるコメントを記述することをいい、Java言語の構文としてはコメントの一種として扱われます。

後者は「Javadocを生成する」といったときに相当しますが、具体的には前述のドキュメンテーションコメントとソースコードを基に Javadocコマンドを使ってドキュメントを作成することを指しています。このコマンドはJava SE SDKに同梱されています。

このあたりは普段気にせず使っていますが、連載ではそれぞれを区別するために以下のように定義します。

Javadocは、ドキュメンテーションコメントとその直後に宣言されたクラスやメンバの宣言を解析してリファレンスドキュメントを生成します。ドキュメンテーションコメントはクラスやメンバの直前に書くため、クラスやメンバのリードコメント（冒頭の説明）として関連づけてJavadocに解釈され ます。

つまり、Javadocは計算機に読ませるための部分と開発者に読んでもらう部分を持つJavaのソースコードから、開発者のためのドキュメントだけを取り出して見せるビューであるといえます(図1)。

図1：JavadocはJavaコードの人間向けのビュー
（画像をクリックすると別ウィンドウに拡大図を表示します）

ドキュメンテーションコメントの記述にはHTMLタグの一部を使い、表を書いたり文字を修飾することができます。また、HTMLタグとは別に Javadocが解釈して処理を行うjavadocタグ（注1）を使うことができます。javadocタグを使うことによって、関連するクラスやメンバへ の参照や使用を推奨されない要素のマーキングなどが定義できます。

では、その内容にどのようなことが書けるのか、ソースコードやリファレンスドキュメント以外のドキュメントとの関連も含めてみていきましょう。

Javadocのドキュメンテーションコメントで書けること、書けないこと

Javadocでうれしい点は、クラスやメソッド、フィールドなどJava言語の構成要素とその説明が対応づけられていることです。図2のように、 作る人はJavaソースコード中にコードとドキュメントの両方を同時に意識しながら作成でき、使う人（コンパイラと他の開発者）はそこから自分に適したと ころだけを抽出してみることができます。

図2：Javadocは設計書とソースコードを繋ぐ

特に他の開発者にとっては、概要をリファレンスドキュメントで調べて詳しくソースをみることや、逆にソースを理解するためにリファレンスをみることができる点がメリットです。例えば、Java SEやJava EEのクラスライブラリ・リファレンスは、Javadocをどう書いたらよいかについてお手本になる非常に優れたものです。

ライブラリの作成とその活用という観点ではソースコードとその説明がリンクしていることで十分ですが、システム開発の現場はそれだけでは足りない面があります。それでは、Javadocには何が足りないのでしょうか。システム開発の視点に少し立ち戻って考えてみます。