/*

 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/**

 * 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 {@link StandardDoclet standard doclet} can be used to

 * generate HTML-formatted documentation. It supports user-defined

 * {@link Taglet taglets}, which can be used to generate customized

 * output for user-defined tags in documentation comments.

 *

 * <p style="font-style: italic">

 * <b>Note:</b> The declarations in this package supersede those

 * in the older package {@code com.sun.javadoc}. 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>

 * The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet}

 * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface

 * method, defines the entry point.

 * <pre>

 *    public boolean <b>run</b>(DocletEnvironment environment)

 * </pre>

 * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the

 * environment that the doclet will be initialized with. From this environment

 * all other information can be extracted, in the form of

 * {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities

 * described by {@link javax.lang.model Language Model API} to query Elements and Types.

 * <p>

 *

 * <a id="terminology"></a>

 * <h3>Terminology</h3>

 *

 * <dl>

 *   <dt><a id="selected"></a>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"></a>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"></a>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"></a>

 * <h3>Options</h3>

 * Javadoc <em>selection control</em> can be specified with these options

 * as follows:

 * <ul>

 *   <li>{@code --show-members:value} and {@code --show-types:value} can

 *       be used to filter the members, with the following values:

 *   <ul>

 *     <li> public    -- considers only public elements

 *     <li> protected -- considers public and protected elements

 *     <li> package   -- considers public, protected and package private elements

 *     <li> private   -- considers all elements

 *   </ul>

 *

 *   <li>{@code --show-packages:value} "exported" or "all" can be used

 *       to consider only exported packages or all packages within a module.

 *

 *   <li>{@code --show-module-contents:value} 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.

 * </ul>

 * The following options can be used to specify the elements to be documented:

 * <ul>

 *   <li>{@code --module} documents the specified modules.

 *

 *   <li>{@code --expand-requires:value} 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> 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

 *   </ul>

 *   By default, only the specified modules will be considered, without expansion

 *   of the module dependencies.

 *

 *   <li>{@code packagenames} can be used to specify packages.

 *   <li>{@code -subpackages} can be used to recursively load packages.

 *   <li>{@code -exclude} can be used exclude package directories.

 *   <li>{@code sourcefilenames} can be used to specify source file names.

 * </ul>

 * <p>

 * <a id="legacy-interactions"></a>

 * <h4>Interactions with older options.</h4>

 *

 * The new {@code --show-*} options provide a more detailed replacement

 * Alternatively, the older options can continue to be used as shorter

 * forms for combinations of the new options, as described below:

 * <p>

 * <a id="qualified"></a>

 * A <em>qualified</em> element name is one that has its package

 * name prepended to it, such as {@code java.lang.String}.  A non-qualified

 * name has no package name, such as {@code String}.

 * <p>

 *

 * <a id="example"></a>

 * <h3>Example</h3>

 *

 * 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<? 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();

 *    }

 * }

 * </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>

 *

 * <h3><a id="migration">Migration Guide</a></h3>

 *

 * <p>Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this

 * package. Instead, types in the {@code javax.lang.model} and {@code com.sun.source} APIs

 * are used instead.

 *

 * <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>

 *

 * @see jdk.javadoc.doclet.Doclet

 * @see jdk.javadoc.doclet.DocletEnvironment

 * @since 9

*/

package jdk.javadoc.doclet;