モジュール jdk.javadoc

パッケージ 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要素の場合はspecifiedspecified要素の場合はspecifiedselected要素の場合は要素は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 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の型が代わりに使用されます。

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

古い型を新しい型にマッピングするためのガイド
旧型新規タイプ
AnnotatedType javax.lang.model.type.TypeMirror
AnnotationDesc javax.lang.model.element.AnnotationMirror
AnnotationDesc.ElementValuePairjavax.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
Tag com.sun.source.doctree.DocTree
ThrowsTag com.sun.source.doctree.ThrowsTree
Type javax.lang.model.type.TypeMirror
TypeVariable javax.lang.model.type.TypeVariable
WildcardType javax.lang.model.type.WildcardType

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