このドキュメントでは、バージョン 1.3 から 1.4 への移行で Javadoc ツールに対して行われた変更について説明します。また、未解決のバグと主要なバグ修正の簡易版リストについては、重要な新しいバグとリグレッションの説明を参照してください。
{@linkplain}
、{@inheritDoc}
、@serial
、{@value}
新規オプション
-breakiterator
、-docfilessubdirs
、-exclude
、-excludedocfilessubdir
、-nocomment
、-noqualifier
、-quiet
、-source
、-linksource
、-subpackages
、-tag
、-taglet
-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)
メソッドを追加することで実行されています。() 現在、
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
オプションと -tagletclasspath
オプションを指定します (-tag
オプションは使用しないでください)。-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)
<P>
など) の位置で停止する。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)
{@value}
を static フィールドのコメント内で使用すると、そのフィールドの値が返されます。このタグは値をドキュメンテーションコメントを追加するのに便利です。 (4422788)
この変更のため、ドックレット API の com.sun.javadoc パッケージに FieldDoc.constantValue()
メソッドおよび FieldDoc.constantValueExpression()
メソッドを追加する必要がありました。() (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)
宣言のファイル名と行番号を公開。 新しいクラス
SourcePosition
と、Doc
および Tag
(4192783 参照) の新しいメソッド position()
をドックレット API に追加しました。これにより、ソースファイルの解析および変換を完全に行えるようになりました。 (4192783, 4208989)
オーバーライドされるメソッドのリストを返す
MethodDoc.overriddenMethod()
を追加。
ドックレット API のドキュメントを改善。
互換性の問題の解消 -
Tag
インタフェースに position()
メソッドを追加しました。1.3 の Tag
インタフェースで実装していたドックレット (MIF 1.2 Beta 1 など) は Javadoc 1.4 では動作しません。
MessageRetriever
コンストラクタのシグニチャーに、configuration
引数が追加されました。この追加により、標準ドックレットをサブクラスとするコードに影響を及ぼす場合があります。新しいコンストラクタは、MessageRetriever(Configuration configuration, String resourcelocation)
です。(バグ番号なし)
Javadoc ツールおよび API の再実装の完了 (4400430):- Javadoc が、古いコンパイラではなく新しい javac コンパイラを使用するようになりました。
いくつかの動作が変化したことがわかっています。これらの変化はバグではないため、javadoc で「修正」されることはありません。
<clinit>
という名前の関数であるかのようにして報告されていました。新しい javadoc では、それらのブロックは正しく省略されます。this$0
パラメータが挿入されていました。この動作は、コンストラクタのリフレクションの観点からすると間違いではありませんが、ソースコードまたは言語の観点からすると間違っています。新しい javadoc では、ソースの記述どおりにシグニチャーが報告されます。this$0
が、直列化可能フィールドとして報告されることがありました。新しい javadoc では、this$0
やその他の合成メンバーの報告が正しく省略されます。例については、java.util.logging.LogManager.LogProperties
を参照してください。java.io.PipedOutputStream
の変換ユニットには、「import java.io.*;
」が含まれています。これは無意味で冗長です。新しい javadoc では、インポートのリストに正しく組み込まれます。java.util.regex.Pattern.Caret
を参照してください。このバグを回避するには、より多くの Unicode 文字をサポートしているロケールを使用します。古い 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 オプションが重大な問題を起こす) があります。