バーではマスターのお任せで今の自分にあったカクテルを出してもらう、というのが粋ですね。 そのためもあるのでしょう、バーにはメニューがないことが多いです。 お金を気にしながら飲むなんてのは野暮ったいですからね。 相場を知っておいてある程度余裕を持って望むのがよいでしょう。

今回はドキュメントの話。Javaにはjavadocと呼ばれるものがあります。 たとえば、Sun公式のJavaのAPIリファレンス。 ところが、Sun公式でなくともこのスタイルのドキュメントが非常に多いのです。 ApacheなどのオープンソースのAPIなどもこのスタイルになっています。なぜでしょう？

実はjavadocというのは「ドキュメント生成ツール」の名前なのですね。 詳しい説明はこちらですが つまるところ、ソースコード中に/** ～ */形式で記述したコメントを元にあのお馴染みのリファレンスを 自動で生成してくれるわけです。

このjavadocコマンド、JDKをインストールすればもれなく付いてきます。 いろんなところのAPIリファレンスが似たようなスタイルなのはみんなこのjavadocを使ってドキュメント生成しているからなんですね。

パッケージのドキュメント

各クラスのドキュメントはそれぞれのクラスの/** ～ */の記述を元に生成されます。 しかし、javadocにはパッケージのドキュメントのページが存在します。 これはどうやって生成するのでしょう？

JDK1.4までの場合はパッケージにpackage.htmlという名前のHTMLファイルを作成しておくと これを元にjavadocのパッケージの説明ページが生成されます。
JDK1.5以降ではpackage-info.javaというjavaファイルを作り、ここに/** ～ */形式で記述するようになりました。 これはパッケージ全体に対するアノテーションの利用のための拡張が関係しています。

また、パッケージのルートにoverview.htmlを置いておくと、概観ページを作ることもできます。 これらのドキュメントを整備しておくと、中途でプロジェクトに参加する人が概観をつかみやすくなります。