Javadoc 1.4 の新機能

このドキュメントでは、バージョン 1.3 から 1.4 への移行で Javadoc ツールに対して行われた変更について説明します。また、未解決のバグと主要なバグ修正の簡易版リストについては、重要な新しいバグとリグレッションの説明を参照してください。

新規タグおよびオプションのサマリー

このサマリーでは、新しいタグおよびオプションについて簡単に説明します。新規タグ
{@linkplain}{@inheritDoc}@serial{@value}

新規オプション
-breakiterator、-docfilessubdirs、-exclude、-excludedocfilessubdir、-nocomment、-noqualifier、-quiet、-source、-linksource、-subpackages、-tag、-taglet

互換性に関する問題

次の変更点は、既存のドキュメンテーションコメントの解釈や表示に影響を及ぼす可能性があります。

Javadoc の実行

コマンド行オプション、エラー、および警告に影響を及ぼす変更点について説明します。 1 つのパッケージルートを渡すことによりすべてのサブパッケージを再帰的に処理する -subpackages オプションを追加- -exclude オプションは、その前後の -subpackages コマンド行のフラグに含まれている場合でも、ドキュメント生成するパッケージのリストからパッケージを無条件に排除します。たとえば、-subpackages java -exclude java.lang.ref には java.io、java.util、java.lang などが含まれますが、java.lang.ref は含まれません。(4074234)

アサーションに -source 1.4 オプションを追加 - このオプションは、javac -source 1.4 を使用してコンパイルされたコードをドキュメント化します。これはアサーションを含むコードでは必須です。 (4400430)

Java 内から Javadoc ツールを呼び出す public メソッドを追加 - com.sun.tools.javadoc.Main にある Javadoc ツールにプログラムから利用できるインタフェースが追加され、その結果、標準ドックレットは再入可能になりました。詳細は、「標準ドックレット」を参照してください。 (4113483)

警告メッセージとエラーメッセージにファイル名と行番号を追加 - この行番号は、ドキュメンテーションコメントの特定の行ではなく、宣言の行に対するものです。SourcePosition クラスを使用してください。 (4396665)

直列化された形式のページの機能向上 - Javadoc に、直列化された形式のページの private クラスが含まれるようになりました (-private フラグは不要)。つまり、通常の Javadoc 実行で、直列化された形式のページが正しく生成されます。これは、filter が false の場合に private クラスおよび package-private クラスを組み込む PackageDoc.allClasses(boolean filter) メソッドを追加することで実行されています。(ドックレット API に固有の情報) 現在、writeReplace() メソッドは直列化された形式のページに組み込まれています。また、Javadoc は「@serial include」および「@serial exclude」タグを認識し、それに応じてクラスを組み込んだり除外したりします。詳細は、@serial タグを参照してください。 (4290079, 4180839, 4341304)

ファイル名のほか、コマンド行オプションと併せて使用される @files をドキュメント化 - これにより、ドキュメントと実装を一致させます。@files 機能はもともと javadoc および javac でドキュメント化されており、使用できるのはファイル名のみで、コマンド行オプションは使用できませんでした。この変更により、ドキュメント内で @files についてもコマンド行オプションを使用できるようになります。(また、ドキュメント内では @files から @argfile に名前を変更し、引数ファイルであることを明確にしました。) (4469119)

エラーメッセージ以外を除外する -quiet オプションを追加
- 警告メッセージおよびエラーメッセージのみを表示し、見つけしやすくしました。 (4217345)

標準ドックレットの出力ストリームでバージョン番号の値を出力 - -quiet オプションで抑制します。 (4114089)

出力先ディレクトリを自動作成 (-d) - javadoc の主な機能はファイルやディレクトリを作成することであるため、出力先ルートディレクトリを作成するのは合理的です。 (4464477)

有効なクラスのみをドキュメント化 - javadoc がパッケージをドキュメント化するとき、無効なクラス名で構成されているファイルを読み込まないようになりました。例:以前は、古い javadoc に com.sun.foo を渡すと、com\sun\foo ディレクトリ内にある、名前が「.java」で終わるファイルが、その拡張子を除いたファイル名が実際に有効なクラス名であるかどうかにかかわらず、すべて解析されました。新しい javadoc では、有効なクラス名を持つファイルだけが解析されます。このことをうまく利用して、開発者は、ドキュメント化の対象にしたくないテンプレートやテスト用ソースファイルなどの .java ファイルに、ハイフン (-) などを含むファイル名を付けることができます。 (4398440)

