<?xml version="1.0" encoding="UTF-8"?><diffreport><diff><div class="flex-box"><header role="banner" class="flex-header"><div style="padding: 6px; text-align: center; font-size: 80%; font-family: DejaVu Sans, Arial, Helvetica, sans-serif; font-weight: normal;">This specification is not final and is subject to change. Use is subject to <a href="https://www.oracle.com/java/javase/terms/license/java17speclicense.html">license terms </a>.              </div><nav role="navigation"><div class="top-nav" id="navbar-top"><div class="skip-nav"><a href="#skip-navbar-top" title="Skip navigation links">Skip navigation links  </a></div><div class="about-language"><div style="margin-top: 9px;"><strong>Java SE 17 &amp; JDK 17     </strong><br/><strong>DRAFT 17-internal+0-adhoc.jlahoda.jdk </strong></div></div><ul id="navbar-top-firstrow" class="nav-list" title="Navigation"><li><a href="../../../../index.html">Overview</a></li><li><a href="../../../module-summary.html">Module</a></li><li class="nav-bar-cell1-rev">Package</li><li>Class</li><li><a href="package-use.html">Use</a></li><li><a href="package-tree.html">Tree</a></li><li><a href="../../../../deprecated-list.html">Deprecated</a></li><li><a href="../../../../preview-list.html"><span class="diff-html-added">Preview</span></a></li><li><a href="../../../../index-files/index-1.html">Index</a></li><li><a href="../../../../help-doc.html#package">Help</a></li></ul></div><div class="sub-nav"><div><ul class="sub-nav-list"><li>Package: </li><li><a href="#package-description">Description</a> | </li><li>Related Packages |  </li><li><a href="#class-summary">Classes and Interfaces  </a></li></ul></div><div class="nav-list-search"><label for="search-input">SEARCH:</label><input type="text" id="search-input" value="search" disabled="disabled"/><input type="reset" id="reset-button" value="reset" disabled="disabled"/></div></div><span class="skip-nav" id="skip-navbar-top"/></nav></header><div class="flex-content"><main role="main"><div class="header"><div class="sub-title"><span class="module-label-in-package">Module</span> <a href="../../../module-summary.html">jdk.javadoc</a></div><h1 title="Package jdk.javadoc.doclet" class="title">Package jdk.javadoc.doclet </h1></div><hr/><div class="package-signature">package <span class="element-name">jdk.javadoc.doclet</span> </div><section class="package-description" id="package-description"><div class="block">The Doclet API provides an environment which, in conjunction with the Language Model API and Compiler Tree API, allows clients to inspect the source-level structures of programs and libraries, including API comments embedded in the source.<p> The <a href="StandardDoclet.html" title="class in jdk.javadoc.doclet"><code>standard doclet </code></a> can be used to generate HTML-formatted documentation. It supports user-defined <a href="Taglet.html" title="interface in jdk.javadoc.doclet"><code>taglets</code></a>, which can be used to generate customized output for user-defined tags in documentation comments.                           </p><p style="font-style: italic"><b>Note:</b> The declarations in this package supersede those in the older package <code>com.sun.javadoc</code>. For details on the mapping of old types to new types, see the <a href="#migration">Migration Guide </a>.                          </p><p> Doclets are invoked by javadoc and this API can be used to write out program information to files. For example, the standard doclet is invoked by default, to generate HTML documentation.                               </p><p> The invocation is defined by the interface <a href="Doclet.html" title="interface in jdk.javadoc.doclet"><code>Doclet</code></a> -- the <a href="Doclet.html#run(jdk.javadoc.doclet.DocletEnvironment)"><code>run</code></a> interface method, defines the entry point.<pre>
    public boolean <b>run</b>(DocletEnvironment environment)
 </pre> The <a href="DocletEnvironment.html" title="interface in jdk.javadoc.doclet"><code>DocletEnvironment</code></a> instance holds the environment that the doclet will be initialized with. From this environment all other information can be extracted, in the form of <a href="../../../../java.compiler/javax/lang/model/element/Element.html" title="interface in javax.lang.model.element"><code>elements</code></a>. One can further use the APIs and utilities described by <a href="../../../../java.compiler/javax/lang/model/package-summary.html"><code>Language Model API  </code></a> to query Elements and Types.                                                            </p><p><a id="terminology"/></p><h2>Terminology</h2><dl><dt><a id="selected"/>Selected</dt><dd>An element is considered to be <em>selected</em>, if the <em>selection controls </em><a href="#options">allow</a> it to be documented. (Note that synthetic elements are never selected.)                    </dd><dt><a id="specified"/>Specified</dt><dd>The set of elements specified by the user are considered to be <em>specified elements </em>. Specified elements provide the starting points for determining the <em>included elements </em> to be documented.                         </dd><dt><a id="included"/>Included</dt><dd>An element is considered to be <em>included</em>, if it is <em>specified</em> if it contains a <em>specified</em> element, or it is enclosed in a <em>specified</em> element, and is <em>selected</em>. Included elements will be documented.                                </dd></dl><p><a id="options"/></p><h2>Options</h2> Javadoc <em>selection control </em> can be specified with these options as follows:<ul><li><code>--show-members:value</code> and <code>--show-types:value</code> can be used to filter the members, with the following values:<ul><li> public -- considers only public elements      </li><li> protected -- considers public and protected elements       </li><li> package -- considers public, protected and package private elements         </li><li> private -- considers all elements     </li></ul>             </li><li><code>--show-packages:value</code> "exported" or "all" can be used to consider only exported packages or all packages within a module.                 </li><li><code>--show-module-contents:value</code> can be used to specify the level at module declarations could be documented. A value of "api" indicates API level documentation, and "all" indicates detailed documentation.                          </li></ul> The following options can be used to specify the elements to be documented:<ul><li><code>--module</code> documents the specified modules.    </li><li><code>--expand-requires:value</code> expand the set of modules to be documented by including some or all of the modules dependencies. The value may be one of:<ul><li> transitive -- each module specified explicitly on the command line is expanded to include the closure of its transitive dependencies                    </li><li> all -- each module specified explicitly on the command line is expanded to include the closure of its transitive dependencies, and also all of its direct dependencies                           </li></ul> By default, only the specified modules will be considered, without expansion of the module dependencies.                                      </li><li><code>packagenames</code> can be used to specify packages.      </li><li><code>-subpackages</code> can be used to recursively load packages.       </li><li><code>-exclude</code> can be used exclude package directories.      </li><li><code>sourcefilenames</code> can be used to specify source file names.        </li></ul><p><a id="legacy-interactions"/></p><h3>Interactions with older options.   </h3> The new <code>--show-*</code> options provide a more detailed replacement for the older options <code>-public</code>, <code>-protected</code>, <code>-package</code>, <code>-private</code>. Alternatively, the older options can continue to be used as shorter forms for combinations of the new options, as described below:<table class="striped"><caption>Short form options mapping   </caption><thead><tr><th rowspan="2" scope="col" style="vertical-align:top"> Older option  </th><th colspan="5" scope="col" style="border-bottom: 1px solid black"> Equivalent to these values with the new option        </th></tr><tr><th scope="col"><code>--show-members</code></th><th scope="col"><code>--show-types</code></th><th scope="col"><code>--show-packages</code></th><th scope="col"><code>--show-module-contents</code></th></tr></thead><tbody><tr><th scope="row"><code>-public</code></th><td>public</td><td>public</td><td>exported</td><td>api</td></tr><tr><th scope="row"><code>-protected</code></th><td>protected</td><td>protected</td><td>exported</td><td>api</td></tr><tr><th scope="row"><code>-package</code></th><td>package</td><td>package</td><td>all</td><td>all</td></tr><tr><th scope="row"><code>-private</code></th><td>private</td><td>private</td><td>all</td><td>all</td></tr></tbody></table><p><a id="qualified"/> A <em>qualified</em> element name is one that has its package name prepended to it, such as <code>java.lang.String</code>. A non-qualified name has no package name, such as <code>String</code>.                           </p><p><a id="example"/></p><h2>Example</h2> The following is an example doclet that displays information of a class and its members, supporting an option.<pre>
 // 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&lt;? extends Option&gt; getSupportedOptions() {
        Option[] options = {
            new Option() {
                private final List&lt;String&gt; 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&lt;String&gt; getNames() {
                    return someOption;
                }

                @Override
                public String getParameters() {
                    return "file";
                }

                @Override
                public boolean process(String opt, List&lt;String&gt; arguments) {
                    overviewfile = arguments.get(0);
                    return true;
                }
            }
        };
        return new HashSet&lt;&gt;(Arrays.asList(options));
    }

    @Override
    public SourceVersion getSupportedSourceVersion() {
        // support the latest release
        return SourceVersion.latest();
    }
 }
 </pre><p> This doclet can be invoked with a command line, such as:<pre>
     javadoc -doclet Example \
       -overviewfile overview.html \
       -sourcepath source-location \
       source-location/Example.java
 </pre>           </p><h2><a id="migration">Migration Guide </a></h2><p>Many of the types in the old <code>com.sun.javadoc</code> API do not have equivalents in this package. Instead, types in the <code>javax.lang.model</code> and <code>com.sun.source</code> APIs are used instead.                          </p><p>The following table gives a guide to the mapping from old types to their replacements. In some cases, there is no direct equivalent.<table class="striped"><caption>Guide for mapping old types to new types       </caption><thead><tr><th scope="col">Old Type </th><th scope="col">New Type </th></tr></thead><tbody style="text-align:left"><tr><th scope="row"><code>AnnotatedType</code></th><td><a href="../../../../java.compiler/javax/lang/model/type/TypeMirror.html" title="interface in javax.lang.model.type"><code>javax.lang.model.type.TypeMirror</code></a></td></tr><tr><th scope="row"><code>AnnotationDesc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/AnnotationMirror.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.AnnotationMirror</code></a></td></tr><tr><th scope="row"><code>AnnotationDesc.ElementValuePair</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/AnnotationValue.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.AnnotationValue</code></a></td></tr><tr><th scope="row"><code>AnnotationTypeDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/TypeElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.TypeElement</code></a></td></tr><tr><th scope="row"><code>AnnotationTypeElementDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/ExecutableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.ExecutableElement</code></a></td></tr><tr><th scope="row"><code>AnnotationValue</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/AnnotationValue.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.AnnotationValue</code></a></td></tr><tr><th scope="row"><code>ClassDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/TypeElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.TypeElement</code></a></td></tr><tr><th scope="row"><code>ConstructorDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/ExecutableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.ExecutableElement</code></a></td></tr><tr><th scope="row"><code>Doc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/Element.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.Element</code></a></td></tr><tr><th scope="row"><code>DocErrorReporter</code></th><td><a href="Reporter.html" title="interface in jdk.javadoc.doclet"><code>jdk.javadoc.doclet.Reporter</code></a></td></tr><tr><th scope="row"><code>Doclet</code></th><td><a href="Doclet.html" title="interface in jdk.javadoc.doclet"><code>jdk.javadoc.doclet.Doclet</code></a></td></tr><tr><th scope="row"><code>ExecutableMemberDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/ExecutableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.ExecutableElement</code></a></td></tr><tr><th scope="row"><code>FieldDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/VariableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.VariableElement</code></a></td></tr><tr><th scope="row"><code>LanguageVersion</code></th><td><a href="../../../../java.compiler/javax/lang/model/SourceVersion.html" title="enum class in javax.lang.model"><code>javax.lang.model.SourceVersion</code></a></td></tr><tr><th scope="row"><code>MemberDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/Element.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.Element</code></a></td></tr><tr><th scope="row"><code>MethodDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/ExecutableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.ExecutableElement</code></a></td></tr><tr><th scope="row"><code>PackageDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/PackageElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.PackageElement</code></a></td></tr><tr><th scope="row"><code>Parameter</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/VariableElement.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.VariableElement</code></a></td></tr><tr><th scope="row"><code>ParameterizedType</code></th><td><a href="../../../../java.compiler/javax/lang/model/type/DeclaredType.html" title="interface in javax.lang.model.type"><code>javax.lang.model.type.DeclaredType</code></a></td></tr><tr><th scope="row"><code>ParamTag</code></th><td><a href="../../../../jdk.compiler/com/sun/source/doctree/ParamTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.ParamTree</code></a></td></tr><tr><th scope="row"><code>ProgramElementDoc</code></th><td><a href="../../../../java.compiler/javax/lang/model/element/Element.html" title="interface in javax.lang.model.element"><code>javax.lang.model.element.Element</code></a></td></tr><tr><th scope="row"><code>RootDoc</code></th><td><a href="DocletEnvironment.html" title="interface in jdk.javadoc.doclet"><code>jdk.javadoc.doclet.DocletEnvironment</code></a></td></tr><tr><th scope="row"><code>SeeTag</code></th><td><a href="../../../../jdk.compiler/com/sun/source/doctree/LinkTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.LinkTree</code></a><br/><a href="../../../../jdk.compiler/com/sun/source/doctree/SeeTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.SeeTree</code></a></td></tr><tr><th scope="row"><code>SerialFieldTag</code></th><td><a href="../../../../jdk.compiler/com/sun/source/doctree/SerialFieldTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.SerialFieldTree</code></a></td></tr><tr><th scope="row"><code>SourcePosition</code></th><td><a href="../../../../jdk.compiler/com/sun/source/util/SourcePositions.html" title="interface in com.sun.source.util"><code>com.sun.source.util.SourcePositions</code></a></td></tr><tr><th scope="row"><code>Tag</code></th><td><a href="../../../../jdk.compiler/com/sun/source/doctree/DocTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.DocTree</code></a></td></tr><tr><th scope="row"><code>ThrowsTag</code></th><td><a href="../../../../jdk.compiler/com/sun/source/doctree/ThrowsTree.html" title="interface in com.sun.source.doctree"><code>com.sun.source.doctree.ThrowsTree</code></a></td></tr><tr><th scope="row"><code>Type</code></th><td><a href="../../../../java.compiler/javax/lang/model/type/TypeMirror.html" title="interface in javax.lang.model.type"><code>javax.lang.model.type.TypeMirror</code></a></td></tr><tr><th scope="row"><code>TypeVariable</code></th><td><a href="../../../../java.compiler/javax/lang/model/type/TypeVariable.html" title="interface in javax.lang.model.type"><code>javax.lang.model.type.TypeVariable</code></a></td></tr><tr><th scope="row"><code>WildcardType</code></th><td><a href="../../../../java.compiler/javax/lang/model/type/WildcardType.html" title="interface in javax.lang.model.type"><code>javax.lang.model.type.WildcardType</code></a></td></tr></tbody></table>                      </p>                                                                                                                  </div><dl class="notes"><dt>Since:</dt><dd>9</dd><dt>See Also: </dt><dd><ul class="see-list"><li><a href="Doclet.html" title="interface in jdk.javadoc.doclet"><code>Doclet</code></a></li><li><a href="DocletEnvironment.html" title="interface in jdk.javadoc.doclet"><code>DocletEnvironment</code></a></li></ul></dd></dl></section><section class="summary"><ul class="summary-list"><li><div id="class-summary"><div class="table-tabs" role="tablist" aria-orientation="horizontal"><button id="class-summary-tab0" role="tab" aria-selected="true" aria-controls="class-summary.tabpanel" tabindex="0" class="active-table-tab">All Classes and Interfaces   </button><button id="class-summary-tab1" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" class="table-tab">Interfaces</button><button id="class-summary-tab2" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" class="table-tab">Classes</button><button id="class-summary-tab3" role="tab" aria-selected="false" aria-controls="class-summary.tabpanel" tabindex="-1" class="table-tab">Enum Classes </button></div><div id="class-summary.tabpanel" role="tabpanel"><div class="summary-table two-column-summary" aria-labelledby="class-summary-tab0"><div class="table-header col-first">Class</div><div class="table-header col-last">Description</div><div class="col-first even-row-color class-summary class-summary-tab1"><a href="Doclet.html" title="interface in jdk.javadoc.doclet">Doclet</a></div><div class="col-last even-row-color class-summary class-summary-tab1"><div class="block">The user doclet must implement this interface, as described in the <a href="package-summary.html#package-description">package description </a>.           </div></div><div class="col-first odd-row-color class-summary class-summary-tab1"><a href="Doclet.Option.html" title="interface in jdk.javadoc.doclet">Doclet.Option</a></div><div class="col-last odd-row-color class-summary class-summary-tab1"><div class="block">An encapsulation of option name, aliases, parameters and descriptions as used by the Doclet.             </div></div><div class="col-first even-row-color class-summary class-summary-tab3"><a href="Doclet.Option.Kind.html" title="enum class in jdk.javadoc.doclet">Doclet.Option.Kind</a></div><div class="col-last even-row-color class-summary class-summary-tab3"><div class="block">The kind of an option.    </div></div><div class="col-first odd-row-color class-summary class-summary-tab1"><a href="DocletEnvironment.html" title="interface in jdk.javadoc.doclet">DocletEnvironment</a></div><div class="col-last odd-row-color class-summary class-summary-tab1"><div class="block">Represents the operating environment of a single invocation of the doclet.          </div></div><div class="col-first even-row-color class-summary class-summary-tab3"><a href="DocletEnvironment.ModuleMode.html" title="enum class in jdk.javadoc.doclet">DocletEnvironment.ModuleMode</a></div><div class="col-last even-row-color class-summary class-summary-tab3"><div class="block">The mode specifying the level of detail of module documentation.         </div></div><div class="col-first odd-row-color class-summary class-summary-tab1"><a href="Reporter.html" title="interface in jdk.javadoc.doclet">Reporter</a></div><div class="col-last odd-row-color class-summary class-summary-tab1"><div class="block">This interface provides error, warning and notice reporting.       </div></div><div class="col-first even-row-color class-summary class-summary-tab2"><a href="StandardDoclet.html" title="class in jdk.javadoc.doclet">StandardDoclet</a></div><div class="col-last even-row-color class-summary class-summary-tab2"><div class="block">This doclet generates HTML-formatted documentation for the specified modules, packages and types.           </div></div><div class="col-first odd-row-color class-summary class-summary-tab1"><a href="Taglet.html" title="interface in jdk.javadoc.doclet">Taglet</a></div><div class="col-last odd-row-color class-summary class-summary-tab1"><div class="block">The interface for a custom taglet supported by doclets such as the <a href="StandardDoclet.html" title="class in jdk.javadoc.doclet"><code>standard doclet </code></a>.            </div></div><div class="col-first even-row-color class-summary class-summary-tab3"><a href="Taglet.Location.html" title="enum class in jdk.javadoc.doclet">Taglet.Location</a></div><div class="col-last even-row-color class-summary class-summary-tab3"><div class="block">The kind of location in which a tag may be used.          </div></div></div></div></div></li></ul></section></main><footer role="contentinfo"><hr/><p class="legal-copy"><small><a href="https://bugreport.java.com/bugreport/">Report a bug or suggest an enhancement      </a><br/> For further API reference and developer documentation see the <a href="https://docs.oracle.com/pls/topic/lookup?ctx=javase17&amp;id=homepage" target="_blank">Java SE Documentation  </a>, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. <a href="https://docs.oracle.com/en/java/javase/index.html">Other versions. </a><br/> Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.<br/><a href="../../../../../legal/copyright.html">Copyright</a> © 1993, 2021, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.<br/>All rights reserved. Use is subject to <a href="https://www.oracle.com/java/javase/terms/license/java17speclicense.html">license terms </a> and the <a href="https://www.oracle.com/technetwork/java/redist-137594.html">documentation redistribution policy  </a>. <br/><strong>DRAFT 17-internal+0-adhoc.jlahoda.jdk </strong>                                                                        </small></p></footer></div></div></diff></diffreport>