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

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

• 主要な新機能
• 主要なバグ修正
• 既知のバグ
• カスタム・ドックレットとの非互換性
• 新機能とバグ修正
  • コマンド行オプション
  • タグとタグレット
  • リンク
  • 生成されるAPI仕様
  • 書式指定と無効なHTML
  • ナビゲーション・バー
  • Accessibility
  • Javadocの実行
  • エラー・メッセージ、警告メッセージ、ステータス・メッセージ
  • ドックレットAPI

主要な新機能

• ジェネリック、列挙型、可変引数: これらの新しい言語機能に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4421066、ツール)と、標準ドックレット(4789689、標準ドックレット、投票数1)に追加しました。
• 注釈: 注釈および注釈型に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4904495、ツール)と、標準ドックレット(4905985、標準ドックレット)に追加しました。
• BreakIterator: 5.0では、-breakiteratorの警告メッセージを取り去りました。また、文の区切りを判別するデフォルト・アルゴリズムは、以前のリリースと同じです。つまり、\-breakiteratorオプションは、5.0ではデフォルトではなくなり、またデフォルトにするつもりもありません。これは、「次のメジャー・リリース」(5.0)でデフォルトを変更するという、以前の目的とは逆になっています。したがって、1.4.xでbreakiteratorの警告の表示をなくすためのソース・コード変更を行っていない場合は、何も処置を取る必要がありません。5.0では警告が表示されなくなるからです。このような方針転換の理由は、-breakiteratorをデフォルトにすることのメリットよりも、その変更に伴い必要になるソース・コード変更の手間というデメリットの方が大きいと考えたことです。この件で皆様に余分の手間をおかけし、混乱を招いたことをお詫びいたします。(なお、-breakiteratorオプションは1.4.0で追加されました。また、英語ロケールの場合、このオプションを指定するとドキュメンテーション・コメント内の最初の文の終わりを判別するためにBreakIteratorクラスが強制的に使用されます。英語以外の言語では、BreakIteratorによる判別が以前から実行されていました。) (4959985、ツール)
  さらに、将来のリリース(可能であれば5.1より)では、新しいjavadocタグを追加して(機能要求4921374)、サマリーを明示的にマークできるようにする予定です。その結果、なんらかの検出法を使用する必要がなくなります。
• 新しいタグ{@literal}および{@code}: {@literal}タグは、リテラル・テキストを表します。このタグで囲まれたテキストには、HTMLマークアップや、ネストされたjavadocタグが含まれないものとして解釈されます。たとえば、ドキュメンテーション・コメント・テキスト{@literal a<B>c}は、生成されるHTMLページで未変更のままa<B>cと表示されます。つまり、<B>は太字として解釈されません。
  {@code}タグは、リテラル・テキストをコード・フォントとして書式指定します。{@code abc}は<code>{@literal abc}</code>と等価です。