-linkoffline の区切り文字を「/」に修正 - Microsoft Windows 上で実行したとき、-linkoffline オプションを指定すると、外部クラスを指す各リンクに、「\」ではなく「/」が正しく挿入されるようになりました。このバグにより、Windows 上の javadoc で作成されたドキュメントを Unix 上でブラウズしたときに、外部クラスへのリンクが壊れているという現象が起きていました。 (4359874)

移行用の「-1.1」オプションを削除 - 「-1.1」オプションは、バージョン 1.2 のときに導入されたもので、Javadoc 1.1 から 1.2 への移行のためにドックレットとして用意されました。この移行は、バージョン 1.3 にアップグレードしてからは不要になりました。バージョン 1.1 のドックレットは、Java 言語の新機能 (内部クラスなど) を処理できず、標準ドックレットとコードを共用していることが維持管理の障害となるため、削除されました。 (4312499)

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

新規タグなど、ドキュメンテーションコメントの記述に影響する変更について説明します。 カスタムタグ用のタグインタフェースを追加
- @return のような通常のスタンドアロンタグや、{@link} のようなインラインタグを作成し、カスタムタグとして使用できます。 -tag オプションおよび -taglet オプションの順序によって、その出力順序が決定します。これらのオプションは、標準タグである -tag return-tag param と組み合わせて混在させることができます。

カスタムインラインタグについては、taglet を作成する必要があります。 (4282805)

カスタムタグの出力時の不明なタグにフラグ。 - この機能はカスタムタグのメカニズムの一部です。javadoc がドキュメンテーションコメントを解析するとき、標準タグではない、あるいは -tag や -taglet が付いていないタグに遭遇すると、そのタグを不明なタグとして認識し、警告をスローします。 (4039014)

