Javadoc 5.0 の新機能
このドキュメントでは、バージョン 1.4.2 から 5.0 (以前の名称は 1.5.0) への移行で Javadoc ツールに対して行われた変更について説明します。
掲載されている変更点には、バグ番号と、その修正が Javadoc ツールのフロントエンドに対するもの (「ツール」) であるか、または標準ドックレットに対するもの (「標準ドックレット」) であるかが示されています。「リグレッション」という用語は、1.3.x では動作していたのに、1.4.x で動作しなくなり、5.0 で修正された機能に対して使用されます。
主要な新機能
- ジェネリック、列挙型、可変引数: これらの新しい言語機能に対するサポートを、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、標準ドックレット)
リンク
ソースファイルドキュメント
- 新機能:
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
- バグの修正:テーブルの見出しに <td> ではなく
. (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、標準ドックレット)
|