Javadoc 1.2 の新機能

このドキュメントでは、バージョン 1.1 から 1.2 への移行で Javadoc に対して行われた変更について説明します。内容は、ユーザーの役割に応じて、(1) ドキュメンテーションコメントの記述者に対するもの、(2) ドックレットを作成する開発者に対するもの (「アーキテクチャー」と「ドックレット API」)、(3) javadoc 生成 HTML ページの読者に対するもの (「内容」と「形式」) の 3 種類にわかれます。詳細については、このあとの「変更の詳細」で説明します。

変更のサマリー

このサマリーでは、ドキュメンテーションコメントの記述者向けの変更、Javadoc ツールに対する変更 (ドックレット API)、および Javadoc の HTML 出力の内容と形式に対する変更 (標準ドックレットの実装の場合) について説明します。

ドキュメンテーションコメントの記述

ドキュメンテーションコメントの記述に関する変更

ほかの項目で取り上げられている機能の中で、ドキュメンテーションコメントの記述方法に影響する変更点を次にまとめます。

アーキテクチャー

ドックレット API

内容

新しいタグ

提供する API 情報とリンクの拡充

カスタマイズ可能なタイトル、ヘッダー、フッター

FORMAT

イメージファイル

スタイルシート

ナビゲーション機能の向上

インデックス機能の向上

生成先ファイルの階層構造

全般

非互換性

その他のドックレット

1.2 以後の拡張機能の予定



変更の詳細

ここでは、Javadoc 1.1 から 1.2 へのバージョンアップで行われた変更について詳細に説明します。「対応済み」と記載されている項目は、バージョン 1.2 の Beta4 で実装されてテストされたものです。

ドキュメンテーションコメントの記述に関する変更

Javadoc 1.2 では、次のような要件と機能が新しく追加されており、ドキュメンテーションコメントを記述する際に注意が必要です。
各クラスの解説の最初の文は、要約文でなければなりません。
パッケージレベルのコメントを使用できるようになりました。
各パッケージの解説の最初の文は、要約文でなければなりません。
システム全体に対するコメントを使用できます。
Javadoc の新しいタグをドキュメンテーションコメントで使用できるようになりました。
イメージとサンプルを保持するための新しいディレクトリ doc-files がコピーされます。
生成先ファイルの階層構造
1.1 と 1.2 のドキュメンテーションコメントの間に互換性がない場合があります。

アーキテクチャー - ドックレット API

Javadoc に、ドックレットを記述できるドックレット API が追加されました。これは、Javadoc のアーキテクチャーに対する大きな変更です。Javadoc のドックレットを使うと、Javadoc の出力をカスタマイズできます。ドックレットは、テキスト変換のためのプラグインと考えることができます。ドックレットは、ドックレット API に対して記述するもので、Javadoc ツールによって生成される出力の内容と形式を指定します。HTML、SGML、XML、RTF、MIF など、任意の種類のテキストファイル出力を生成するためのドックレットを作成できます。HTML 形式の API ドキュメントを生成する「標準」ドックレットが、Sun から提供されています。さらに、ドックレットを使うと、API ドキュメントの生成とは関係のない特別な処理を行うこともできます。たとえば、すべてのメンバーにドキュメンテーションコメントがあることを検査する診断用ドックレットを作成できます。

新しいアーキテクチャーが採用された理由 - これまでの Javadoc (1.0.x と 1.1.x) では、入力として Java のソースファイルを使い、出力として HTML を生成します。HTML 出力の形式は、Java の中でハードコードされています。このようなアーキテクチャーの欠点は、ソースのライセンスを所有しており、非常に難解なコードを修正する意欲がないかぎり、出力をカスタマイズできないということです。つまり、単語の先頭文字の大文字化や色の変更やボールドの追加などの小さな修正であれ、MIF や RTF などの新しい形式への変換のような大きな修正であれ、テクニカルライターは必要な拡張を実施できないのです。

Javadoc のアーキテクチャー変更の要件は、次のようなものでした。

