|
|
Javadoc 1.2 の新機能 |
Javadoc に施された機能強化 |
このドキュメントでは、バージョン 1.1 から 1.2 への移行で Javadoc に対して行われた変更について説明します。内容は、ユーザの役割に応じて、(1) doc コメントの記述者に対するもの、(2) ドックレットを作成する開発者に対するもの (「アーキテクチャ」と「ドックレット API」)、(3) javadoc 生成 HTML ページの読者に対するもの (「内容」と「フォーマット」) の 3 種類に分かれます。詳細については、後述の「変更の詳細」で説明します。
変更の概要この概要では、doc コメントの記述者向けの変更、Javadoc ツールに対する変更 (ドックレット API)、および Javadoc の HTML 出力の内容とフォーマットに対する変更 (標準ドックレットでの実装として) について説明します。
|
- つまり、各クラスの解説の最初の文は、要約文でなければなりません。
- パッケージレベルのコメントを使用できます。
- つまり、各パッケージの解説の最初の文は、要約文でなければなりません。
- システム全体に対するコメントを使用できます。
- Javadoc の新しいタグを doc コメントで使用できます。
- イメージとサンプルを保持するための新しいディレクトリ doc-files をコピーします。
- 階層構造のファイルを生成します。
- 1.1 と 1.2 の doc コメントの間に互換性がない場合があります。
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 名前 ラベル」です。ラベルを指定した場合は、名前の代わりにラベルが表示されます。
- 新しいタグ {@link apiname label} は、テキストの中でのインラインリンクの指定に使います。旧バージョンの Javadoc の場合、API にリンクを含めるには、@see タグを使うか HTML をハードコードするしか方法がありませんでした。この新しいインラインタグでは、@see で HTML リンクを生成するために使われているものと同じアルゴリズムが使われています。ただし、「関連項目」見出しの下ではなく行の中にリンクが置かれる点が異なります。
- パッケージごとに、doc コメント専用のファイル (名前は 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 のクラス概要に格納されます。各クラスの解説の最初の文が取り出され、package-
.html のクラス概要に格納されます。 - 旧仕様: Javadoc 1.1 の場合、このような概要リストの機能はありません。
注 - この機能を使う場合は、新しい Javadoc の規則に従う必要があります。つまり、各クラスの解説の最初の文は、要約文でなければなりません。
- クラスとインタフェースのページのメソッドとフィールドの概要に、継承される API が追加されます。
- 旧仕様: Javadoc 1.1 の場合、特定のクラスについて継承されるメンバはクラスのページに表示されず、リンクをたどって調べる必要があります。
- メソッド概要のシグニチャーに、戻り値の型とキーワード static、protected、および abstract が追加されます。 これは、メソッドを呼び出す際に必要なためです。public、transient、volatile、または final は含まれません。 これらは、ページのさらに下の詳細セクションに表示されます。フィールドのデータ型は含まれます。
- 旧仕様: Javadoc 1.1 の場合、メソッドの概要に戻り値の型は表示されません。また、フィールドの概要にフィールドのデータ型は表示されません。
- インタフェースを実装するメンバに「Specified by」が追加されます。
- 旧仕様: Javadoc 1.1 の場合、インタフェースを実装するクラスのメンバにこのような項目は表示されません。
- クラスページの先頭にサブクラスのリストが追加されます。また、インタフェースページの先頭には、サブインタフェースおよび実装するクラスが追加されます。
- 旧仕様: Javadoc 1.1 の場合、クラスページにサブクラスのリストは表示されません。
- 実装するメソッドにテキストが含まれない場合に限り、インタフェースのメソッドからその実装するサブクラスに、自動的に解説がコピーされます。テキストがインタフェースからコピーされたことを示す同じ内容の文が追加されます。このような処理を行う理由は、インタフェースを実装する場合、インタフェースとクラスの両方でメソッドの解説がまったく同じことがよくあるためです。手作業で記述をコピーするのは、管理が面倒で無駄な作業であると考えられます。
- 旧仕様: Javadoc 1.1 の場合、メソッドの解説はインタフェースからコピーされません。
- パッケージごとのツリー表示が追加されます。パッケージまたはクラスを表示したときの Tree はこのツリー表示にリンクしており、ツリー表示には全パッケージのツリーへのリンクがあります。
- 旧仕様: Javadoc 1.1 の場合、単一のパッケージについてのツリー表示 (クラス階層) はありません。唯一のツリー表示は全パッケージについてのもので、JDK の場合、これがツリー表示の大部分を占めます。
- 外部の Javadoc 生成ドキュメントにリンクするための -link オプションが導入されます。デフォルトでは、外部ドキュメントにはリンクされません。doc を生成する際に、-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 キーワードを使わない場合でも、そのようなプライベートメソッドを呼び出す場合があります。
- 旧仕様: Javadoc 1.1 の場合、キーワード synchronized と native が含まれています。
- イメージとサンプルを保持するための doc-files ディレクトリが、パッケージごと 1 つコピーされます。Javadoc は、ソースツリーの各パッケージのディレクトリで doc-files という名前のディレクトリを探し、この名前のディレクトリとその内容をドキュメントの生成先にコピーします。doc-files の中のファイルは、単に生成先にコピーされるだけで、処理はされません。つまり、これらのファイルに標準のナビゲーションバー、ヘッダ、またはフッタを加えることはできず、インデックスやツリーにこれらのファイルを加えることもできません。このディレクトリには、doc コメントで参照する任意のファイルを置くことができます。例: イメージ、HTML ファイル、テキストファイル、サンプルソースコード、複数のクラスで共有される HTML テーブルなどを格納できます。
例: java.awt.Button クラスの解説の中にイメージファイル Button-1.gif への参照を加えるには、次のようにします。
「-1」で始まり、以降のイメージに対しては数字を 1 ずつ増やしていく命名規則が採用されています。詳細については、「Including Images」を参照してください。
- ソースツリーで、java/awt/ ディレクトリの下に doc-files という名前のディレクトリを作ります。
- doc-files ディレクトリに Button-1.gif ファイルを置きます。
- Button クラスの doc コメントに <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 の doc コメントの間に互換性がない場合があります。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 出力を処理し、その形式に依存するパーサの場合、Javadoc 1.1 の形式が必要です。
- [今後] MIF のドックレットを実装します。これにより、MIF 形式の出力を生成する機能が追加されて、FrameMaker にインポートできるようになります。
(1.2 以降に実施およびリリースされる予定)- 旧仕様: Javadoc 1.1 には MIF の出力機能はありません。 ただし Javadoc 1.0.2 にはあります。
コメントの送付先: javadoc-tool@sun.com
- 1 つの Javadoc 生成ドキュメントに対して追加生成できるようにします。Javadoc を実行するたびに中間形式を保存し、この中間形式をマージして、正確なインデックス、ツリー、クラス階層、サブクラスリストなどを備えた完全なドキュメントを生成できるようにします。
(未対応 - 1.2 のリリースで対応の予定)- 旧仕様: Javadoc 1.1 の場合、ドキュメントの追加生成はできません。