Javadocの拡張機能(Java SE 1.4.2)

このドキュメントでは、バージョン1.4.1から1.4.2への移行でJavadocツールに対して行われた変更について説明します。

掲載されている変更点には、バグ番号と、その修正がJavadocツールのフロント・エンドに対するもの(「ツール」)であるか、または標準ドックレットに対するもの(「標準ドックレット」)であるかが示されています。「リグレッション」という用語は、1.3.xでは動作していたのに、1.4.0または1.4.1で動作しなくなり、1.4.2で修正された機能に対して使用されます。

主要な新機能
主要なバグ修正
主要な既知のバグ
新機能とバグ修正

主要な新機能

このバージョンでは、Accessibility (ユーザー補助機能)に対する米国政府の第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ツールがハング・アップすることのあるバグや、非常に顕著なバグについて、ここで紹介します。バグの簡潔なリストが「重要な新しいJavadocのバグと回帰」に表示されます。

コメントを継承できないメンバーの中で{@inheritDoc}を使用すると、役立つメッセージが表示されずにJavadocがハング・アップします。(4812240、標準ドックレット)たとえば次のような場合です。
```
public class C {
    /** {@inheritDoc} */
    public abstract void m() {
    }
}
```
Internet Explorerでフレームを表示すると、メイン・コンテンツのペインに不必要な水平スクロール・バーが表示されます。簡単な回避策が、バグ・レポートの中で説明されています。(4852280、標準ドックレット)

新機能とバグ修正

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、標準ドックレット)

連絡先