新しいアーキテクチャー:javadoc のフロントエンドは、コマンド行の引数を処理し、Java の構文解析と処理を行い、ルートデータ構造を構築して、それを Java の「ドックレット」に渡します。ドックレットは、パッケージ、クラス、メソッド、フィールド、コメント、およびこれらのオブジェクトの列挙を表す API を介して、このデータにアクセスします。この API に対して新しいドックレットを記述することも、標準ドックレットをサブクラス化して小さな変更を加えることも可能です。

内容 - 新しいタグ

ここで説明するタグは、実際には、標準ドックレットではなく、Javadoc API の中で実装されています。
新しいタグ @throws は、@exception と同義のタグです。「throws」は Java 言語のキーワードなので、わかりやすくなります。
既存のタグ @see が、パッケージ、HTML のアンカー、および引用符で囲まれた文字列を受け付けるようになりました。また、ラベルも指定できます。@see タグでは、クラス、メソッド、またはほかの API を参照する場合と同じように、パッケージを参照できます。HTML のアンカーは <a href="xxx">XXX</a> の形式で指定し、引用符で囲まれた文字列は "xxx" の形式で指定します。例については、Javadoc のリファレンスページを参照してください。ラベルは必要に応じて指定でき、形式は「@see 名前 ラベル」です。ラベルを指定した場合は、名前の代わりにラベルが表示されます。
新しいタグ {@link apiname label} は、テキストの中でのインラインリンクの指定に使います。旧バージョンの Javadoc の場合、API にリンクを含めるには、@see タグを使うか、HTML をハードコードするしか方法がありませんでした。この新しいインラインタグでは、@see で HTML リンクを生成するために使われているのと同じアルゴリズムが使われます。両者の違いは、「関連項目」見出しの下ではなく、インラインにリンクが置かれる点です。

内容 - 提供する API 情報とリンクの拡充

パッケージごとに、ドキュメンテーションコメント専用のファイル (名前は「package.html」) が 1 つ、ソースツリーに追加されるようになりました。各パッケージの解説の最初の文は、要約文です。Javadoc は、<body> と </body> の間にあるすべてのものを取り出して、パッケージのサマリーページ「package-summary.html」に追加します。このページには、クラスとインタフェースの一覧表も含まれています。Javadoc は、この最初の文を、概要ページである overview.html にコピーします。したがって、<body> と最初の文の間に、タイトルやほかのテキストを挿入することはできません。
パッケージレベルのコメントの概略は次のとおりです。
  • はじめに
  • パッケージの仕様
  • 関連項目

詳細は、「Package-Level Comments」を参照してください。

