このドキュメントでは、バージョン 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>{@literal}</code> と等価です。
- タグ {@value arg}: このインラインタグは、次のように、プログラム要素名を受け付けるようになりました。
{@value package.class#field}。このような表記は、定数フィールドのドキュメンテーションコメント内だけでなく、任意のドキュメンテーションコメント内で使用できます。(4764045、標準ドックレット、投票数 2)
- 標準ドックレットを再実装: 標準ドックレットおよび 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)
すべてのバグ修正については、下に掲載します。
既知のバグ
Javadoc 5.0 には、ハングアップやクラッシュを引き起こす既知のバグがあります。その一覧は、「Bug Parade」のデータベースで見ることができます。詳細については、Javadoc FAQ を参照してください。
カスタムドックレットとの非互換性
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 ドキュメントで壊れていたリンクの修正など)。
コマンド行オプション
- 新機能: -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、標準ドックレット)
- バグ修正: (リグレッション): @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、標準ドックレット)
リンク
生成される API 仕様
- 新機能: 汎用型、列挙型、変数引数に対するサポートを、javadoc ツールのフロントエンド (ドックレット API) (4421066、ツール) と、標準ドックレット (4789689、標準ドックレット) に追加しました。
- 新機能: 注釈および注釈型に対するサポートを、javadoc ツールのフロントエンド (ドックレット API) (4904495、ツール) と、標準ドックレット (4905985、標準ドックレット) に追加しました。
- 新機能: 読みやすくするために、long 型の定数フィールドを小文字の「l」ではなく「L」として出力するようにしました。(4869993、ツール)
- 新機能: 読みやすくするために、long 型の serialVersionUID 値を小文字の「l」ではなく「L」として出力するようにしました。(4821483、標準ドックレット)
- 新機能: 「推奨されていない API」リストの上端に目次を追加しました。(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> ではなく <th> を使用するようにしました。(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、標準ドックレット)
