モジュール 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 {
private Reporter reporter;
private PrintWriter stdout;
@Override
public void init(Locale locale, Reporter reporter) {
reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
this.reporter = reporter;
stdout = reporter.getStandardWriter();
}
public void printElement(DocTrees trees, Element e) {
DocCommentTree docCommentTree = trees.getDocCommentTree(e);
if (docCommentTree != null) {
stdout.println("Element (" + e.getKind() + ": "
+ e + ") has the following comments:");
stdout.println("Entire body: " + docCommentTree.getFullBody());
stdout.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) {
stdout.println("Overview html: " + docCommentTree.getFullBody());
}
} catch (IOException missing) {
reporter.print(Kind.ERROR, "No overview.html found.");
}
for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {
stdout.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 = List.of(
"--overview-file",
"-overviewfile",
"-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 Set.of(options);
}
@Override
public SourceVersion getSupportedSourceVersion() {
// support the latest release
return SourceVersion.latest();
}
}
このドックレットは、次のようなコマンドラインで呼び出すことができます:
javadoc -docletpath doclet-classes \
-doclet Example \
--overview-file overview.html \
--source-path source-location \
source-location/Example.java
移行ガイド
古いcom.sun.javadoc APIの型の多くは、このパッケージに相当するものがありません。 代わりに、javax.lang.modelおよびcom.sun.source APIの型が代わりに使用されます。
次の表は、古い型からその置換型へのマッピングのガイドです。 場合によっては、直接の同等物はありません。
- 導入されたバージョン:
- 9
- 関連項目:
-
クラス説明ユーザー・ドックレットは、「パッケージの説明」で説明されているように、このインタフェースを実装する必要があります。Docletが使用するオプション名、別名、パラメータ、および記述のカプセル化。オプションの種類。ドックレットを1回呼び出す操作環境を表します。モジュール・ドキュメントの詳細レベルを指定するモード。診断およびその他のメッセージをレポートするためのインタフェース。このドックレットは、指定されたモジュール、パッケージ、および型のHTML形式のドキュメントを生成します。
standard docletなどのドックレットでサポートされているカスタム・タグ・レットのインタフェース。タグが使用されるロケーションの種類。