旧仕様: Javadoc 1.1 の場合、特定のパッケージに固有のコメントを記述することはできません。 - 上記の機能には、新しい Javadoc の規則に従う記述者が必要です。各パッケージの解説の最初の文は、要約文でなければなりません。
一式のパッケージに対して、システム全体を対象とする 1 つのドキュメント overview.html が追加されるようになりました。このファイルには、ドキュメント化されているすべてのパッケージに当てはまるコメントが入ります。たとえば、このページでは、「特に記載がないかぎり、null が渡されると常に NullPointerException がスローされる」などのような前提事項をドキュメント化できます。
このファイルはソースツリーに属し、任意のファイル名を指定できます。通常、overview.html という名前を使用します。Javadoc を実行するときに、コマンド行で -overview オプションにこのファイル名を指定すると、そのファイルの内容 (<body> タグと </body> タグの間) が、右側のフレームに表示される overview-summary.html という名前の初期ページ (Beta3 以前のバージョンでは packages.html という名前) に挿入されます。
旧仕様: Javadoc 1.1 の場合、すべてのパッケージに当てはまるコメントを記述することはできません。
Javadoc によって、各パッケージを 1 行で要約した最初の文が package.html から取り出され、packages.html に格納されるようになりました。これにより、全パッケージのリストに、各パッケージのサマリーが表示されます。
旧仕様: Javadoc 1.1 には、このようなサマリーリストはありません。
各クラスの解説の最初の文が取り出され、package-<class>.html のクラスのサマリーに格納されます。これにより、特定のパッケージについてすべてのクラスのサマリーが提供されます。
旧仕様: Javadoc 1.1 には、このようなサマリーリストはありません。 - 上記の機能には、新しい Javadoc の規則に従う記述者が必要です。各クラスの解説の最初の文は、要約文でなければなりません。
クラスおよびインタフェースのページ上のメソッドのサマリーとフィールドのサマリーに、継承された API が追加されました。
旧仕様: Javadoc 1.1 の場合、特定のクラスについて継承されたメンバーはそのクラスのページには表示されず、リンクをたどって調べる必要があります。
メソッドのサマリーのシグニチャーに、戻り値の型と、キーワード static、protected、および abstract が組み込まれるようになりました。これらの情報は、メソッドを呼び出す際に必要だからです。ただし、public、transient、volatile、または final は組み込まれません。これらは、ページのさらに下の詳細セクションに表示されます。フィールドのデータ型は組み込まれます。
旧仕様: Javadoc 1.1 の場合、メソッドのサマリーに戻り値の型は表示されません。また、フィールドのサマリーにフィールドのデータ型は表示されません。
インタフェースを実装するメンバーに「定義」が追加されました。
旧仕様: Javadoc 1.1 の場合、インタフェースを実装するクラスのメンバーにこのような項目は表示されません。
クラスページの先頭にサブクラスのリストが追加されました。また、インタフェースページの先頭に、サブインタフェースおよび実装するクラスが追加されました。
旧仕様: Javadoc 1.1 の場合、クラスページにサブクラスのリストは表示されません。
実装するメソッドにテキストが含まれていない場合にかぎり、インタフェースのメソッドからその実装するサブクラスに、自動的に解説がコピーされるようになりました。このとき、そのテキストがインタフェースからコピーされたことを示す同じ内容の文が組み込まれます。このような処理を行う理由は、インタフェースを実装する場合、インタフェースとクラスの両方でメソッドの解説がまったく同じであることが多いからです。手作業で記述をコピーするのは、維持管理が面倒で、無駄な作業です。
旧仕様: Javadoc 1.1 の場合、メソッドの解説はインタフェースからコピーされません。
パッケージごとのツリー表示が追加されました。パッケージまたはクラスを表示したときのツリー表示は、このツリー表示にリンクしており、そこからさらに全パッケージのツリーにリンクしています。
旧仕様: Javadoc 1.1 の場合、単一のパッケージについてのツリー表示 (クラス階層) はありません。唯一のツリー表示は全パッケージについてのもので、JDK の場合、これは巨大なツリーになります。
外部の Javadoc 生成ドキュメントにリンクするための -link オプションが導入されました。デフォルトでは、外部ドキュメントにはリンクされません。ドキュメントを生成する際に、-link オプションを指定すると、ドキュメント化している API から参照している API のドキュメントへのリンクが生成されます。リンクは、ローカルまたはリモート (インターネット上) のどちらも可能です。
旧仕様: Javadoc 1.1 の場合、生成しているドキュメントから外部へのリンクは作成されません。
Javadoc でドキュメント化するべきでないデフォルトのコンストラクタについて、バグを提出しました。 デフォルトのコンストラクタは、推奨されないものとして記載するか、バグと見なして、ドキュメントから除外する必要があります。
(Javadoc には影響なし)
旧仕様: Javadoc 1.1 の場合、アプリケーション開発者がそれを呼び出すかどうかにかかわらず、デフォルトのコンストラクタがすべて組み込まれるようになっています。デフォルトコンストラクタをドキュメント化するとき、解説は空白になります。
非推奨の API をすべて一覧表示する非推奨サマリーページが追加されました。(最終的には、置き換えられた API へのリンクが追加される予定です。)
旧仕様: Javadoc 1.1 の場合、非推奨の API のリストは生成されません。
非推奨のクラスに印が付けられるようになりました。
旧仕様: Javadoc 1.1 の場合、特定のパッケージのクラスリストで、非推奨のクラスにそれを示す印は付きません。
シグニチャーから synchronized と native が削除されました。Javadoc は API の仕様を生成します。これら 2 つのキーワードは、実装に固有のものなので、仕様のシグニチャーには含まれません。キーワード native は、ドキュメント化する必要がありません。キーワード synchronized は、スレッドに対して安全な動作を示しており、むしろメソッドの解説に記述するべきものです。スレッドに対して安全なメソッド自体が synchronized キーワードを使わない場合でも、そのような private メソッドを呼び出す場合があります。
旧仕様: Javadoc 1.1 の場合、キーワード synchronized と native が組み込まれます。
イメージとサンプルを保持するための doc-files ディレクトリが、各パッケージに 1 つずつコピーされるようになりました。Javadoc は、ソースツリーの各パッケージのディレクトリで「doc-files」という名前のディレクトリを探し、この名前のディレクトリとその内容をドキュメントの生成先にコピーします。「doc-files」内のファイルは、単に生成先にコピーされるだけで、Javadoc による処理は施されません。つまり、これらのファイルに標準のナビゲーションバー、ヘッダー、またはフッターを加えることはできません。またインデックスやツリーにこれらのファイルを加えることもできません。このディレクトリには、ドキュメンテーションコメントから参照する任意のファイルを置くことができます。例イメージ、HTML ファイル、テキストファイル、サンプルソースコード、複数のクラスで共有される HTML テーブルなど。
例:java.awt.Button クラスの解説の中にイメージファイル Button-1.gif への参照を組み込むには、次のようにします。
  • ソースツリーで、java/awt/ ディレクトリの下に doc-files という名前のディレクトリを作ります。
  • doc-files ディレクトリに Button-1.gif ファイルを置きます。
  • Button クラスのドキュメンテーションコメントに <img> タグを追加します。
       /**
        * <img src="doc-files/Button-1.gif">
        */
    