• タグ {@value arg}: このインライン・タグは、{@value package.class#field}のように、プログラム要素の名前を受け付けるようになりました。このような表記は、定数フィールドのドキュメンテーション・コメント内だけでなく、任意のドキュメンテーション・コメント内で使用できます。(4764045、標準ドックレット、投票数2)
• package-info.java: この名前でソース・ファイルを作成し、パッケージのコメントと注釈を保存することができます。package.html (コメントだけをサポートし、注釈はサポートしない)の代用になります。package-info.javaが存在する場合、javadocはpackage.htmlを無視して、(場合によっては注釈が付けられた)パッケージ宣言の直前にパッケージ・ドキュメンテーション・コメントを探します。javadocツールは、package-info.javaおよびpackage.htmlの選択と解析を行い、ドキュメンテーション・コメントをドックレットに渡します。 Package Comment Filesを参照してください。
• @Deprecated注釈: これは5.0の新しい注釈で、プログラム要素を非推奨にするための@deprecatedタグに追加して使用します。Java言語仕様では、@Deprecated注釈(必ずしもタグではない)を使用する場合、警告を発行するコンパイラが必要です。@deprecatedタグには、非推奨プログラム要素に代わる要素を記述する場所があります。「@Deprecated注釈」を参照してください。
• 標準ドックレットを再実装: 標準ドックレットおよびMIFドックレットが再実装され、可能なかぎり多くのコードを共有するようになりました。これにより、両方のドックレットのバグを削減することや、MIFドックレットの機能を標準ドックレットの機能に昇格させることが可能になります。なお、新しいMIFドックレットはまだリリースされていません(おそらく、バージョン1.4 Beta 1という名称になる予定)。この2つのドックレットを併合する主な理由は、どちらのドックレットも形式が異なる(HTMLとPDF)だけで本質的には同じドキュメントを生成するものだからです。(4638723、標準ドックレット、投票数2)
  この共有コードは、ドックレット・ツールキットとして公開することを予定しています。Javadocツールのホーム・ページを参照してください。

  すべての新機能については、下に掲載します。

主要なバグ修正

• オプション -tag: (リグレッション) -tagタグを修正して、その名前にダッシュ「-」を含めることができるように戻しました(1.4.1と同様)。(4920381、標準ドックレット、投票数59)
• {@inheritDoc}が原因のハング・アップ: {@inheritDoc}が(1)スーパー・スーパーインタフェースから継承できない場合、または(2)スーパー・スーパーインタフェースから継承している場合に、ハング・アップすることがなくなりました。(4812240、標準ドックレット、投票数18)
• タグ@param: (リグレッション)@paramを修正して、パラメータ名(第1引数)が間違っていても、パラメータ名を出力するようにしました(1.3.1と同様)。(4802275、標準ドックレット、投票数1)
• タグ{@value}: {@value}をカスタム・タグの中で使用しても、NullPointerExceptionが生成されなくなりました。(4821796、標準ドックレット、投票数1)
• ブラウザのスクロール・バー: Internet Explorerでフレームを表示したとき、不必要な水平スクロール・バーが表示されなくなりました。(4852280、標準ドックレット、投票数5)
• package-privateドキュメントの継承: -privateオプションを使用したとき、package-privateクラスから継承されたメソッドが、継承されたメソッドのサマリー表にだけドキュメント化され、詳細セクションにはドキュメント化されないという、正しい動作をするようになりました。(4780441、標準ドックレット、投票数5)
• 最初の文が{@inheritDoc}で終わっている場合: {@inheritDoc}が含まれている最初の文の終わりを正しく判別するようになりました。(4767038、標準ドックレット、投票数4)
• 最初の文に{@docRoot}が含まれているとリンクが壊れる: 最初の文に{@docRoot}リンクが含まれていても、単一ページのインデックスでリンクが壊れなくなりました。(4760191、標準ドックレット、投票数3)
• 継承されたコメントへのリンク: 継承されたコメントが、単にクラスにリンクするだけでなく、適切なメンバーに直接リンクするようになりました。(4368820、標準ドックレット、投票数1)
• 索引のアルファベット順ソート: 索引が再び大文字小文字の区別なくソートされるようになりました。1.4.1と1.4.2においてのみ、大文字の後に小文字が続くようにソートされていました。(4984419、標準ドックレット、投票なし)

  すべてのバグ修正については、下に掲載します。

既知のバグ

Javadoc 5.0には、ハング・アップやクラッシュの原因となるバグはありません。Bug Databaseの一覧表を参照してください。主要なバグは次のとおりです。

• 1.4.2以降、深く継承されたクラスのパフォーマンスが1/6に低下。低下する原因の一部は、ジェネリック型のパラメータに必要な追加処理にあります。
  回避策: なし。(5081166)
• 主説明に{@inheritDoc}が含まれる場合に基底クラス内の@paramが無視される。
  回避策: なし。(4778311)
• 定数に角カッコ(<)が含まれる場合に不正な「定数値」ページを生成
  回避策: なし。(5077317)
• リソース・ファイル内にメッセージが存在しないために不正なHTMLタグがエラーをスローする。
  エラー・メッセージ: java.util.MissingResourceException: Can't find resource for bundle com.sun.tools.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag
  回避策: javadocに渡されるパッケージとクラスの数をエラーがなくなるまで減らし、不正なタグを含むソース・ファイルを見つけます。次に、不正なタグを修正します。不正なHTMLタグとは、先頭部分は正しいが、それ以外が不適切なタグです。たとえば、<action>は不正な<a>タグと解釈されます。(5082928)

カスタム・ドックレットとの非互換性

5.0より前に記述されたカスタム・ドックレットは、5.0の新しい言語機能を使用するソース・ファイルに対して実行すると、互換性の問題が発生します。

• 新しい言語機能: ドックレットAPIおよび標準ドックレットは、5.0の新しい言語機能(ジェネリック、列挙型、可変引数、および注釈)を処理できるように改訂されました。これらの機能に対応するため、カスタム・ドックレットも改訂する必要があります。

  Javadocツールは、いわゆる「レガシー(従来の)」ドックレットに対して、可能な範囲で次のようなプログラム・ビューを提示しようとします。(1) 5.0より前のソース・コードでも引き続き動作する。(2) 5.0ソース・コードで期待される事柄に適合する。したがって、たとえば、ジェネリックの構造からは型パラメータと型引数が取り除かれ、型変数とワイルドカード型は新たに置き換えられ、ClassDoc.fields()はenum定数を返します。

  とはいえ、レガシー・サポートの仕様は精度が高くありません。処理対象の言語を理解できるようにドックレットが更新されるまでの間の、暫定的な互換モードです。保証されているのは、ドックレットそのもののソースおよびバイナリの互換性だけです。たとえば、5.0のJavadocツールを使用する場合に、ドックレットは1.4をベースにしており、処理対象のソース・コードも1.4をベースにしているとしても、そのドックレットをコンパイルすることができ、ドックレットは以前と同じように動作します(バグ修正は除く)。

---

新機能とバグ修正

この後のリストには、5.0における実質的にすべての新機能とバグの修正を掲載します。ごく小さな変更は省略しています(ドックレットAPIドキュメントで壊れていたリンクの修正など)。また、5.0のEarly Access版で発生し、最終リリースで修正されたバグも省略しています。

コマンド行オプション

• 新機能: -keywordsオプションにより、生成される各HTMLファイルに、検索に便利なMETAタグが追加されるようにしました。(4776637、標準ドックレット)
• 新機能: 新しい -notimestampオプションを使用すると、HTMLページの上に埋め込まれている隠し表示のタイムスタンプが抑止されます。(4777717)
• 新機能: 名前にハイフンを含むテスト用のサブパッケージを作成できるようになりました。-subpackagesオプションを使用したとき、そのようなサブパッケージはスキップされ、警告は生成されません。つまり、このオプションでは、Java名として無効な名前のディレクトリに遭遇しても警告を生成しません(Java名として無効な名前の規則は、無効なソース・ファイル名と同じ)。(4773013、ツール)
• バグの修正: -helpオプションで使用方法に「[classnames]」が表示されるという間違いが修正されました。(4775743、ツール)
• バグの修正: -groupオプションで、警告の重複がなくなりました。(4924383、標準ドックレット)

タグとタグレット

• 新機能: {@literal}タグは、リテラル・テキストを表します。このタグで囲まれたテキストには、HTMLマークアップや、ネストされたjavadocタグが含まれないものとして解釈されます。たとえば、ドキュメンテーション・コメント・テキスト{@literal a<B>c}は、生成されるHTMLページで未変更のままa<B>cと表示されます。つまり、<B>は太字として解釈されません。
• 新機能: {@code}タグは、リテラル・テキストをコード・フォントとして書式指定します。これは<code>{@literal}</code>と等価です。
• 新機能: {@value}インライン・タグが、{@value package.class#member label}のように、プログラム要素およびラベルの名前を受け付けるようになりました。そのため、任意のドキュメンテーション・コメントの中でこのタグを使用できます。(4764045、標準ドックレット)
• 新機能: Javadocタグではない@Deprecated注釈は5.0からの新機能で、プログラム要素を非推奨にするための@deprecatedタグに追加して使用します。「@Deprecated注釈」を参照してください。
• バグの修正: (リグレッション):@paramを修正して、パラメータ名(第1引数)が間違っていても、パラメータ名を出力するようにしました(1.3.1と同じ)。(4802275、標準ドックレット)
• バグの修正: (リグレッション) -tagタグを修正して、その名前にダッシュ「-」を含めることができるように戻しました(1.4.1と同じ)。(4920381、標準ドックレット)
• バグの修正: 最初の文に{@docRoot}リンクが含まれていても、単一ページのインデックスでリンクが壊れなくなりました。(4760191、標準ドックレット)
• バグの修正: {@inheritDoc}が含まれている最初の文の終わりを正しく判別するようになりました。(4767038、標準ドックレット、投票数4)
• バグの修正: {@docroot}タグを -bottomのテキストで使用しても、help-doc.htmlページでリンクが壊れないようになりました。(4851991、標準ドックレット)
• バグの修正: タグレットのコードを修正し、スタンドアロン・タグでインライン・タグを処理できるようにしました。(4654308、標準ドックレット)
• バグの修正: {@value}をカスタム・タグの中で使用しても、NullPointerExceptionが生成されなくなりました。(4821796、標準ドックレット)
• バグの修正: インライン・タグの中に、インライン・タグの一部ではない、ネストされた中カッコを記述できるようになりました。(4965490、ツール)
• バグの修正: @param、@return、および一部の@throwsタグが、コメントを正しく継承するようになりました。(4915434、標準ドックレット)
• バグの修正: 例外がチェックされる場合、@throwsドキュメントが自動で継承されるようになりました。(4947455、標準ドックレット)

リンク

• バグの修正: 継承されたコメントが、単にクラスにリンクするだけでなく、適切なメンバーに直接リンクするようになりました。(4368820、標準ドックレット)
• バグの修正: クラスが直接のメンバーを持たず、メンバーを継承している場合に、サマリーの見出しが欠落しないようになりました。(4904036、標準ドックレット)
• バグの修正: 最初の文の<a href>に相対リンクが含まれている場合、それがほかのページに表示されるときに、壊れたリンクを生成しないようになりました。(4460354、標準ドックレット)

  リンクに関連したその他のバグ修正については、「タグとタグレット」セクションにある{@docRoot}タグに関連した項目を参照してください。

ソース・ファイル・ドキュメント

• 新機能: package-info.javaは、ソース・ファイルにパッケージのコメントと注釈を保存するための予約名です。package-info.javaについては、前述の説明を参照してください。

生成されるAPI仕様

• 新機能: ジェネリック、列挙型、可変引数に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4421066、ツール)と標準ドックレット(4789689、標準ドックレット)に追加しました。
• 新機能: 注釈および注釈型に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4904495、ツール)と、標準ドックレット(4905985、標準ドックレット)に追加しました。
• 新機能: 読みやすくするために、long型の定数フィールドを小文字の「l」ではなく「L」として出力するようにしました。(4869993、ツール)
• 新機能: 読みやすくするために、long型のserialVersionUID値を小文字の「l」ではなく「L」として出力するようにしました。(4821483、標準ドックレット)
• 新機能: 「非推奨」リストの上端に目次を追加しました。(4927552、標準ドックレット)
• バグの修正: {@inheritDoc}が(1)スーパー・スーパーインタフェースから継承できない場合、または(2)スーパー・スーパーインタフェースから継承している場合に、ハング・アップすることがなくなりました。(4812240、標準ドックレット)
• バグの修正: 継承しているpublic以外のスーパー・クラスには言及しないようになりました。(4874845、標準ドックレット)
• バグの修正: 「定義:」および「オーバーライド:」のコメントを、外部的に参照しているクラスから継承するようになりました。(4857717、標準ドックレット)
• バグの修正: ドキュメントにおいて、package-privateクラスのメンバーからは継承しないようになりました。(4780441、標準ドックレット)
• バグの修正: メソッドの説明の順序が実行ごとに変動するということがなくなりました。(4885372、標準ドックレット)
• バグの修正: クラスBがインタフェースIを実装しているクラスAを拡張したものである場合、インタフェースIのドキュメントに、BがIを実装しているとドキュメント化するようにしました(「既知の実装クラスの一覧」セクション)。(4947464、標準ドックレット)
• バグの修正: あるメソッドが、オーバーライドしたメソッドからドキュメントを継承する場合に、そのメソッドとオーバーライドしたメソッドとで戻り値の型が違っているとき、メンバーのサマリーに正しい戻り値の型が記載されるようになりました。(4951228、標準ドックレット)
• バグの修正: 直列化された形式のページに、readObjectNoData()のドキュメントを生成するようになりました。(4770063、標準ドックレット)
• バグの修正: 名前のないパッケージが存在する場合に、そのパッケージについてもパッケージのサマリー・ページを生成するようになりました。(4774450、標準ドックレット)
• バグの修正: 名前のないパッケージの名前として、空の文字列を出力するのではなく、「名前なし(Unnamed)」と出力するようにしました。(4904075、標準ドックレット)
• バグの修正: 複数のインタフェースを拡張している場合に、継承したメソッドがすべてドキュメント化されるようになりました。(4933335、標準ドックレット)
• バグの修正: インタフェースのメソッドが「public」とマークされることがなくなりました。これは、実際にはバグではなく、単なる変更です。(4682448、標準ドックレット)
• バグの修正: コンストラクタのコメントが正しくインデントされるようにしました。(4904037、標準ドックレット)
• バグの修正: 生成されるファイルの中にpackages.htmlファイル(ファイル名は複数形)が含まれなくなりました。1.1以来、このファイルは使用されておらず、不要です。(4475679、標準ドックレット)
• バグの修正: メンバーのサマリーにある型パラメータが10文字より長い場合に、改行を追加して幅を縮めるようにしました。(4927167、標準ドックレット)

