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

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

    52  * doclet will be initialized with. From this environment all other information can be

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

    53  * extracted, in the form of {@link javax.lang.model} elements. One can further use the

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

    54  * APIs and utilities described by {@link javax.lang.model} to query Elements and Types.

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

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

    60  * <a name="specified"></a>

    61  * <dl>

    61  * Module, package and source file names can be provided as parameters to the

    62  *   <dt><a name="selected"></a>Selected</dt>

    62  * javadoc tool -- these are called the <em>specified</em> set containing

    63  *     <dd>An element is considered to be <em>selected</em>, if the

    63  * module elements, package elements and type elements.

    64  *         <em>selection controls</em> <a href="#options">allow</a> it

    64  * <p>

    65  *         to be documented. (Note that synthetic elements are never

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

    66  *         selected.)

    66  * {@code --show-members:value}, {@code --showtypes:value}, where value can be one of

    67  *    </dd>

    67  * the following:

    68  *

    68  * <ul>

    69  *   <dt><a name="specified"></a>Specified</dt>

    69  * <li> public    -- considers only public elements

    70  *   <dd>The set of elements specified by the user are considered to be <em>specified

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

    71  *       elements</em>. Specified elements provide the starting points

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

    72  *       for determining the <em>included elements</em> to be documented.

    72  * <li> private   -- considers all elements

    73  *   </dd>

    73  * </ul>

    74  *

    74  *

    75  *   <dt><a name="included"></a>Included</dt>

    75  * The {@code --show-package:value} where a value of "exported" or "all" can be used to

    76  *   <dd>An element is considered to be <em>included</em>, if it is

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

    77  *       <em>specified</em> if it contains a <em>specified</em> element,

    77  * <p>

    78  *       or it is enclosed in a <em>specified</em> element, and is <em>selected</em>.

    78  * The {@code --expand-requires:value}, expands the "requires" directives of a

    79  *       Included elements will be documented.

    79  * module declaration, to create a module set to considered for documentation

    80  *   </dd>

    81  *

    82  * </dl>

    83  * <p>

    84  * <a name="options"></a>

    85  * <h3>Options</h3>

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

    82  * <li> public -- follows and expands  all "requires public" edges in the module graph

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

    83  * <li> all    -- follows and expands  all "requires" edges in the module graph.

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

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

    91  *   <ul>

    85  * of the module dependencies.

    92  *     <li> public    -- considers only public elements

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

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

    95  *     <li> private   -- considers all elements

    96  *   </ul>

    97  *

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

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

   100  *

   101  *   <li>{@code --show-module-contents:value} can be used to specify the level at

   102  *       module declarations could be documented. A value of "api" indicates API

   103  *       level documentation, and "all" indicates detailed documentation.

    87  * <a name="included"></a>

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

    88  * All of the above are used to select the elements, to produce the

   106  * <ul>

    89  * <em>included</em> or the <em>selected</em> set.

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

    90  * <p>

   108  *

    91  * {@code --show-module-contents:value} can be used to specify the level at

   109  *   <li>{@code --expand-requires:value} expand the set of modules to be documented

    92  * module declarations could be documented, a value of "api" indicates API

   110  *        by including some or all of the modules dependencies. The value may be

    93  * level documentation, and "all" indicates detailed documentation.

   111  *        one of:

   112  *   <ul>

   113  *     <li> public -- each module specified explicitly on the command line is

   114  *          expanded to include the closure of its transitive dependencies

   115  *     <li> all    -- each module specified explicitly on the command line

   116  *          is expanded to include the closure of its transitive dependencies,

   117  *          and also all of its direct dependencies

   118  *   </ul>

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

   120  *   of the module dependencies.

   121  *

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

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

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

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

   126  * </ul>

    98  * The new --show-* options provide a more detailed replacement for the older

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

    99  * options -public, -protected, -package, -private.  Alternatively, the older

   132  * for the older options -public, -protected, -package, -private.

   100  * options can continue to be used as shorter forms for combinations of the

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

   101  * new options, as described below:

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

   105     <tr><th><th>--show-members<th>--show-types<th>--show-packages<th>--show-module-contents

   138     <tr><th><th>{@code --show-members}<th>{@code --show-types}<th>{@code --show-packages}<th>{@code --show-module-contents}

   106     <tr><td>-public<td>public<td>public<td>exported<td>api

   139     <tr><td>{@code -public}<td>public<td>public<td>exported<td>api

   107     <tr><td>-protected<td>protected<td>protected<td>exported<td>api

   140     <tr><td>{@code -protected}<td>protected<td>protected<td>exported<td>api

   108     <tr><td>-package<td>package<td>package<td>all<td>all

   141     <tr><td>{@code -package}<td>package<td>package<td>all<td>all

   109     <tr><td>-private<td>private<td>private<td>all<td>all

   142     <tr><td>{@code -private}<td>private<td>private<td>all<td>all

   122  * and its members, supporting an option "someoption".

   155  * and its members, supporting an option.

   124  * import com.sun.source.doctree.DocCommentTree;

   157  * // note imports deleted for clarity

   125  * import com.sun.source.util.DocTrees;

   126  * import java.io.IOException;

   127  * import java.util.Collections;

   128  * import java.util.Set;

   129  * import javax.lang.model.SourceVersion;

   130  * import javax.lang.model.element.Element;

   131  * import javax.lang.model.element.TypeElement;

   132  * import jdk.javadoc.doclet.*;

   133  *

   135  *

   159  *    Reporter reporter;

   136  *     @Override

   160  *    @Override

   137  *     public void init(Locale locale, Reporter reporter) {

   161  *    public void init(Locale locale, Reporter reporter) {

   138  *        return;

   162  *        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);

   139  *     }

   163  *        this.reporter = reporter;

   140  *

   164  *    }

   141  *     @Override

   165  *

   142  *     public boolean run(DocletEnvironment docEnv) {

   166  *    public void printElement(DocTrees trees, Element e) {

   143  *         // cache the DocTrees utility class to access DocComments

   167  *        DocCommentTree docCommentTree = trees.getDocCommentTree(e);

   144  *         DocTrees docTrees = docEnv.getDocTrees();

   168  *        if (docCommentTree != null) {

   145  *

   169  *            System.out.println("Element (" + e.getKind() + ": "

   146  *         // location of an element in the same directory as overview.html

   170  *                    + e + ") has the following comments:");

   147  *         try {

   171  *            System.out.println("Entire body: " + docCommentTree.getFullBody());

   148  *             Element barElement = null;

   172  *            System.out.println("Block tags: " + docCommentTree.getBlockTags());

   149  *             for (Element e : docEnv.getIncludedClasses()) {

   173  *        }

   150  *                 if (e.getSimpleName().toString().equals("FooBar")) {

   174  *    }

   151  *                     barElement = e;

   175  *

   152  *                 }

   176  *    @Override

   153  *             }

   177  *    public boolean run(DocletEnvironment docEnv) {

   154  *             DocCommentTree docCommentTree =

   178  *        reporter.print(Kind.NOTE, "overviewfile: " + overviewfile);

   155  *                     docTrees.getDocCommentTree(barElement, "overview.html");

   179  *        // get the DocTrees utility class to access document comments

   156  *             if (docCommentTree != null) {

   180  *        DocTrees docTrees = docEnv.getDocTrees();

   157  *                 System.out.println("Overview html: " +

   181  *

   158  *                         docCommentTree.getFullBody());

   182  *        // location of an element in the same directory as overview.html

   159  *             }

   183  *        try {

   160  *         } catch (IOException missing) {

   184  *            Element e = ElementFilter.typesIn(docEnv.getSpecifiedElements()).iterator().next();

   161  *             System.err.println("No overview.html found.");

   185  *            DocCommentTree docCommentTree

   162  *         }

   186  *                    = docTrees.getDocCommentTree(e, overviewfile);

   163  *

   187  *            if (docCommentTree != null) {

   164  *         for (TypeElement t : docEnv.getIncludedClasses()) {

   188  *                System.out.println("Overview html: " + docCommentTree.getFullBody());

   165  *             System.out.println(t.getKind() + ":" + t);

   189  *            }

   166  *             for (Element e : t.getEnclosedElements()) {

   190  *        } catch (IOException missing) {

   167  *                 DocCommentTree docCommentTree = docTrees.getDocCommentTree(e);

   191  *            reporter.print(Kind.ERROR, "No overview.html found.");

   168  *                 if (docCommentTree != null) {

   192  *        }

   169  *                     System.out.println("Element (" + e.getKind() + ": " +

   193  *

   170  *                             e + ") has the following comments:");

   194  *        for (TypeElement t : ElementFilter.typesIn(docEnv.getIncludedElements())) {

   171  *                     System.out.println("Entire body: " + docCommentTree.getFullBody());

   195  *            System.out.println(t.getKind() + ":" + t);

   172  *                     System.out.println("Block tags: " + docCommentTree.getBlockTags());

   196  *            for (Element e : t.getEnclosedElements()) {

   173  *                 } else {

   197  *                printElement(docTrees, e);

   174  *                     System.out.println("no comment.");

   198  *            }

   175  *                 }

   199  *        }

   176  *             }

   200  *        return true;

   177  *         }

   201  *    }

   178  *         return true;

   202  *

   179  *     }

   203  *    @Override

   180  *

   204  *    public String getName() {

   181  *     @Override

   205  *        return "Example";

   182  *     public String getName() {

   206  *    }

   183  *         return "Example";

   207  *

   184  *     }

   208  *    private String overviewfile;

   185  *

   209  *

   186  *   private String someOption;

   210  *    @Override

   187  *

   211  *    public Set<? extends Option> getSupportedOptions() {

   188  *   @Override

   212  *        Option[] options = {

   189  *   public Set<Option> getSupportedOptions() {

   213  *            new Option() {

   190  *       Option[] options = {

   214  *                private final List<String> someOption = Arrays.asList(

   191  *           new Option() {

   215  *                        "-overviewfile",

   192  *               public int getArgumentCount() {

   216  *                        "--overview-file",

   193  *                   return 1;

   217  *                        "-o"

   194  *               }

   218  *                );

   195  *               public String getDescription() {

   219  *

   196  *                   return "someoption";

   220  *                @Override

   197  *               }

   221  *                public int getArgumentCount() {

   198  *               public Option.Kind getKind() {

   222  *                    return 1;

   199  *                   return Option.Kind.STANDARD;

   223  *                }

   200  *               }

   224  *

   201  *               public String getName() {

   225  *                @Override

   202  *                   return "someoption";

   226  *                public String getDescription() {

   203  *               }

   227  *                    return "an option with aliases";

   204  *               public String getParameters() {

   228  *                }

   205  *                   return "url";

   229  *

   206  *               }

   230  *                @Override

   207  *               public boolean matches(String option) {

   231  *                public Option.Kind getKind() {

   208  *                  String opt = option.startsWith("-") ? option.substring(1) : option;

   232  *                    return Option.Kind.STANDARD;

   209  *                  return getName().equals(opt);

   233  *                }

   210  *               }

   234  *

   211  *               public boolean process(String option, ListIterator<String> arguments) {

   235  *                @Override

   212  *                  overviewpath = arguments.next();

   236  *                public List<String> getNames() {

   213  *                  return true;

   237  *                    return someOption;

   214  *               }

   238  *                }

   215  *          }

   239  *

   216  *      };

   240  *                @Override

   217  *      return new HashSet<Option>(Arrays.asList(options));

   241  *                public String getParameters() {

   218  *     }

   242  *                    return "file";

   219  *

   243  *                }

   220  *     @Override

   244  *

   221  *     public SourceVersion getSupportedSourceVersion() {

   245  *                @Override

   222  *         // support the latest release

   246  *                public boolean process(String opt, List<String> arguments) {

   223  *         return SourceVersion.latest();

   247  *                    overviewfile = arguments.get(0);

   224  *     }

   248  *                    return true;

   249  *                }

   250  *            }

   251  *        };

   252  *        return new HashSet<>(Arrays.asList(options));

   253  *    }

   254  *

   255  *    @Override

   256  *    public SourceVersion getSupportedSourceVersion() {

   257  *        // support the latest release

   258  *        return SourceVersion.latest();

   259  *    }

   228  * This doclet when invoked with a command line, such as:

   263  * This doclet can be invoked with a command line, such as:

   230  *     javadoc -doclet Example -sourcepath <source-location>

   265  *     javadoc -doclet Example \

   231  * </pre>

   266  *       -overviewfile overview.html \

   232  * will produce an output, such as:

   267  *       -sourcepath source-location \

   233  * <pre>

   268  *       source-location/Example.java

   234  *  Overview.html: overview comments

   235  *  ...

   236  *  ...

   237  *  CLASS: SomeKlass

   238  *  .....

   239  *  Element (METHOD: main(java.lang.String...)) has the following comments:

   240  *  Entire body: The main entry point.

   241  *  Block tags: @param an array of Strings

   242  *  ...