Java Software では、「-1」で始まり、それ以降のイメージに対しては数字を 1 ずつ増やしていく命名規則を採用しています。詳細は、「Including Images」を参照してください。
旧仕様: Javadoc 1.1 の場合、Javadoc を実行してもイメージが生成先にコピーされないので、リンクの壊れたファイルが生成されます。JDK の現状を見ると、このようなイメージの大部分は、AWT および Swing コンポーネントのスクリーンショットです。

内容 - カスタマイズ可能なタイトル、ヘッダー、フッター

先頭ページ packages.html にタイトルを組み入れるための -title オプションが追加されました。タイトルの例:Java Platform 1.2 Core API
旧仕様: Javadoc 1.1 の場合、生成ドキュメントにタイトルを追加する正規の方法はありません。
各ページにヘッダー、フッター、およびボトムノートを加えるための -header、-footer、-bottom の各オプションが追加されました。この機能を使うと、API のバージョン番号 (Java 1.2 Beta4 など) を各ページに出力して、ページを印刷したときに、生成元の API のバージョンを記録できます。「ボトムノート」機能を使うと、各ページの下端に、著作権表記やフィードバック用の電子メールリンクを追加できます。
旧仕様: Javadoc 1.1 の場合、デフォルトで各ページにバージョン番号を表示することはできません。

内容 - ソースファイルへのリンクを加えない

内部で行われる開発の場合、Javadoc で生成されるクラスページからソースコードに直接リンクされていると便利です。しかし、API ドキュメントを生成して公開する際、Java API のドキュメントに Java ソースコードへのリンクを組み込まないことが決まりました。したがって、標準ドックレットに対するこの機能の追加も、優先度が低くなりました。ただし、これとは別に、ソースコードへのリンクを生成するドックレットを利用できます。

形式 - イメージファイル

必須の GIF イメージがなくなりました。GIF イメージの丸印は、横罫線に置き換えられます。また、グラフィックイメージの見出し (「メソッド」、「フィールド」など) の代わりに、表の色付きのセルに見出しのテキストが配置されます。
旧仕様: Javadoc 1.1 の場合、丸印と見出しに GIF イメージが使われています。このような GIF イメージは必要ありません。GIF イメージを使うと、表示が遅くなり、ドキュメントの生成先にイメージを手作業でコピーする必要があります。

形式 - スタイルシート

色、フォント、および配置を制御するための HTML スタイルシートが追加されました。スタイルシートは、Web ページのテキストの色、フォント、および配置を実行時に設定する標準化された方法です。表のセルの色や左側のフレームに表示されるフォントのサイズを変更するには、javadoc が生成するファイル stylesheet.css を修正します。また、-stylesheetfile オプションを使うと、javadoc を実行するときに独自のスタイルシートを指定できます。
たとえば、見出しのセルの背景色を濃い青から白に変更するには、stylesheet.css ファイルを次のように編集します。
編集前:
   #TableHeadingColor     { background: #CCCCFF } /* Dark mauve */
