jdk.javadoc.doclet (Java SE 9 & JDK 9 )

ドックレット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とみなされます。含まれる要素は文書化される。

Options

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`	パッケージ	パッケージ	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の型が代わりに使用されます。

次の表は、古い型からその置換型へのマッピングのガイドです。場合によっては、直接の同等物はありません。

古い型を新しい型にマッピングするためのガイド
旧型	新規タイプ
AnnotatedType	javax.lang.model.type.Type
AnnotationDesc	javax.lang.model.element.AnnotationMirror
AnnotationDesc.ElementValuePair	javax.lang.model.element.AnnotationValue
AnnotationTypeDoc	javax.lang.model.element.TypeElement
AnnotationTypeElementDoc	javax.lang.model.element.ExecutableElement
AnnotationValue	javax.lang.model.element.AnnotationValue
ClassDoc	javax.lang.model.element.TypeElement
ConstructorDoc	javax.lang.model.element.ExecutableElement
Doc	javax.lang.model.element.Element
DocErrorReporter	jdk.javadoc.doclet.Reporter
Doclet	jdk.javadoc.doclet.Doclet
ExecutableMemberDoc	javax.lang.model.element.ExecutableElement
FieldDoc	javax.lang.model.element.VariableElement
LanguageVersion	javax.lang.model.SourceVersion
MemberDoc	javax.lang.model.element.Element
MethodDoc	javax.lang.model.element.ExecutableElement
PackageDoc	javax.lang.model.element.PackageElement
Parameter	javax.lang.model.element.VariableElement
ParameterizedType	javax.lang.model.type.DeclaredType
ParamTag	com.sun.source.doctree.ParamTree
ProgramElementDoc	javax.lang.model.element.Element
RootDoc	jdk.javadoc.doclet.DocletEnvironment
SeeTag	com.sun.source.doctree.LinkTree com.sun.source.doctree.SeeTree
SerialFieldTag	com.sun.source.doctree.SerialFieldTree
SourcePosition	com.sun.source.util.SourcePositions
タグ	com.sun.source.doctree.DocTree
ThrowsTag	com.sun.source.doctree.ThrowsTree
型	javax.lang.model.type.Type
TypeVariable	javax.lang.model.type.TypeVariable
WildcardType	javax.lang.model.type.WildcardType

導入されたバージョン:: 9
関連項目:: Doclet, DocletEnvironment

インタフェースのサマリー
インタフェース	説明
Doclet	ユーザー・ドックレットは、「パッケージの説明」で説明されているように、このインタフェースを実装する必要があります。
Doclet.Option	Docletが使用するオプション名、別名、パラメータ、および記述のカプセル化。
DocletEnvironment	ドックレットを1回呼び出す操作環境を表します。
Reporter	このインタフェースは、エラー、警告、および通知のレポートを提供します。
Taglet	`standard doclet`などのドックレットでサポートされているカスタム・タグ・レットのインタフェース。

クラスのサマリー
クラス	説明
StandardDoclet	このドックレットは、指定されたモジュール、パッケージ、および型のHTML形式のドキュメントを生成します。

列挙型のサマリー
列挙型	説明
Doclet.Option.Kind	オプションの種類。
DocletEnvironment.ModuleMode
Taglet.Location	タグが使用されるロケーションの種類。

パッケージ jdk.javadoc.doclet

用語

Options

古いオプションとのやりとり。

例

移行ガイド