書式指定と無効なHTML

• バグの修正: 各<SCRIPT>タグと一緒に<NOSCRIPT>タグを出力するようにしました。(4855054、標準ドックレット)
• バグの修正: Internet Explorerでフレームを表示したとき、不必要な水平スクロール・バーが表示されなくなりました。(4852280、標準ドックレット)
• バグの修正: 改行を「\n」としてハードコードすることをやめました。(4938109、標準ドックレット)
• バグの修正: 定数値のサマリーで、クラス見出しの周囲に表の枠を追加しました。(4904025、標準ドックレット)
• バグの修正: 特定のHTMLソース・コメントを出力するかどうか、条件判断を追加しました。(4904038、標準ドックレット)

ナビゲーション・バー

• バグの修正: ナビゲーション・バーの最初の行に余分な列を表示しないようになりました。(4664607、標準ドックレット、投票数1)
• バグの修正: パッケージを1つだけドキュメント化したときにも、パッケージ・リンクがアクティブになるようにしました。(4689286、標準ドックレット)
• バグの修正: 「前のクラス」および「次のクラス」リンクをクリックしたとき、現在のパッケージにあるすべてのインタフェースおよびすべてのクラスを順番に移動できるようにしました。(4131628、標準ドックレット)

Accessibility

• バグの修正: 表の見出しに

  . (4905786、標準ドックレット) バグの修正: inherit.gifの代替テキストの末尾に、欠落していた空白文字を追加しました。(4956908、標準ドックレット) Javadocの実行 バグの修正: ソース・ファイルが、間違ったディレクトリにある別のソース・ファイルにリンクしている場合でも、InvocationTargetExceptionを受け取らないようになりました。(4835749、標準ドックレット) バグの修正: (リグレッション)内部クラスで問題が起きないようになりました(1.4.1では正常に動作していた)。(4843578、ツール) エラー・メッセージ、警告メッセージ、ステータス・メッセージ 新機能: voidメソッドに@returnタグがある場合に、警告を出すようになりました。(4490068、標準ドックレット) 新機能: 生成先ディレクトリを新しく作成するときに、メッセージを表示するようにしました。(4657239、標準ドックレット) バグの修正: BreakIteratorの警告を表示しないようにしました。詳細は、前述の説明を参照してください。(4959985、ツール) バグの修正: 「first sentence」警告がstderrとstdoutに分割されることがなくなりました。(4753853、ツール) バグの修正: DocLocale.javaの実装を修正して、正しく翻訳できるようにしました。(4780921、ツール) バグの修正: オプションのエラーを出力するために、MessageRetrieverではなく、DocletErrorReporterを使用するようにしました。(4927928、標準ドックレット) バグの修正: package-listファイルが欠落しているというメッセージが実際には「警告」である場合、「エラー」として出力しないようにしました。(4625883、標準ドックレット) ドックレットAPI 新機能: ジェネリック、列挙型、可変引数に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4421066、ツール)と標準ドックレット(4789689、標準ドックレット)に追加しました。 新機能: 注釈および注釈型に対するサポートを、javadocツールのフロントエンド(ドックレットAPI)(4904495、ツール)と、標準ドックレット(4905985、標準ドックレット)に追加しました。 新機能: ドックレットを作成するときに対象としたJavaソース・コードのバージョンを判別するための、Doclet.languageVersionメソッドを追加しました。(4909767、ツール) 標準ドックレットの実装 バグの修正: 標準ドックレットをエミュレートするドックレットとのコード共有を最大限にするため、標準ドックレットを実装し直しました。(4638723、標準ドックレット)