< prev index next >

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/package-info.java

Print this page




  45  * <p>
  46  * Doclets are invoked by javadoc and this API can be used to write out
  47  * program information to files.  For example, the standard doclet is
  48  * invoked by default, to generate HTML documentation.
  49  * <p>
  50 
  51  * The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet}
  52  * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface
  53  * method, defines the entry point.
  54  * <pre>
  55  *    public boolean <b>run</b>(DocletEnvironment environment)
  56  * </pre>
  57  * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
  58  * environment that the doclet will be initialized with. From this environment
  59  * all other information can be extracted, in the form of
  60  * {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities
  61  * described by {@link javax.lang.model Language Model API} to query Elements and Types.
  62  * <p>
  63  *
  64  * <a id="terminology"></a>
  65  * <h2>Terminology</h2>
  66  *
  67  * <dl>
  68  *   <dt><a id="selected"></a>Selected</dt>
  69  *     <dd>An element is considered to be <em>selected</em>, if the
  70  *         <em>selection controls</em> <a href="#options">allow</a> it
  71  *         to be documented. (Note that synthetic elements are never
  72  *         selected.)
  73  *    </dd>
  74  *
  75  *   <dt><a id="specified"></a>Specified</dt>
  76  *   <dd>The set of elements specified by the user are considered to be <em>specified
  77  *       elements</em>. Specified elements provide the starting points
  78  *       for determining the <em>included elements</em> to be documented.
  79  *   </dd>
  80  *
  81  *   <dt><a id="included"></a>Included</dt>
  82  *   <dd>An element is considered to be <em>included</em>, if it is
  83  *       <em>specified</em> if it contains a <em>specified</em> element,
  84  *       or it is enclosed in a <em>specified</em> element, and is <em>selected</em>.
  85  *       Included elements will be documented.
  86  *   </dd>
  87  *
  88  * </dl>
  89  * <p>
  90  * <a id="options"></a>
  91  * <h2>Options</h2>
  92  * Javadoc <em>selection control</em> can be specified with these options
  93  * as follows:
  94  * <ul>
  95  *   <li>{@code --show-members:value} and {@code --show-types:value} can
  96  *       be used to filter the members, with the following values:
  97  *   <ul>
  98  *     <li> public    -- considers only public elements
  99  *     <li> protected -- considers public and protected elements
 100  *     <li> package   -- considers public, protected and package private elements
 101  *     <li> private   -- considers all elements
 102  *   </ul>
 103  *
 104  *   <li>{@code --show-packages:value} "exported" or "all" can be used
 105  *       to consider only exported packages or all packages within a module.
 106  *
 107  *   <li>{@code --show-module-contents:value} can be used to specify the level at
 108  *       module declarations could be documented. A value of "api" indicates API
 109  *       level documentation, and "all" indicates detailed documentation.
 110  * </ul>
 111  * The following options can be used to specify the elements to be documented:


 115  *   <li>{@code --expand-requires:value} expand the set of modules to be documented
 116  *        by including some or all of the modules dependencies. The value may be
 117  *        one of:
 118  *   <ul>
 119  *     <li> transitive -- each module specified explicitly on the command line is
 120  *          expanded to include the closure of its transitive dependencies
 121  *     <li> all    -- each module specified explicitly on the command line
 122  *          is expanded to include the closure of its transitive dependencies,
 123  *          and also all of its direct dependencies
 124  *   </ul>
 125  *   By default, only the specified modules will be considered, without expansion
 126  *   of the module dependencies.
 127  *
 128  *   <li>{@code packagenames} can be used to specify packages.
 129  *   <li>{@code -subpackages} can be used to recursively load packages.
 130  *   <li>{@code -exclude} can be used exclude package directories.
 131  *   <li>{@code sourcefilenames} can be used to specify source file names.
 132  * </ul>
 133  * <p>
 134  * <a id="legacy-interactions"></a>
 135  * <h3>Interactions with older options.</h3>
 136  *
 137  * The new {@code --show-*} options provide a more detailed replacement
 138  * for the older options {@code -public}, {@code -protected}, {@code -package}, {@code -private}.
 139  * Alternatively, the older options can continue to be used as shorter
 140  * forms for combinations of the new options, as described below:
 141  * <table class="striped">
 142  *   <caption>Short form options mapping</caption>
 143  *   <thead>
 144  *       <tr>   <th rowspan="2" scope="col" style="vertical-align:top">
 145  *                      Older option
 146  *              <th colspan="5" scope="col" style="border-bottom: 1px solid black">
 147  *                      Equivalent to these values with the new option
 148  *       <tr>   <th scope="col">{@code --show-members}
 149  *              <th scope="col">{@code --show-types}
 150  *              <th scope="col">{@code --show-packages}
 151  *              <th scope="col">{@code --show-module-contents}
 152  *   </thead>
 153  *   <tbody>
 154  *       <tr>   <th scope="row">{@code -public}
 155  *              <td>public


 164  *       <tr>   <th scope="row">{@code -package}
 165  *              <td>package
 166  *              <td>package
 167  *              <td>all
 168  *              <td>all
 169  *       <tr>   <th scope="row">{@code -private}
 170  *              <td>private
 171  *              <td>private
 172  *              <td>all
 173  *              <td>all
 174  *   </tbody>
 175  * </table>
 176  * <p>
 177  * <a id="qualified"></a>
 178  * A <em>qualified</em> element name is one that has its package
 179  * name prepended to it, such as {@code java.lang.String}.  A non-qualified
 180  * name has no package name, such as {@code String}.
 181  * <p>
 182  *
 183  * <a id="example"></a>
 184  * <h2>Example</h2>
 185  *
 186  * The following is an example doclet that displays information of a class
 187  * and its members, supporting an option.
 188  * <pre>
 189  * // note imports deleted for clarity
 190  * public class Example implements Doclet {
 191  *    Reporter reporter;
 192  *    @Override
 193  *    public void init(Locale locale, Reporter reporter) {
 194  *        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
 195  *        this.reporter = reporter;
 196  *    }
 197  *
 198  *    public void printElement(DocTrees trees, Element e) {
 199  *        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
 200  *        if (docCommentTree != null) {
 201  *            System.out.println("Element (" + e.getKind() + ": "
 202  *                    + e + ") has the following comments:");
 203  *            System.out.println("Entire body: " + docCommentTree.getFullBody());
 204  *            System.out.println("Block tags: " + docCommentTree.getBlockTags());


 283  *        };
 284  *        return new HashSet&lt;&gt;(Arrays.asList(options));
 285  *    }
 286  *
 287  *    @Override
 288  *    public SourceVersion getSupportedSourceVersion() {
 289  *        // support the latest release
 290  *        return SourceVersion.latest();
 291  *    }
 292  * }
 293  * </pre>
 294  * <p>
 295  * This doclet can be invoked with a command line, such as:
 296  * <pre>
 297  *     javadoc -doclet Example \
 298  *       -overviewfile overview.html \
 299  *       -sourcepath source-location \
 300  *       source-location/Example.java
 301  * </pre>
 302  *
 303  * <h2><a id="migration">Migration Guide</a></h2>
 304  *
 305  * <p>Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this
 306  * package. Instead, types in the {@code javax.lang.model} and {@code com.sun.source} APIs
 307  * are used instead.
 308  *
 309  * <p>The following table gives a guide to the mapping from old types to their replacements.
 310  * In some cases, there is no direct equivalent.
 311  *
 312  * <table class="striped">
 313  *   <caption>Guide for mapping old types to new types</caption>
 314  *   <thead>
 315  *     <tr><th scope="col">Old Type<th scope="col">New Type
 316  *   </thead>
 317  *   <tbody style="text-align:left">
 318  *     <tr><th scope="row">{@code AnnotatedType}            <td>{@link javax.lang.model.type.TypeMirror javax.lang.model.type.TypeMirror}
 319  *     <tr><th scope="row">{@code AnnotationDesc}           <td>{@link javax.lang.model.element.AnnotationMirror javax.lang.model.element.AnnotationMirror}
 320  *     <tr><th scope="row">{@code AnnotationDesc.ElementValuePair}<td>{@link javax.lang.model.element.AnnotationValue javax.lang.model.element.AnnotationValue}
 321  *     <tr><th scope="row">{@code AnnotationTypeDoc}        <td>{@link javax.lang.model.element.TypeElement javax.lang.model.element.TypeElement}
 322  *     <tr><th scope="row">{@code AnnotationTypeElementDoc} <td>{@link javax.lang.model.element.ExecutableElement javax.lang.model.element.ExecutableElement}
 323  *     <tr><th scope="row">{@code AnnotationValue}          <td>{@link javax.lang.model.element.AnnotationValue javax.lang.model.element.AnnotationValue}




  45  * <p>
  46  * Doclets are invoked by javadoc and this API can be used to write out
  47  * program information to files.  For example, the standard doclet is
  48  * invoked by default, to generate HTML documentation.
  49  * <p>
  50 
  51  * The invocation is defined by the interface {@link jdk.javadoc.doclet.Doclet}
  52  * -- the {@link jdk.javadoc.doclet.Doclet#run(DocletEnvironment) run} interface
  53  * method, defines the entry point.
  54  * <pre>
  55  *    public boolean <b>run</b>(DocletEnvironment environment)
  56  * </pre>
  57  * The {@link jdk.javadoc.doclet.DocletEnvironment} instance holds the
  58  * environment that the doclet will be initialized with. From this environment
  59  * all other information can be extracted, in the form of
  60  * {@link javax.lang.model.element.Element elements}. One can further use the APIs and utilities
  61  * described by {@link javax.lang.model Language Model API} to query Elements and Types.
  62  * <p>
  63  *
  64  * <a id="terminology"></a>
  65  * <h3>Terminology</h3>
  66  *
  67  * <dl>
  68  *   <dt><a id="selected"></a>Selected</dt>
  69  *     <dd>An element is considered to be <em>selected</em>, if the
  70  *         <em>selection controls</em> <a href="#options">allow</a> it
  71  *         to be documented. (Note that synthetic elements are never
  72  *         selected.)
  73  *    </dd>
  74  *
  75  *   <dt><a id="specified"></a>Specified</dt>
  76  *   <dd>The set of elements specified by the user are considered to be <em>specified
  77  *       elements</em>. Specified elements provide the starting points
  78  *       for determining the <em>included elements</em> to be documented.
  79  *   </dd>
  80  *
  81  *   <dt><a id="included"></a>Included</dt>
  82  *   <dd>An element is considered to be <em>included</em>, if it is
  83  *       <em>specified</em> if it contains a <em>specified</em> element,
  84  *       or it is enclosed in a <em>specified</em> element, and is <em>selected</em>.
  85  *       Included elements will be documented.
  86  *   </dd>
  87  *
  88  * </dl>
  89  * <p>
  90  * <a id="options"></a>
  91  * <h3>Options</h3>
  92  * Javadoc <em>selection control</em> can be specified with these options
  93  * as follows:
  94  * <ul>
  95  *   <li>{@code --show-members:value} and {@code --show-types:value} can
  96  *       be used to filter the members, with the following values:
  97  *   <ul>
  98  *     <li> public    -- considers only public elements
  99  *     <li> protected -- considers public and protected elements
 100  *     <li> package   -- considers public, protected and package private elements
 101  *     <li> private   -- considers all elements
 102  *   </ul>
 103  *
 104  *   <li>{@code --show-packages:value} "exported" or "all" can be used
 105  *       to consider only exported packages or all packages within a module.
 106  *
 107  *   <li>{@code --show-module-contents:value} can be used to specify the level at
 108  *       module declarations could be documented. A value of "api" indicates API
 109  *       level documentation, and "all" indicates detailed documentation.
 110  * </ul>
 111  * The following options can be used to specify the elements to be documented:


 115  *   <li>{@code --expand-requires:value} expand the set of modules to be documented
 116  *        by including some or all of the modules dependencies. The value may be
 117  *        one of:
 118  *   <ul>
 119  *     <li> transitive -- each module specified explicitly on the command line is
 120  *          expanded to include the closure of its transitive dependencies
 121  *     <li> all    -- each module specified explicitly on the command line
 122  *          is expanded to include the closure of its transitive dependencies,
 123  *          and also all of its direct dependencies
 124  *   </ul>
 125  *   By default, only the specified modules will be considered, without expansion
 126  *   of the module dependencies.
 127  *
 128  *   <li>{@code packagenames} can be used to specify packages.
 129  *   <li>{@code -subpackages} can be used to recursively load packages.
 130  *   <li>{@code -exclude} can be used exclude package directories.
 131  *   <li>{@code sourcefilenames} can be used to specify source file names.
 132  * </ul>
 133  * <p>
 134  * <a id="legacy-interactions"></a>
 135  * <h4>Interactions with older options.</h4>
 136  *
 137  * The new {@code --show-*} options provide a more detailed replacement
 138  * for the older options {@code -public}, {@code -protected}, {@code -package}, {@code -private}.
 139  * Alternatively, the older options can continue to be used as shorter
 140  * forms for combinations of the new options, as described below:
 141  * <table class="striped">
 142  *   <caption>Short form options mapping</caption>
 143  *   <thead>
 144  *       <tr>   <th rowspan="2" scope="col" style="vertical-align:top">
 145  *                      Older option
 146  *              <th colspan="5" scope="col" style="border-bottom: 1px solid black">
 147  *                      Equivalent to these values with the new option
 148  *       <tr>   <th scope="col">{@code --show-members}
 149  *              <th scope="col">{@code --show-types}
 150  *              <th scope="col">{@code --show-packages}
 151  *              <th scope="col">{@code --show-module-contents}
 152  *   </thead>
 153  *   <tbody>
 154  *       <tr>   <th scope="row">{@code -public}
 155  *              <td>public


 164  *       <tr>   <th scope="row">{@code -package}
 165  *              <td>package
 166  *              <td>package
 167  *              <td>all
 168  *              <td>all
 169  *       <tr>   <th scope="row">{@code -private}
 170  *              <td>private
 171  *              <td>private
 172  *              <td>all
 173  *              <td>all
 174  *   </tbody>
 175  * </table>
 176  * <p>
 177  * <a id="qualified"></a>
 178  * A <em>qualified</em> element name is one that has its package
 179  * name prepended to it, such as {@code java.lang.String}.  A non-qualified
 180  * name has no package name, such as {@code String}.
 181  * <p>
 182  *
 183  * <a id="example"></a>
 184  * <h3>Example</h3>
 185  *
 186  * The following is an example doclet that displays information of a class
 187  * and its members, supporting an option.
 188  * <pre>
 189  * // note imports deleted for clarity
 190  * public class Example implements Doclet {
 191  *    Reporter reporter;
 192  *    @Override
 193  *    public void init(Locale locale, Reporter reporter) {
 194  *        reporter.print(Kind.NOTE, "Doclet using locale: " + locale);
 195  *        this.reporter = reporter;
 196  *    }
 197  *
 198  *    public void printElement(DocTrees trees, Element e) {
 199  *        DocCommentTree docCommentTree = trees.getDocCommentTree(e);
 200  *        if (docCommentTree != null) {
 201  *            System.out.println("Element (" + e.getKind() + ": "
 202  *                    + e + ") has the following comments:");
 203  *            System.out.println("Entire body: " + docCommentTree.getFullBody());
 204  *            System.out.println("Block tags: " + docCommentTree.getBlockTags());


 283  *        };
 284  *        return new HashSet&lt;&gt;(Arrays.asList(options));
 285  *    }
 286  *
 287  *    @Override
 288  *    public SourceVersion getSupportedSourceVersion() {
 289  *        // support the latest release
 290  *        return SourceVersion.latest();
 291  *    }
 292  * }
 293  * </pre>
 294  * <p>
 295  * This doclet can be invoked with a command line, such as:
 296  * <pre>
 297  *     javadoc -doclet Example \
 298  *       -overviewfile overview.html \
 299  *       -sourcepath source-location \
 300  *       source-location/Example.java
 301  * </pre>
 302  *
 303  * <h3><a id="migration">Migration Guide</a></h3>
 304  *
 305  * <p>Many of the types in the old {@code com.sun.javadoc} API do not have equivalents in this
 306  * package. Instead, types in the {@code javax.lang.model} and {@code com.sun.source} APIs
 307  * are used instead.
 308  *
 309  * <p>The following table gives a guide to the mapping from old types to their replacements.
 310  * In some cases, there is no direct equivalent.
 311  *
 312  * <table class="striped">
 313  *   <caption>Guide for mapping old types to new types</caption>
 314  *   <thead>
 315  *     <tr><th scope="col">Old Type<th scope="col">New Type
 316  *   </thead>
 317  *   <tbody style="text-align:left">
 318  *     <tr><th scope="row">{@code AnnotatedType}            <td>{@link javax.lang.model.type.TypeMirror javax.lang.model.type.TypeMirror}
 319  *     <tr><th scope="row">{@code AnnotationDesc}           <td>{@link javax.lang.model.element.AnnotationMirror javax.lang.model.element.AnnotationMirror}
 320  *     <tr><th scope="row">{@code AnnotationDesc.ElementValuePair}<td>{@link javax.lang.model.element.AnnotationValue javax.lang.model.element.AnnotationValue}
 321  *     <tr><th scope="row">{@code AnnotationTypeDoc}        <td>{@link javax.lang.model.element.TypeElement javax.lang.model.element.TypeElement}
 322  *     <tr><th scope="row">{@code AnnotationTypeElementDoc} <td>{@link javax.lang.model.element.ExecutableElement javax.lang.model.element.ExecutableElement}
 323  *     <tr><th scope="row">{@code AnnotationValue}          <td>{@link javax.lang.model.element.AnnotationValue javax.lang.model.element.AnnotationValue}


< prev index next >