このドキュメントでは、バージョン 1.4.1 から 1.4.2 への移行で Javadoc ツールに対して行われた変更について説明します。
掲載されている変更点には、バグ番号と、その修正が Javadoc ツールのフロントエンドに対するもの (「ツール」) であるか、または標準ドックレットに対するもの (「標準ドックレット」) であるかが示されています。「リグレッション」という用語は、1.3.x では動作していたのに、1.4.0 または 1.4.1で動作しなくなり、1.4.2 で修正された機能に対して使用されます。
主要な新機能
- このバージョンでは、Acessibility (ユーザ補助機能) に対する米国政府の第 508 項の要件に関連したバグがすべて修正されました。(4737558、標準ドックレット)
- 「直列化された形式」に serialVersionUID を組み込みました。(4525039、標準ドックレット)
- ドキュメント化の対象ではないソースファイルからコメントを継承できるようになりました。ドキュメント化するコードは、コマンド行で渡されていないソースファイルでも、-sourcepath 上にあるソースファイルであれば、そのソースファイル内のインタフェースおよびクラスからコメントを自動的に継承することができます。たとえば、J2SE の場合にこの機能を試すには、SDK に同梱されている src.zip (ただし、ソースファイルの一部しか含まれていない) を解凍して、そのパスを -sourcepath に追加します。目的のコードに対して javadoc を実行すると、必要に応じてこれらのソースファイルからドキュメンテーションコメントがロードされます。コードが java.lang.Comparable を実装している場合は、実装した
compareTo(Object) メソッドは java.lang.Comparable からドキュメンテーションコメントを継承します。
この機能は、実際には 1.4.1 で使用可能になりました。(バグ番号なし、ツール) -link (または -linkoffline) オプションを使用したとき、すべての @see タグおよび {@link} タグにより、除外されたクラスへのリンクも作成されるようになりました。この修正は、外部のクラスおよびメンバをリンクする作業を大幅に簡略化します。以前は、@see または {@link} で外部クラスのドキュメントにリンクするためには、その外部クラスをインポートするか、宣言の中で完全に修飾する必要がありました。今回のバージョンからは、クラスを完全に修飾したうえで、そのクラスの API ドキュメントが -link により指定したパス上に存在するだけでよいことになりました。(4652655、標準ドックレット)
その他の新機能については、下に掲載します。
主要なバグ修正
- リンク: 完全修飾されたプログラム要素の @link を修正して、
-link オプションで指定された外部クラスにリンクするようにしました。(4652655、ツール、リグレッション)
- リンク: .java ファイルが渡されたとき、戻り値およびパラメータの型に対する内部リンクが欠落するというバグを修正しました。(4628281、ツール)
- 実行: 重複したクラスもドキュメント化するように修正しました。(4673477、ツール、リグレッション)
- 直列化された形式: 「直列化された形式」におけるリンクアンカーを修正しました。(4521661、標準ドックレット)
- Javascript: -linkoffline によりリンクされたときの Internet Explorer Javascript のロードエラー。(4645058、標準ドックレット、リグレッション)
- HTML: パッケージ名を渡した場合や .java ファイル名を渡した場合に diff が出ないように修正しました。(4506980、標準ドックレット)
その他のバグ修正については、下に掲載します。
主要な既知のバグ
Javadoc ツールがハングアップすることのあるバグや、非常に顕著なバグについて、ここで紹介します。また、未解決のバグの簡易版リストについては重要な新しいバグとリグレッションの説明、データベースの一覧表については Important Bug Fixes and Changes を参照してください。
新機能とバグ修正
1.4.2 におけるすべての新機能とバグ修正はこのあとに掲載します。
コマンド行オプション
- 新機能: 左上フレームに -packagesheader オプションを追加しました。(4766385、標準ドックレット)
- 新機能: 「-tag name:a:name」に対して「-tag name」という短縮表記が使用可能になりました。(4695326、標準ドックレット)
- 新機能: 各タブを n 個の空白文字に変換するための -linksourcetab オプションを追加しました。このオプションは実験的であり、変更される可能性があります。(4510979、標準ドックレット)
- 新機能: -tag オプションで、@ejb:bean などの xdoclet タグに対してダッシュ (-) 区切り文字を使用できるようになりました。 (4750173、標準ドックレット)
- 新機能: 新しい -keywords オプションにより、API の検索を改善するためにメンバ名を META キーワードタグとして追加できるようになりました。(4764726、標準ドックレット)
- 新機能: 警告があった場合にゼロ以外で終了するための -Xwerror フラグを追加しました。(4099527、ツール)
- バグ修正: オプション「-tag tagname:X:taghead」を修正し、taghead を省略可能にしました。(4628181、標準ドックレット)
- バグ修正: -quiet オプションにより抑止されるのが標準ドックレットのメッセージだけであることをドキュメントに明記しました (4714350、標準ドックレット)。新しいバグ 4702454 を提出して、javadoc ツールのメッセージも抑止するように要求しました。
- バグ修正: -source オプションのドキュメントを、ドックレットのオプションから javadoc ツールのオプションに移動しました。これは、実際には、最初からツールのオプションでした。(4760924、標準ドックレット)
タグ
- 新機能: Javadoc で、実行時例外の @throws コメントを継承するようになりました。(4679573、標準ドックレット)
- 新機能: Javadoc で、@param の最初の引数がパラメータ名でない場合に警告を出すようになりました。(4693440、標準ドックレット)
- バグ修正: @throws のテキストを継承する際、完全修飾の例外名を比較するようにしました。(4684827、標準ドックレット)
- バグ修正: 自動生成の例外だけが後に続く場合に「例外」見出しが欠落するというバグを修正しました。(4530727、標準ドックレット)
- バグ修正: abstract スーパークラスのインタフェースから継承する際に壊れていた @inheritDoc を修正しました。(4720974、標準ドックレット)
API 仕様
- 新機能: 「直列化された形式」に serialVersionUID を組み込みました。(4525039、標準ドックレット)
- 新機能: ドキュメント化の対象ではないソースファイルからコメントを継承できるようになりました。ドキュメント化するコードは、コマンド行で渡されていないソースファイルでも、-sourcepath 上にあるソースファイルであれば、そのソースファイル内のインタフェースおよびクラスからコメントを自動的に継承することができます。例を参照してください。(バグ番号なし、ツール)
- バグ修正: 概要テーブルで、継承された入れ子のクラスが欠落しているというバグを修正しました。(4638588、標準ドックレット)
- バグ修正: Javadoc が隠されたフィールドを誤ってリストに含めないように修正しました。(4492178、標準ドックレット)
- バグ修正: public 以外の直列化可能クラスの直列化可能なスーパークラスを追加するようにしました。(4671694、標準ドックレット)
- バグ修正: private メソッド (たとえば createBufferStrategy) のオーバーライドをドキュメント化しないようにしました。(4634891、標準ドックレット)
HTML と Javascript
- 新機能: 生成される HTML コメントに、javadoc のバージョン番号とビルドを組み込むようにしました。(4749707、標準ドックレット)
- バグ修正: 「直列化された形式」ページのクラスを参照するリンクに「#anchor」を追加するように戻しました。(4521661、標準ドックレット、リグレッション)
- バグ修正: -linkoffline によりリンクされたときの Javascript IE ロードエラーを修正しました。(4645058、標準ドックレット、リグレッション)
- バグ修正: パッケージ名を渡した場合や .java ファイル名を渡した場合に diff が出ないように修正しました。(4506980、標準ドックレット)
- バグ修正: 無効な stylesheet.css ファイル (font-size: normal) を修正しました。(4417174、標準ドックレット)
- バグ修正: 左フレームをロードしたときにウィンドウタイトルが変化しないように修正しました (Javascript、標準ドックレット)。(4747738、標準ドックレット)
無効な HTML
- バグ修正: DOCTYPE 宣言で欠落していた空白文字を追加しました。(4625400、標準ドックレット)
- バグ修正: フレームセット DTD 内の無効な HTML と、余分な <DL> を修正しました。(4275630、標準ドックレット)
- バグ修正: <FRAMESET> 要素の外側では使用できない <NOFRAMES> を修正しました。(4753048、標準ドックレット)
- バグ修正: index-all.html ファイル内の間違った !DOCTYPE を修正しました。(4418115、標準ドックレット)
- バグ修正: 「パッケージの使用」ページで間違った場所に挿入されていた HTML テーブルタグを修正しました。(4415270、標準ドックレット)
リンク
- バグ修正: .java ファイルが渡されたとき、戻り値およびパラメータの型で内部リンクが欠落するというバグ。(4628281、ツール、リグレッション)
- バグ修正: 完全修飾されたプログラム要素の @link を修正して、
-link オプションで指定された外部クラスにリンクするようにしました。(4652655、ツール、リグレッション)
- バグ修正: -link および -linkoffline を修正して、適切な相対リンクを生成するようにしました。(4720957、標準ドックレット)
- バグ修正: Windows 上で実行したとき、-linksource オプションによってリンクの中に「\」が生成されないようにしました。(4511110、標準ドックレット)
- バグ修正: {@link java.lang label} 内のラベルが、パッケージ名にリンクしているときにも無視されないようにしました。(4524136、標準ドックレット)
- バグ修正: @link タグで、第 1 引数と第 2 引数の間に改行だけが存在するときに適切でない書式を設定しないように修正しました。(4739870、標準ドックレット)
Javadoc の実行
- バグ修正: ソースディレクトリに名前のないパッケージのテストファイルが含まれている場合に、ツールがクラッシュしないようにしました。(4670772、ツール)
- バグ修正: 重複したクラスを再度ドキュメント化するように修正しました。(4673477、ツール、リグレッション)
- バグ修正: 空の jar ファイルが classpath 上にある場合に、空の jar ファイルが classpath にあっても例外をスローしないように修正しました。(4697113、標準ドックレット)
- バグ修正: ファイル: ソースディレクトリと生成先ディレクトリが同じである場合でも、doc-files が破壊されないようになりました。(4258405、標準ドックレット)
エラーメッセージと警告メッセージ
- バグ修正: 意味の分かりにくい「foo.jar: Body tag missing from HTML」というエラーメッセージを改善しました。(4691095、標準ドックレット)
- バグ修正: Javadoc を修正して、classpath の jar ファイルに package.html ファイルが含まれていてもエラーを報告しないようにしました。(4697040、標準ドックレット)
- バグ修正: 「Parameter foo is documented more than once.」という不正な警告を修正しました。(4745855、標準ドックレット)
- バグ修正: System.out や System.err ではなく、Messager PrintWriters を使用するようになりました。(4644257、標準ドックレット)
Accessibility
- バグ修正: 「インタフェース」としてのイタリックスタイルについて説明するタイトル記述をリンクに追加しました。(4714257、標準ドックレット)
- バグ修正: ユーザ補助機能として、ナビゲーションバーをスキップする機能を追加しました。(4638136、標準ドックレット)
- バグ修正: ユーザ補助機能として、テーブルに summary 属性を追加しました。(4637604、4775148、標準ドックレット)
- バグ修正: ユーザ補助機能として、<FRAME> タグに title 属性を追加しました。(4636655、標準ドックレット)
- バグ修正: <H1>、<H2>、<H3> が適切な順序になるように修正しました。(4636667、標準ドックレット)
- バグ修正: ユーザ補助機能として、クラス階層図の ASCII アートに同等の内容のテキストを追加しました。(4706779、標準ドックレット)
ドックレット API
- 新機能: Doclet API を拡張して、Tag インタフェースに holder() メソッドを追加しました。(4706525、標準ドックレット)
- バグ修正: Doc オブジェクトが再び、== で比較可能になりました。(4731054、ツール、リグレッション)
- バグ修正: .class ファイルからビルドしたとき、入れ子のクラスの ClassDoc が間違っていたのを修正しました。(4694497、ツール)
- バグ修正: Doc.position() の仕様を明確にしました。(4748246、標準ドックレット)
- バグ修正: RootDoc の classes() メソッドの仕様を明確にしました。(4748234、標準ドックレット)
- バグ修正: com.sun.javadoc.SeeTag の仕様を明確にしました。(4754029、標準ドックレット)
- バグ修正: PackageDoc.ordinaryClasses() の仕様を明確にしました。(4748244、標準ドックレット)
- バグ修正: com.sun.javadoc.Doc の仕様にある「kind」の意味を明確にしました。(4502589、標準ドックレット)
- バグ修正: Doc.isClass() の仕様とすべての「class (クラス)」という用語の意味を明確にしました。(4748245、標準ドックレット)
- バグ修正: 「class (クラス)」の意味をさらに明確にしました。(4763596、標準ドックレット)
- バグ修正: PackageDoc.allClasses() メソッドの仕様と「included」という用語の意味を明確にしました。(4748240、標準ドックレット)
- バグ修正: ProgramElementDoc.qualifiedName() のパラメータリストの仕様を明確にしました。(4621267、標準ドックレット)
- バグ修正: RootDoc.classes() および PackageDoc.allClasses() の仕様を明確にしました。(4748238、標準ドックレット)