編集後:
   #TableHeadingColor     { background: #FFFFFF } /* Dark mauve */

公式の解説については、W3C の Web ページ「Cascading Style Sheets」を参照してください。使用方法についての詳細な説明は、CNET の Web ページ「CSS Reference Table」を参照してください。概要説明を見る場合は、「CSS Reference Table」のページで「back to intro」をクリックしてください。

形式 - ナビゲーション機能の向上

パッケージ、クラス、およびメンバーのためのフレームが追加されました。フレームなしの場合は、package-summary.html から始まります。フレームありの場合は、overview-summary.html から始まります。
旧仕様: Javadoc 1.1 の場合、任意のパッケージ、クラス、またはメンバーにアクセスする簡単な方法はありません。さかのぼって自分で探す必要があります。
パッケージリストの上端 (左上のフレーム) に「すべてのクラス」リンクが追加されました。このリンクをクリックすると、アルファベット順に並んだすべてのクラスのリストが左下のフレームに表示されます。
旧仕様: Javadoc 1.1 の場合、パッケージの中にあるかどうかにかかわらず、任意のクラスにアクセスする簡単な方法はありません。「クラス階層」を表示する必要があります。クラスとインタフェースだけのリストがあると便利です。
すべての画面で使用できる単一のナビゲーションバーが用意されました。使用できない項目は淡色表示されます。
旧仕様: Javadoc 1.1 の場合、画面の上端に表示される標準のナビゲーションバーは、ページによって大きく異なります。全パッケージ用 (2 項目)、単独のパッケージ用 (3 項目)、クラス用 (6 項目) という 3 種類のナビゲーションバーがあります。
各サブセクションへ移動するための、別のナビゲーションバーが追加されました。
サマリー: 内部クラス | フィールド | コンストラクタ | メソッド       詳細: フィールド | コンストラクタ | メソッド
旧仕様: Javadoc 1.1 の場合、メンバーのサマリーと詳細を表示するには、クラスの解説をスクロールして先に進まなければなりません。
「API ユーザーズガイド」リンクは「ヘルプ」に名前が変更されました。デフォルトのヘルプファイルを生成するように、Javadoc が変更されました。必要に応じて「ヘルプ」リンクをナビゲーションバーから削除できるように、-nohelp オプションが追加されています。また、ファイルの作成を指定する -helpfile オプションが追加されています。
旧仕様: Javadoc 1.1 の場合は、「API ユーザーズガイド」というリンクが packages.html に作成されます。このリンクが指しているファイルは、ドキュメント生成先のディレクトリに自動的にはコピーされません。
Javadoc 1.2 でのメンバー用の HTML フレーム。標準ドックレットにこの機能を追加するかどうか検討されましたが、追加しないことになりました。サードパーティーの開発者が別個のドックレットでこの機能をリリースしたら、公表する予定です。

形式 - Web ページ

サマリーの表示が、枠と背景色のあるセルで構成される表に変わりました。 この表示方法の方が、クラスファイルのサマリー部分と詳細部分を簡単に区別できます。
旧仕様: Javadoc 1.1 の場合、サマリー部分と詳細部分の表示がよく似ているため、ページをスクロールダウンしたときにどちらの部分が表示されているかはっきりしません。
「インデックス」という名前は、ドキュメントの最後にあるアルファベット順の API リストのことを指します。パッケージごとのページの先頭部分の名前が、「パッケージのインデックス」から「パッケージのサマリー」に変更されました。同様に、クラスごとのページの先頭にある部分の名前が、「メソッドのインデックス」は「メソッドのサマリー」に、「コンストラクタのインデックス」は「コンストラクタのサマリー」に、「フィールドのインデックス」は「フィールドのサマリー」に、それぞれ変更されました。
旧仕様: Javadoc 1.1 の場合、「インデックス」という言葉が、クラスのページの先頭にあるサマリーと、全 API のアルファベット順のリストの両方について使われています。これは、不必要な混乱を招きます。

