1. JavaDocガイド
  2. JavaDocツール

1 JavaDocツール

JavaDocツールは、ドックレットと呼ばれるプラガブル・バック・エンドで分析できるフォームに、Javaソース・ファイルとクラス・ファイルを読み込むプログラムです。

JavaDocツールを使用するには、次のことを行う必要があります:

  • Javaドキュメント・コメントを含むソース・コードを使用します。

  • ドックレットを指定してjavadocツールを実行し、ドキュメント・コメントおよびその他の特別なタグを分析します。コマンドでドックレットを指定しない場合、デフォルトで標準ドックレットが使用されます。

生成された任意のファイルのコンテンツは、ドックレットに固有です。標準ドックレットではHTML出力が生成されますが、別のドックレットでは、スペルミスのある単語や文法的エラーのレポートなど、その他の出力を生成することが可能です。

標準以外のドックレットを指定した場合、そのドックレットや生成されたファイル(存在する場合)の操作には、このガイドの説明が当てはまらないことがあります。

このガイドの説明に加えて、JavaDocツールのユーザーおよびコンテンツ開発者は、次のドキュメントを使用する必要があります:

  • コンテンツAPIドキュメントの作成者向け: 標準ドックレットのドキュメンテーション・コメント・タグ仕様

  • APIドキュメントを生成するためのツールを実行するユーザー向け: javadocコマンド

  • APIドキュメントのエンドユーザーの読者向け: 生成されたドキュメントのヘルプ・ページ。ヘルプ・ページのコンテンツは、APIのコンテンツおよびドキュメントの生成に使用されるコマンド向けにカスタマイズされます。たとえば、Java SEおよびJDK API仕様のヘルプ・ページを参照してください。

JavaDocの機能

JavaDocの機能では、サンプル・コード、検索、サマリー・ページ、モジュール・システム、ドックレットAPI、HTMLサポートおよびDocLintのサポートが強化されています。

サンプル・コードの拡張サポート

標準ドックレットでは、JEP 413: Java APIドキュメントのコード・スニペットに記載されているとおり、サンプル・コードのサポートが強化されています。詳細は、スニペットのためのプログラマーズ・ガイドを参照してください。

検索

JavaDocツールにより標準ドックレットが実行されると出力が生成されますが、この出力により、生成されたAPIドキュメントに定義されている要素や追加のキー・フレーズを、生成されたドキュメントでユーザーが検索できるようになります。検索結果には、検索文字列内の任意の位置の一致する文字が含まれます。検索機能では、ユーザーの選択に基づいてページ・リダイレクションを行うこともできます。

ノート:

検索機能ではJavaScriptが使用されます。ブラウザでJavaScriptを無効にすると、検索機能を使用できなくなります。ただし、検索機能のすべての情報は、生成されるどのAPIドキュメントにも存在するA-Zの索引でも参照できます。A-Zの索引はプレーンHTMLで、JavaScriptを使用する必要はありません。検索機能の使用方法の詳細は、Javadocの検索仕様を参照してください。

サマリー・ページ

標準ドックレットでは、APIに含まれる個々の宣言の詳細な説明に基づいて、様々な追加のサマリー・ページが生成される場合があります。これらのページには、新しいAPI、非推奨のAPI、定数値および直列化された形式に関する情報が記載されています。これらのページへのリンクは、各ページの上部にあるメインのナビゲーション・バーまたはA-Zの索引にあります。

モジュール・システム

javadocツールはモジュール宣言内のドキュメンテーション・コメントをサポートしています。一部のJavaDocコマンド行オプションでは、ドキュメント化する一連のモジュールを指定し、ドキュメント化するモジュールのサマリー・ページを生成できます。詳細は、javadocコマンドを参照してください。

ドックレットAPI

ドックレットAPIは、最新の言語機能をすべてサポートしています。詳細は、モジュール jdk.javadocを参照してください。

HTMLサポート

標準ドックレットでは、最新のWeb標準を使用してドキュメントが生成されます。

ノート:

標準ドックレットでは、ドキュメンテーション・コメントのHTMLエラーは修復も修正もされません。HTMLエラーは、準拠チェッカにより行われる、生成されたAPIドキュメントの検証が失敗する原因になることがあります。

DocLint

DocLintは、JavaDocツールおよびJDK Javaコンパイラjavacで提供される機能で、作成者の意図に沿わない出力になる可能性があるドキュメンテーション・コメントの問題を検出してレポートします。問題とは、コメントの欠落、宣言されていないアイテムへの参照(スペル・ミスによるもの)、アクセシビリティのエラー、不適切な形式のHTMLおよび構文エラーです。各問題の重大度に応じて、警告またはエラーとしてレポートされます。DocLintの詳細は、javadocコマンドを参照してください。

ノート:

DocLintなどの機能は問題の検出に便利ですが、生成されたAPIドキュメントを作成者が必ずチェックして校正し、意図どおりであることを確認してください。