モジュール jdk.javadoc
パッケージ 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およびユーティリティを使用して、要素および型を問い合せることができます。
用語
- 選択済
- 選択コントロールが許可されている場合、要素は選択されているとみなされます。 (合成要素は選択されません。)
- 指定
- ユーザーが指定した要素のセットは、指定した要素とみなされます。 指定されたエレメントは、文書化する含まれるエレメントを決定するための開始点となります。
- 含む
- エレメントが includedと見なされるのは、specifiedエレメントが含まれている場合、または specifiedエレメントで囲まれていて、selectedエレメントである場合です。 含まれる要素が文書化されます。
オプション
Javadocの選択制御は、次のオプションで指定できます。--show-members:valueおよび--show-types:valueを使用して、次の値でメンバーをフィルタできます。- public -- public要素のみを考慮します。
- protected -- public要素およびprotected要素を考慮します。
- package -- public、protected、パッケージprivate要素を考慮します
- private -- すべての要素を考慮します
--show-packages:value"exported"または"all"を使用すると、エクスポートされたパッケージまたはモジュール内のすべてのパッケージのみを考慮できます。--show-module-contents:valueを使用すると、モジュール宣言でのレベルを記述できます。 値"API"はAPIレベルのドキュメントを示し、"all"は詳細なドキュメントを示します。
--moduleは、指定されたモジュールをドキュメント化します。--expand-requires:valueは、モジュール依存関係の一部またはすべてを含めることで、ドキュメント化されるモジュールのセットを拡張します。 値は次のいずれかです。- transitive -- コマンドラインで明示的に指定された各モジュールは、その推移的依存関係のクローズを含むように展開されます。
- 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 | |
修飾要素名は、その前に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,DocletEnvironment
-
インタフェースのサマリー インタフェース 説明 Doclet ユーザー・ドックレットは、パッケージの説明の説明に従って、このインタフェースを実装する必要があります。Doclet.Option ドックレットで使用されるオプション名、別名、パラメータおよび説明のカプセル化。DocletEnvironment ドックレットの1回の呼出しのオペレーティング環境を表します。Reporter このインタフェースは、エラー、警告および通知のレポートを提供します。Taglet standard docletなどのドックレットでサポートされているカスタム・タグレットのインタフェース。 -
クラスのサマリー クラス 説明 StandardDoclet このドックレットは、指定されたモジュール、パッケージおよびタイプについてHTML形式のドキュメントを生成します。 -
列挙型のサマリー 列挙型 説明 Doclet.Option.Kind オプションの種類。DocletEnvironment.ModuleMode Taglet.Location タグを使用できる場所の種類。