形式 - インデックス機能の向上

インデックスをアルファベットごとに別々のファイルに分割する -breakindex オプションが追加されました。
旧仕様: Javadoc 1.1 の場合、インデックスのファイルは JDK で 1.4M バイトという巨大なものになり、インターネット経由でロードするのに時間がかかりすぎます。
インデックスにクラスとインタフェースが追加されました。
旧仕様: Javadoc 1.1 の場合、インデックスにはコンストラクタとメンバーだけが表示され、クラスとインタフェースは含まれません。
インデックスが国際化され、Unicode 文字を利用できるようになりました。
旧仕様: Javadoc 1.1 の場合、インデックスで処理できる文字はアルファベットの A - Z だけです (実際は A - Y だけ)。

形式 - 生成先ファイルの階層構造

ドキュメント生成先のディレクトリに階層構造が追加されました。ソースコードのツリーを反映するように、サブパッケージごとに 1 つのディレクトリが作成されます。平坦なディレクトリ構造はサポートされなくなりました。パッケージ単位でファイルが分散されるので、各ディレクトリ内のファイル数が少なくなるという効果があります。また、パッケージ名がファイル名の一部ではなくディレクトリ名で表現されるため、ファイル名が短くなるという副次効果もあります。これにより、サードパーティーは、意味のある短い名前 (Macintosh 用の 31 文字の名前など) を簡単に生成できるようになります。
たとえば、java.awt.Button.html\java\awt\Button.html になります。1.2 での変更をすべて適用すると、java.applet パッケージに対して Javadoc を実行した場合、ドキュメント生成先ファイルの構造は、「生成されるファイルの構造」で説明されているとおりになります。
旧仕様: Javadoc 1.1 では平坦な構造が使われており、HTML ファイルはすべて 1 つのディレクトリに配置されます。

非互換性

1.1 と 1.2 のドキュメンテーションコメントの間に互換性がない場合があります。Javadoc 1.2 は、Javadoc の旧バージョン用に書かれたドキュメンテーションコメントとの互換性を考慮して作成されました。とはいえ、古いドキュメンテーションコメントを Javadoc 1.2 でコンパイルすると、それまでとは違う「動作」をする場合があります。
  • 多くのファイル名が変更されました。もっとも重要な変更は、生成ドキュメントの初期ページが、packages.html ではなく、index.html (HTML フレームを設定するファイル) になったことです。フレームを表示しない場合は、overview-summary.html を初期ページとしてロードします (このページは、1.1 での packages.html に当たる)。
  • コメントの記述者が、コメントのテキストの中に、API 名へのインラインリンクをハードコードしていた場合があります。javadoc が階層構造のディレクトリを生成するようになったため、このようなリンクは正しく機能しません。新しい {@link} タグを使えば、インラインリンクを正しく記述できます。

その他のドックレット

Javadoc 1.1 のドキュメント形式は、独自のドックレットとして残されています。このドックレットでは、古い表示形式と平坦なディレクトリ構造が使用されますが、バグの一部が新しく修正されています。Javadoc 1.1 形式を利用するには、javadoc の「-1.1」オプションを使います。
旧仕様: Javadoc 1.1 形式は、その形式の HTML 出力を処理する、その形式に依存したパーサーを開発したユーザーにとって重要です。
[今後] MIF のドックレットを実装します。 これにより、MIF 形式の出力を生成する機能が追加されて、FrameMaker にインポートできるようになります。
(1.2 以降に実施およびリリースされる予定。)
旧仕様: Javadoc 1.1 には MIF の出力機能はありません。ただし、Javadoc 1.0.2 にはあります。

将来の拡張機能 - 1.2 以降のリリース

単一の Javadoc 生成ドキュメントを作成するための、追加生成を可能にします。 Javadoc を実行するたびに中間形式を保存し、この中間形式をマージして、正確なインデックス、ツリー、クラス階層、サブクラスリストなどを備えた完全なドキュメントを生成できるようにします。
(未対応 - 1.2 よりあとのリリースで対応の予定)
旧仕様: Javadoc 1.1 の場合、ドキュメントの追加生成はできません。

Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.