モジュール jdk.javadoc
パッケージjdk.javadoc.doclet
パッケージjdk.javadoc.doclet
ドックレットAPIは、言語モデルAPIおよびコンパイラ・ツリーAPIとともに、クライアントがソースに埋め込まれたAPIコメントを含むプログラムおよびライブラリのソース・レベルの構造を検査できる環境を提供します。
standard docletは、HTML形式のドキュメントを生成するために使用できます。 ユーザー定義tagletsがサポートされており、これを使用して、ドキュメント・コメント内のユーザー定義タグ用にカスタマイズされた出力を生成できます。
ノート: このパッケージの宣言は、古いパッケージcom.sun.javadocの宣言を置き換えます。 古い型から新しい型へのマッピングの詳細は、「移行ガイド」を参照してください。
ドックレットはjavadocによって起動され、このAPIを使用してプログラム情報をファイルに書き込むことができます。 たとえば、標準ドックレットはデフォルトで起動され、HTMLドキュメントが生成されます。
呼び出しはインタフェースDocletによって定義されます。 -- runインタフェース・メソッドは、エントリ・ポイントを定義します。
public boolean run(DocletEnvironment environment)
DocletEnvironmentインスタンスは、ドックレットの初期化に使用される環境を保持します。 この環境からは、他のすべての情報をelementsの形式で抽出できます。 さらに、Language Model APIで説明されているAPIおよびユーティリティを使用して、要素およびタイプを問い合せることができます。
用語
- 選択済
- 要素がselectedであるとみなされるのは、「選択コントロール」 allowの場合です。 (合成要素は選択されないことに注意してください。)
- 指定された
- ユーザーが指定した要素のセットは「指定された要素」とみなされます。 指定された要素は、ドキュメント化する「含まれる要素」を決定するための出発点となります。
- 含む
- 要素がselectedであり、次のいずれかがtrueの場合、要素はincludedであるとみなされます:
- 要素はspecified、または
- 要素にspecified要素が含まれているか、または
- 要素はspecified要素で囲まれます。
オプション
Javadoc 「選択制御」は、次のようにこれらのオプションで指定できます:--show-members:valueおよび--show-types:valueは、次の値を使用してメンバーをフィルタするために使用できます:- public - public要素のみを考慮
- protected - public要素とprotected要素を考慮
- package -- public、protectedおよびpackage private要素を考慮
- プライベート - すべての要素を考慮
--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
| パブリック | パブリック | エクスポート | api | |
-protected
| protected | protected | エクスポート | api | |
-package
| package | package | all | all | |
-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
- 関連項目:
-
クラス説明ユーザー・ドックレットは、「パッケージの説明」の説明に従って、このインタフェースを実装する必要があります。ドックレットで使用されるオプション名、別名、パラメータおよび説明のカプセル化。オプションの種類。ドックレットの1回の呼出しの操作環境を表します。モジュール・ドキュメントの詳細レベルを指定するモード。診断およびその他のメッセージをレポートするためのインタフェース。このドックレットは、指定されたモジュール、パッケージおよびタイプに対してHTML形式のドキュメントを生成します。
standard docletなどのドックレットでサポートされているカスタム・タグ・レットのインタフェース。タグを使用できるロケーションの種類。