|
|
Javadoc 1.4 の新機能 |
Javadoc ツール |
このドキュメントでは、バージョン 1.3 から 1.4 へのアップグレードで Javadoc ツールに加えられた変更について説明します。また、未解決のバグの簡易版リストについては 重要な新しいバグとリグレッションの説明、データベースの一覧表については「Java(TM) 2 SDK and Runtime Environment Important Bug Fixes and Changes」を参照してください。
新規タグ
{@linkplain}、{@inheritDoc}、@serial、{@value}新規オプション
-breakiterator、-docfilessubdirs、-exclude、-excludedocfilessubdir、-nocomment、-noqualifier、-quiet、-source、-linksource、-subpackages、-tag、-taglet
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)メソッドを追加することで行われました。() 現在、
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}のようなインタインラグを作成し、カスタムタグとして使用できます。
- 単純タグ - テキストの引数を 1 つもつタグ。固有のタグ名を選択し、
-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)
- 古いアルゴリズム - ピリオドのあとに空白文字がある位置、または段落レベルの HTML タグ (
<P>など) の位置で停止- 新しいアルゴリズム - 次の語が大文字で始まる場合、ピリオド、疑問符、または感嘆符と空白文字の位置で停止。このアルゴリズムでは、ほとんどの省略表記が処理される (「Serial no. is valid」は処理されるが「Mr. Smith」は処理されない)。HTML タグや、数字または記号で始まる文では停止しない
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()メソッドを追加する必要がありました。(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)
ナビゲーションバーに「すべてのクラス」を追加し、アクセス機能を向上 (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}タグがあると、その{@link}タグが無効になるというバグが修正されました。 (4369014)「実装」見出しの修正 - abstract メソッドから継承されたドキュメンテーションコメントに対して、「オーバーライド」ではなく、「実装」という見出しが正しく使用されるようになりました。 (4318787)
インタフェースページの「実装クラス」を修正 - インタフェースページで一部のクラスが「実装クラス」として表示されないバグが修正されました。 (4378491)
static 初期化子の修正 - 以前のバージョンでは、static {...} があると、「〜から継承したメソッド」の表がコンマ (,) で始まってしまいました。これは、javadoc が
static { }を匿名メソッドと見なすバグが原因でした。現在、このコンマは生成された ドキュメントのメソッドエントリとして表示されません。 (4136861)private 内部クラスのフィールドおよびメソッドを正しくドキュメント化 (445611)
「入れ子のクラス」という用語を修正 - javadoc が、すべての見出しと小見出しについて、「内部クラス」ではなく「入れ子のクラス」という用語を使用するようになりました。定義は次のとおりです。入れ子のクラスとは、「別のクラスまたはインタフェース本体の内側に宣言が置かれているクラス」のこと」です。それに対して内部クラスとは、「入れ子のクラスのうち、static 以外のクラス」を指します。したがって、「入れ子の」という用語のほうが汎用的です。 (4307151)
SourcePositionをドックレット API に追加するとともに、新しいメソッドposition()をDocおよびTagに追加しました (4192783 参照)。これにより、ソースファイルの解析および変換を完全に行えるようになりました。 (4192783、4208989)
MethodDoc.overriddenMethod()を追加
Tagインタフェースにposition()メソッドを追加しました。1.3 のTagインタフェースを実装しているドックレット (MIF ドックレット 1.2 Beta 1 など) は Javadoc 1.4 では動作しません。
標準ドックレットのコードの変更 - 標準ドックレットのソースコードで、MessageRetrieverコンストラクタのシグニチャーに、configuration引数が追加されました。この追加により、標準ドックレットをサブクラスとするコードに影響を及ぼす場合があります。新しいコンストラクタは、MessageRetriever(Configuration configuration, String resourcelocation)です。 (バグ番号なし)
Javadoc ツールおよび API の再実装の完了 (4400460) - Javadoc が、古いコンパイラではなく新しい javac コンパイラを使用するようになりました。
いくつかの動作が変化したことがわかっています。これらの変化はバグではないため、javadoc で「修正」されることはありません。
- private の内部クラスが、private としてマークされるようになりました。古い javadoc では、それらのクラスが package protected として間違ってマークされていました。
- 古い javadoc では、static クラスの初期化ブロックが、
<clinit>という名前の関数であるかのようにして報告されていました。新しい javadoc では、それらのブロックは正しく省略されます。- 古い javadoc では、入れ子になったクラスのコンストラクタに対して、間違って
this$0パラメータが挿入されていました。この動作は、コンストラクタのリフレクションの観点からすると間違いではありませんが、ソースコードまたは言語の観点からすると間違っています。新しい javadoc では、ソースの記述どおりにシグニチャーが報告されます。- 古い javadoc では、コンパイラ生成のフィールド
this$0が、直列化可能フィールドとして報告されることがありました。新しい javadoc では、this$0やその他の合成メンバの報告が正しく省略されます。実例については、java.util.logging.LogManager.LogPropertiesを参照してください。- 古い javadoc では、ソースに記述されているワイルドカードのインポート宣言が省略されることがありました。たとえば、
java.io.PipedOutputStreamの変換ユニットには、「import java.io.*;」が含まれています。これは無意味で冗長です。新しい javadoc では、インポートのリストに正しく組み込まれます。- 古い javadoc では、private メソッドが、スーパークラス内の同じシグニチャーを持つ private メソッドをオーバーライドしていると、間違って報告されていました。新しい javadoc では、private メソッドは決してオーバーライドされないものとして正しく報告されます。
- 新しい java.io 実装にいくつかのバグが残っているため、出力の Unicode 文字が正しく処理されないことがあります。これは javadoc そのもののバグではありませんが、古い javadoc の出力を新しい javadoc の出力と比較すると、多少の違いが生じます。そのような違いの実例としては、
java.util.regex.Pattern.Caretを参照してください。このバグを回避するには、より多くの Unicode 文字をサポートしているロケールを使用します。古い javadoc について知られている間違った動作例の一部は、互換性を保つために、新しい javadoc 実装でも意図的に再現されています。たとえば、クラス a.A が内部クラスを持っている場合に、それらのクラスを次のようにしてインポートするとします。
import a.A.*;古い javadoc では、ドックレット API を介して、次のようなインポートが間違って報告されます。import a.*;現行のドックレット API では、このインポート宣言を正しく表現させる方法はありません。ClassDoc インスタンスが一意ではなくなりました - 1.4.0 より前は、ドキュメント化されるすべてのクラスが単一の ClassDoc インスタンスで表現されていました。これは、ドキュメントに記載されていない実装の詳細です。1.4.0 では、その動作が変わりました。Javadoc ツールは、同じクラスを表現した 2 つの異なる ClassDoc インスタンスを作成することができます。この変更により、不適切に以前の動作に依存しているドックレットが問題を起こすことがあります。そのようなバグの 1 つに、4496290 (-use オプションが重大な問題を起こす) があります。
|
Copyright © 2001 Sun Microsystems, Inc. All Rights Reserved. |
 Java ソフトウェア |
コメントの送付先: 