モジュール jdk.javadoc
パッケージjdk.javadoc.doclet
パッケージjdk.javadoc.doclet
ドックレットAPIは、言語モデルAPIおよびコンパイラ・ツリーAPIと共に、クライアントがソースに埋め込まれたAPIコメントを含むプログラムおよびライブラリのソース・レベルの構造を検査できるようにする環境を提供します。
standard doclet
は、HTML形式のドキュメントを生成するために使用できます。 これは、ユーザー定義のtaglets
をサポートしています。taglets
は、ドキュメンテーション・コメントのユーザー定義タグの出力をカスタマイズするために使用できます。
ノート: このパッケージの宣言は、古いパッケージcom.sun.javadoc
の宣言を置き換えます。 古い型から新しい型へのマッピングの詳細については、「移行ガイド」を参照してください。
ドックレットはjavadocによって呼び出され、このAPIを使用してプログラム情報をファイルに書き出すことができます。 たとえば、標準ドックレットはデフォルトで呼び出され、HTMLドキュメントを生成します。
呼び出しはインタフェースDoclet
によって定義されます。-- run
インタフェース・メソッドは、エントリ・ポイントを定義します。
public boolean run(DocletEnvironment environment)
DocletEnvironment
インスタンスは、ドックレットが初期化される環境を保持します。 この環境から、他のすべての情報をelements
の形式で抽出することができます。 Language Model API
で記述されているAPIとユーティリティを使用して要素と型を問い合わせることができます。
用語
- が選択されました
- 「選択コントロール」 allowが文書化される場合、要素はselectedとみなされます。 (合成要素は決して選択されないことに注意してください。)
- 指定された
- ユーザーが指定した要素のセットは「指定された要素」とみなされます。 指定された要素は、文書化される「含まれる要素」を決定するための開始点を提供します。
- 含まれています
- 要素がspecified要素の場合はspecified、specified要素の場合はspecified、selected要素の場合は要素はincludedとみなされます。 含まれる要素は文書化されます。
オプション
Javadoc 「選択制御」は、次のようにこれらのオプションで指定できます:--show-members:value
および--show-types:value
を使用して、次の値を使用してメンバーをフィルタリングできます:- public - public要素のみを考慮
- protected - public要素とprotected要素を考慮
- package -- パブリック、プロテクト、パッケージ・プライベート要素を考慮
- プライベート- すべての要素を考慮
--show-packages:value
"exported"または"all"は、エクスポートされたパッケージまたはモジュール内のすべてのパッケージのみを検討するために使用できます。--show-module-contents:value
を使用して、モジュール宣言時のレベルを指定して文書化することができます。 "api"の値はAPIレベルのドキュメントを示し、"all"は詳細なドキュメントを示します。
--module
は、指定されたモジュールを文書化します。--expand-requires:value
は、モジュールの依存関係の一部またはすべてを含めることによって、文書化されるモジュールのセットを拡張します。 値は次のいずれかです:- 推移的- コマンドラインで明示的に指定された各モジュールは、推移的な依存関係のクロージャを含むように展開されます
- all -- コマンドライン上で明示的に指定された各モジュールは、推移的な依存関係のクロージャを含むように展開されます。また、すべての直接的な依存関係
packagenames
を使用してパッケージを指定できます。-subpackages
は、パッケージを再帰的にロードするために使用できます。-exclude
は、パッケージ・ディレクトリを除外するために使用できます。sourcefilenames
を使用してソース・ファイル名を指定できます。
古いオプションとのやりとり。
新しい--show-*
オプションは、古いオプション-public
、-protected
、-package
、-private
のより詳細な置き換えを提供します。 あるいは、古いオプションは、以下で説明するように、新しいオプションの組み合わせのための短い形式として引き続き使用できます:
以前のオプション | 新しいオプションでこれらの値に相当 | ||||
---|---|---|---|---|---|
--show-members
| --show-types
| --show-packages
| --show-module-contents
| ||
-public
| public | public | exported | api | |
-protected
| protected | protected | exported | api | |
-package
| package | package | all | all | |
-private
| private | private | all | all |
qualified要素名は、java.lang.String
のように、その前にパッケージ名が付いた要素名です。 修飾されていない名前には、パッケージ名が含まれません(String
など)。
例
以下は、オプションをサポートする、クラスとそのメンバーの情報を表示するサンプル・ドックレットです。// note imports deleted for clarity public class Example implements Doclet { Reporter reporter; @Override public void init(Locale locale, Reporter reporter) { reporter.print(Kind.NOTE, "Doclet using locale: " + locale); this.reporter = reporter; } public void printElement(DocTrees trees, Element e) { DocCommentTree docCommentTree = trees.getDocCommentTree(e); if (docCommentTree != null) { System.out.println("Element (" + e.getKind() + ": " + e + ") has the following comments:"); System.out.println("Entire body: " + docCommentTree.getFullBody()); System.out.println("Block tags: " + docCommentTree.getBlockTags()); } } @Override public boolean run(DocletEnvironment docEnv) { reporter.print(Kind.NOTE, "overviewfile: " + overviewfile); // get the DocTrees utility class to access document comments DocTrees docTrees = docEnv.getDocTrees(); // location of an element in the same directory as overview.html try { Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next(); DocCommentTree docCommentTree = docTrees.getDocCommentTree(e, overviewfile); if (docCommentTree != null) { System.out.println("Overview html: " + docCommentTree.getFullBody()); } } catch (IOException missing) { reporter.print(Kind.ERROR, "No overview.html found."); } for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) { System.out.println(t.getKind() + ":" + t); for (Element e : t.getEnclosedElements()) { printElement(docTrees, e); } } return true; } @Override public String getName() { return "Example"; } private String overviewfile; @Override public Set<? extends Option> getSupportedOptions() { Option[] options = { new Option() { private final List<String> someOption = Arrays.asList( "-overviewfile", "--overview-file", "-o" ); @Override public int getArgumentCount() { return 1; } @Override public String getDescription() { return "an option with aliases"; } @Override public Option.Kind getKind() { return Option.Kind.STANDARD; } @Override public List<String> getNames() { return someOption; } @Override public String getParameters() { return "file"; } @Override public boolean process(String opt, List<String> arguments) { overviewfile = arguments.get(0); return true; } } }; return new HashSet<>(Arrays.asList(options)); } @Override public SourceVersion getSupportedSourceVersion() { // support the latest release return SourceVersion.latest(); } }
このドックレットは、次のようなコマンドラインで呼び出すことができます:
javadoc -doclet Example \ -overviewfile overview.html \ -sourcepath source-location \ source-location/Example.java
移行ガイド
古いcom.sun.javadoc
APIの型の多くは、このパッケージに相当するものがありません。 代わりに、javax.lang.model
およびcom.sun.source
APIの型が代わりに使用されます。
次の表は、古い型からその置換型へのマッピングのガイドです。 場合によっては、直接の同等物はありません。
- 導入されたバージョン:
- 9
- 関連項目:
-
クラス説明ユーザー・ドックレットは、「パッケージの説明」で説明されているように、このインタフェースを実装する必要があります。Docletが使用するオプション名、別名、パラメータ、および記述のカプセル化。オプションの種類。ドックレットを1回呼び出す操作環境を表します。モジュール・ドキュメントの詳細レベルを指定するモード。診断およびその他のメッセージをレポートするためのインタフェース。このドックレットは、指定されたモジュール、パッケージ、および型のHTML形式のドキュメントを生成します。
standard doclet
などのドックレットでサポートされているカスタム・タグ・レットのインタフェース。タグが使用されるロケーションの種類。