行頭のアスタリスク (*) を省略するとき、<PRE> タグ内のインデントを維持。 - この機能により、コードの例をドキュメンテーションコメントに直接貼り付けられるようになります。インデントは区切り文字「/**」よりも左寄りになります。 (4232882)

最初の文の終わりを判別する新しい手段として、-breakiterator を追加。 - 次のメージャーリリースでは、最初の文の終わりを判別するアルゴリズムを変更する予定です。-breakiterator オプションで新しいアルゴリズムを試すことができます。1.2 および 1.3 では、java.text.BreakIterator クラスを使用してすべての言語 (ただし英語以外) の文の終わりを判別していました (4165985)。英文には、ピリオドのあとに空白文字が来るという固有のアルゴリズムがあります。-breakiterator を使用しないと、最初の文の終わりが 1.2 および 1.3 から変更されず、差異がある場所を表示する警告が表示されます。-breakiterator を用いて、新しいアルゴリズムを使用します。英文でのアルゴリズムの差異は、次のとおりです。 (4165985)

Javadoc でメソッド本体が要求されないように修正。 - Javadoc は、メソッド本体のない純粋なスタブファイルである .java ソースファイルに対しても実行することができます。したがって、API の作成時には、実装を記述する前の設計の早い段階で、ドキュメンテーションコメントを記述して javadoc を実行できます。以前では、これを行おうとすると javadoc によるメッセージが表示され、メソッドおよびクラスに「abstract」を追加するように要求されました。

{@link} のプレーンテキストバージョンである {@linkplain} を追加。 - リンクのラベルをコードフォントではなくプレーンテキストで表示します。ラベルがプレーンテキストで記述されていると便利です。 (4429628)
例:

        Refer to {@linkplain add() the overridden method}.

ドキュメント継承のための {@inheritDoc} タグを追加。 このタグは、ドキュメンテーションコメントをスーパークラスから現在のドキュメンテーションコメントにコピーします。この機能により、開発者は継承されたテキストだけでなく、コピーされたテキストを使って記述することもできます。以前は、テキストがコピーされるのはコメントが失われた場合だけでした。 (4186639)

Javadoc の @return タグ、@param タグ、@throws タグを個別に継承 1.3 では、これらのタグが継承されるのはドキュメンテーションコメント全体が空である場合のみでした。@see タグも継承されますが、これはオーバーライドしている要素に @see タグが存在しない場合のみです。 (4496270)

オーバーライドされるメソッド内で例外が明示的に宣言されている場合のみ、@throws ドキュメンテーションをそのメソッドからサブクラスにコピー。 1.3 では、メソッドが例外をスローできるかどうかにかかわらず、@throws テキストがオーバーライドするメソッドにコピーされていました。新しい動作によって、@throws が正常に継承していたドキュメンテーションの一部が削除されることがあります。@throws にドキュメンテーションを継承させるには、{@inheritDoc} を使用できます。 (4317583)

コンテンツの出力

出力するテキスト、イメージ、レイアウト、形式、およびリンクについて説明します。 static フィールド定数の値を組み込む - Javadoc で定数フィールドの値をドキュメント化できるようになりました。この値については別の「定数フィールド値」ページで説明しており、各 static フィールドの「関連項目: 定数フィールド値」というリンクから参照できます。新しいインラインタグ {@value} を static フィールドのコメント内で使用すると、そのフィールドの値が返されます。このタグは値をドキュメンテーションコメントを追加するのに便利です。 (4422788)

この変更のため、ドックレット API の com.sun.javadoc パッケージに FieldDoc.constantValue() メソッドおよび FieldDoc.constantValueExpression() メソッドを追加する必要がありました。(ドックレット API に固有の情報) (4320557)

出力内のクラス名の先頭から修飾パッケージ名を除外する -noqualifier オプションを追加
以前の動作では、p.C クラスのページで p パッケージに所属していないクラスのみにパッケージ名を追加していました。-noqualifier の引数として all を指定した場合、すべてのパッケージ修飾子がすべて省略されます。削除する複数のパッケージ名をコロンで区切って、ワイルドカードとともに指定することもできます (java.lang:java.awt:javax.* など)。 (4359889)

-linksource オプションを使用してソースコードにリンクを追加
各ソースファイルの HTML バージョンを作成し、通常のドキュメントからリンクを追加します。(Beta2 では -src と呼ばれていましたが、-source と区別しやすいように、最終バージョンでは -linksource に名前が変更されます。) (1242492)

ウィンドウのタイトルに現在のクラスまたはパッケージ名を表示。
この機能によって、ウィンドウを最小化したときに Windows タスクバーに名前が表示されるようになりました。(フレームが有効になっている場合、Internet Explorer でも動作します。) (4232597)

ソースファイル名 (*.java) で渡すとき、パッケージページを生成。 - 生成されたドキュメントは、パッケージ内のクラスに対してソースファイル名で渡される場合でも、パッケージ名で渡される場合でも、同じである必要があります。 (4359386)

次の場合に、スローセクションに例外クラスリンクを追加。
(1) @throws タグはあるが、テキストが伴わない場合
(2) 例外が宣言されているが、タグがない場合 (4074202)

記述およびタグを抑制し、宣言のみを生成するため、-nocomment を追加 用途に応じて、ソースファイルを再利用できるようになりました。 (4464558)

エラー終了のステータス - ドックレットの終了状態を使用するように、javadoc が修正されました。 (4136558)

package.html を読み込むとき、-encoding オプションを使用 (4463408)

ナビゲーションバーに「All Classes」を追加し、アクセス機能を向上 (4140824)

.java ファイルを渡したとき、doc-files ディレクトリをコピー - javadoc にソースファイル (*.java) を渡した場合にも、doc-files ディレクトリがドキュメント生成先にコピーされるようになりました。以前は、そのような場合には、doc-files ディレクトリはコピーされませんでした。この動作は、パッケージ名を渡した場合と同じになりました。 (4340814)

ドキュメンテーションルートの doc-files ディレクトリが生成先にコピーされるように修正
この修正によって、概要レベルのドキュメントを含むことができるようになりました。 (4256505)

-docfilessubdirs を追加し、doc-files を下位の階層までコピー - -docfilessubdirs を使用した場合、doc-files ディレクトリのサブディレクトリが生成先に再帰的にコピーされます。たとえば、doc-files/example/images とその中のコンテンツがすべてコピーされます。必要な場合は、次のオプションも利用できます。-excludedocfilessubdir name1>:<name2>... では、指定した名前の doc-files サブディレクトリを除外できます。これにより、SCCS とその他のソースコード制御サブディレクトリのコピーを防ぎます。以前は、doc-files ディレクトリ内のファイルだけがコピーされていました。 (4385048)

HTML フレームの {@docroot} を修正 - {@docroot} タグが、左上の HTML フレーム (overview-frame.html) で使用されている場合にも、正しく解決されるようになりました。 (4365290)

@see{@docroot} を修正 - @see タグのテキスト内の {@docroot} が正しく解決されるようになりました。 (4416364)

{@docRoot}{@link} のバグを修正 - 同じコメント内で {@docRoot} タグのあとに {@link} タグがあると、そのタグが無効になるというバグが修正されました。 (4369014)

「実装」見出しの修正 - abstract メソッドから継承されたドキュメンテーションコメントに対して、「オーバーライド」ではなく、「実装」という見出しが正しく使用されるようになりました。 (4318787)

インタフェースページの「実装クラス」を修正 - インタフェースページで一部のクラスが「実装クラス」として表示されないバグが修正されました。 (4378491)

static 初期化子の修正 - 以前のバージョンでは、static {...} があると、「- から継承したメソッド」の表がコンマ (,) で始まってしまいました。これは、javadoc が static {} を匿名メソッドと見なすバグが原因でした。現在、このコンマは生成されたドキュメントのメソッドエントリとして表示されません。 (4136861)

private 内部クラスのフィールドおよびメソッドを正しくドキュメント化 (445611)

「ネストされたクラス」という用語を修正 - javadoc が、すべての見出しと小見出しについて、「内部クラス」ではなく「ネストされたクラス」という用語を使用するようになりました。定義は次のとおりです。ネストされたクラスとは、「別のクラスまたはインタフェース本体の内側に宣言が置かれているクラス」のことです。それに対して内部クラスとは、「ネストされたクラスのうち、static 以外のクラス」を指します。したがって、「ネストされた」という用語の方が汎用的です。 (4307151)

ドックレット API

ドックレット API に固有の情報 ドックレット API が直列化できなくなった。 - クラスを直列化して拡張できなくなりました。(通常、これらを直列化しようとしても正しくできませんでした。) (4125581)

ドックレット API に固有の情報 宣言のファイル名と行番号を公開。 新しいクラス SourcePosition と、Doc および Tag (4192783 参照) の新しいメソッド position() をドックレット API に追加しました。これにより、ソースファイルの解析および変換を完全に行えるようになりました。 (4192783, 4208989)

ドックレット API に固有の情報 オーバーライドされるメソッドのリストを返す MethodDoc.overriddenMethod() を追加。

ドックレット API に固有の情報 ドックレット API のドキュメントを改善。

ドックレット API に固有の情報 互換性の問題の解消 - Tag インタフェースに position() メソッドを追加しました。1.3 の Tag インタフェースで実装していたドックレット (MIF 1.2 Beta 1 など) は Javadoc 1.4 では動作しません。

標準ドックレットコードの変更

標準ドックレットのコードの変更 - 標準ドックレットのソースコードで、MessageRetriever コンストラクタのシグニチャーに、configuration 引数が追加されました。この追加により、標準ドックレットをサブクラスとするコードに影響を及ぼす場合があります。新しいコンストラクタは、MessageRetriever(Configuration configuration, String resourcelocation) です。(バグ番号なし)

Javadoc ツールのフロントエンド

Javadoc ツールに関する説明については多くの変更点がありますが、もっとも注意すべき点は次のとおりです。

Javadoc ツールおよび API の再実装の完了 (4400430):- Javadoc が、古いコンパイラではなく新しい javac コンパイラを使用するようになりました。

いくつかの動作が変化したことがわかっています。これらの変化はバグではないため、javadoc で「修正」されることはありません。

古い javadoc について知られている間違った動作例の一部は、互換性を保つために、新しい javadoc 実装でも意図的に再現されています。たとえば、クラス a.A が内部クラスを持っている場合に、それらのクラスを次のようにしてインポートするとします。

        import a.A.*;
古い javadoc では、ドックレット API を介して、次のようなインポートが間違って報告されます。
        import a.*;
現行の javadoc API では、このインポート宣言を正しく表現する方法はありません。

ClassDoc インスタンスが一意ではなくなった - 1.4.0 より前は、ドキュメント化されるすべてのクラスが単一の ClassDoc インスタンスで表現されていました。これは、ドキュメントに記載されていない実装の詳細です。1.4.0 では、その動作が変わりました。Javadoc ツールは、同じクラスを表現した 2 つの異なる ClassDoc インスタンスを作成することができます。この変更により、不適切に以前の動作に依存しているドックレットが問題を起こすことがあります。そのようなバグの 1 つに、4496290 (-use オプションが重大な問題を起こす) があります。


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