jdk.javadoc.doclet.package-info Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javac Show documentation
Show all versions of javac Show documentation
A repackaged copy of javac for error-prone to depend on
/*
* Copyright (c) 2015, 2016, 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 javadoc comments embedded in the source.
*
*
* Note: 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
* Migration Guide.
*
*
*
* 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.
*
* 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.
*
* public boolean run(DocletEnvironment environment)
*
* 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} elements. One can further use the
* APIs and utilities described by {@link javax.lang.model} to query Elements and Types.
* Terminology
*
*
* When calling javadoc, one can pass in package names and source file names --
* these are called the specified PackageElements and TypeElements.
* Javadoc options are also passed in; the access control Javadoc options
* ({@code -public}, {@code -protected}, {@code -package},
* and {@code -private}) are used to filter program elements, producing a
* result set, called the included set, or "selected" set.
*
*
* A qualified 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}.
*
Example
*
* The following is an example doclet that displays information of a class
* and its members, supporting an option "someoption".
*
* import com.sun.source.doctree.DocCommentTree;
* import com.sun.source.util.DocTrees;
* import java.io.IOException;
* import java.util.Collections;
* import java.util.Set;
* import javax.lang.model.SourceVersion;
* import javax.lang.model.element.Element;
* import javax.lang.model.element.TypeElement;
* import jdk.javadoc.doclet.*;
*
* public class Example implements Doclet {
*
* @Override
* public void init(Locale locale, Reporter reporter) {
* return;
* }
*
* @Override
* public boolean run(RootDoc root) {
* // cache the DocTrees utility class to access DocComments
* DocTrees docTrees = root.getDocTrees();
*
* // location of an element in the same directory as overview.html
* try {
* Element barElement = null;
* for (Element e : root.getIncludedClasses()) {
* if (e.getSimpleName().toString().equals("FooBar")) {
* barElement = e;
* }
* }
* DocCommentTree docCommentTree =
* docTrees.getDocCommentTree(barElement, "overview.html");
* if (docCommentTree != null) {
* System.out.println("Overview html: " +
* docCommentTree.getFullBody());
* }
* } catch (IOException missing) {
* System.err.println("No overview.html found.");
* }
*
* for (TypeElement t : root.getIncludedClasses()) {
* System.out.println(t.getKind() + ":" + t);
* for (Element e : t.getEnclosedElements()) {
* DocCommentTree docCommentTree = docTrees.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());
* } else {
* System.out.println("no comment.");
* }
* }
* }
* return true;
* }
*
* @Override
* public String getName() {
* return "Example";
* }
*
* private String someOption;
*
* @Override
* public Set<Option> getSupportedOptions() {
* Option[] options = {
* new Option() {
* public int getArgumentCount() {
* return 1;
* }
* public String getDescription() {
* return "someoption";
* }
* public Option.Kind getKind() {
* return Option.Kind.STANDARD;
* }
* public String getName() {
* return "someoption";
* }
* public String getParameters() {
* return "url";
* }
* public boolean matches(String option) {
* String opt = option.startsWith("-") ? option.substring(1) : option;
* return getName().equals(opt);
* }
* public boolean process(String option, ListIterator<String> arguments) {
* overviewpath = arguments.next();
* return true;
* }
* }
* };
* return new HashSet<Option>(Arrays.asList(options));
* }
*
* @Override
* public SourceVersion getSupportedSourceVersion() {
* // support the latest release
* return SourceVersion.latest();
* }
* }
*
*
* This doclet when invoked with a command line, such as:
*
* javadoc -doclet Example -sourcepath <source-location>
*
* will produce an output, such as:
*
* Overview.html: overview comments
* ...
* ...
* CLASS: SomeKlass
* .....
* Element (METHOD: main(java.lang.String...)) has the following comments:
* Entire body: The main entry point.
* Block tags: @param an array of Strings
* ...
*
*
* Migration Guide
*
* 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.
*
*
The following table gives a guide to the mapping from old types to their replacements.
* In some cases, there is no direct equivalent.
*
*
Guide for mapping old types to new types
Old Type New Type
AnnotatedType javax.lang.model.type.Type
AnnotationDesc javax.lang.model.element.AnnotationMirror
AnnotationDesc.ElementValuePair javax.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.Type
TypeVariable javax.lang.model.type.TypeVariable
WildcardType javax.lang.model.type.WildcardType
*
*
* @see jdk.javadoc.doclet.Doclet
* @see jdk.javadoc.doclet.DocletEnvironment
* @since 9
*/
package jdk.javadoc.doclet;
© 2015 - 2025 Weber Informatics LLC | Privacy Policy