|
|
Javadoc 1.2 の新機能 |
Javadoc に施された機能強化 |
このドキュメントでは、バージョン 1.1 から 1.2 へのアップグレードで Javadoc に対して行われた変更について説明します。 内容は、ユーザの役割に応じて、 (1) ドキュメンテーションコメントの記述者に対するもの、(2) ドックレットを作成する開発者に対するもの (「アーキテクチャ」と「ドックレット API」)、(3) javadoc 生成 HTML ページの読者に対するもの (「内容」と「形式」) の 3 種類に分かれます。 詳細については、このあとの「変更の詳細」で説明します。
変更の概要この概要では、ドキュメンテーションコメントの記述者向けの変更、Javadoc ツールに対する変更 (ドックレット API)、および Javadoc の HTML 出力の内容と形式に対する変更 (標準ドックレットの実装の場合) について説明します。
|
- 各クラスの解説の最初の文は、要約文でなければなりません。
- パッケージレベルのコメントを使用できるようになりました。
- 各パッケージの解説の最初の文は、要約文でなければなりません。
- システム全体に対するコメントを使用できます。
- Javadoc の新しいタグをドキュメンテーションコメントで使用できるようになりました。
- イメージとサンプルを保持するための新しいディレクトリ doc-files がコピーされます。
- 階層構造のファイルが生成されます。
- 1.1 と 1.2 のドキュメンテーションコメントの間に互換性がない場合があります。
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 に対して新しいドックレットを記述することも、標準ドックレットをサブクラス化して小さな変更を加えることも可能です。
- 入力ソースの構文解析と処理に使われる機構を、出力形式の仕様から切り離す
- 出力形式の仕様をプラグイン可能にする
- 出力形式の仕様を、テクニカルライターの要求にできるかぎり幅広く対応できるようにする
- 新しいタグ @throws は、@exception と同義のタグです。 「throws」は Java 言語のキーワードなので、わかりやすくなります。
- 既存のタグ @see が、パッケージ、HTML のアンカー、および引用符で囲まれた文字列を受け付けるようになりました。 また、ラベルも指定できます。 @see タグでは、クラス、メソッド、またはほかの API を参照する場合と同じように、パッケージを参照できます。 HTML のアンカーは「
<a href="xxx">XXX</a>」の形式で指定し、引用符で囲まれた文字列は「"xxx"」の形式で指定します。 例として、Javadoc のリファレンスページを参照してください。 ラベルは必要に応じて指定でき、形式は「@see 名前 ラベル」です。 "@see瀟ame瀝abel". ラベルを指定した場合は、名前の代わりにラベルが表示されます。
- 新しいタグ {@link apiname label} は、テキストの中でのインラインリンクの指定に使います。旧バージョンの Javadoc の場合、API にリンクを含めるには、@see タグを使うか、HTML をハードコードするしか方法がありませんでした。 この新しいインラインタグでは、@see で HTML リンクを生成するために使われているのと同じアルゴリズムが使われます。 両者の違いは、[関連項目] 見出しの下ではなく、インラインにリンクが置かれる点です。
- パッケージごとに、ドキュメンテーションコメント専用のファイル (名前は「package.html」) が 1 つ、ソースツリーに追加されるようになりました。各パッケージの解説の最初の文は、要約文です。 Javadoc は、<body> と </body> の間にあるすべてのものを取り出して、パッケージの概要ページ package-summary.html に追加します。このページには、クラスとインタフェースの一覧表も含まれています。 Javadoc は、この最初の文を、概要ページである overview.html にコピーします。 したがって、<body> と最初の文の間に、タイトルやほかのテキストを挿入することはできません。
パッケージレベルのコメントの概略は次のとおりです。
- はじめに
- パッケージの仕様
- 関連ドキュメント
詳細については、「Package-Level Doc 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 の場合、すべてのパッケージに当てはまるコメントを記述することはできません。
- 各パッケージを 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 ディレクトリ内のファイルは、単に生成先にコピーされるだけで、処理は施されません。 つまり、これらのファイルに標準のナビゲーションバー、ヘッダ、またはフッタを加えることはできません。またインデックスやツリーにこれらのファイルを加えることもできません。 このディレクトリには、ドキュメンテーションコメントから参照する任意のファイルを置くことができます。 例: イメージ、HTML ファイル、テキストファイル、サンプルソースコード、複数のクラスで共有される HTML テーブルなどを格納できます。
例: java.awt.Button クラスの解説の中にイメージファイル Button-1.gif への参照を組み込むには、次のようにします。
Java ソフトウェアでは、「-1」で始まり、それ以降のイメージに対しては数字を 1 ずつ増やしていく命名規則を採用しています。 詳細については、「Including Images」を参照してください。
- ソースツリーで、java/awt/ ディレクトリの下に doc-files という名前のディレクトリを作ります。
- doc-files ディレクトリに Button-1.gif ファイルを置きます。
- Button クラスのドキュメンテーションコメントに <img> タグを追加します。
/** * <img src="doc-files/Button-1.gif"> */- 旧仕様: 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 フレーム。標準ドックレットにこの機能を追加するかどうか検討されましたが、追加しないことになりました。 サードパーティの開発者が別個のドックレットでこの機能をリリースしたら、公表する予定です。
- 概要の表示が、枠と背景色のあるセルで構成される表に変わりました。この表示方法のほうが、クラスファイルの概要部分と詳細部分を簡単に区別できます。
- 旧仕様: 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 にはあります。
- 単一の Javadoc 生成ドキュメントを作成するための、追加生成を可能にします。Javadoc を実行するたびに中間形式を保存し、この中間形式をマージして、正確なインデックス、ツリー、クラス階層、サブクラスリストなどを備えた完全なドキュメントを生成できるようにします。
(未対応 - 1.2 よりあとのリリースで対応の予定)- 旧仕様: Javadoc 1.1 の場合、ドキュメントの追加生成はできません。
|
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. |
 Java ソフトウェア |
コメントの送付先: javadoc-tool@sun.com