https://openjdk.java.net/ 
/*
 * Copyright (c) 2015, 2020, 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.
 */

package jdk.javadoc.doclet;

import java.util.List;
import java.util.Locale;
import java.util.Set;

import javax.lang.model.SourceVersion;


The user doclet must implement this interface, as described in the
package description.
Each implementation of a Doclet must provide a public no-argument constructor
to be used by tools to instantiate the doclet. The tool infrastructure will
interact with classes implementing this interface as follows:

    

  1.  The tool will create an instance of a doclet using the no-arg constructor
 of the doclet class.

  2.  Next, the tool calls the init method with an appropriate locale and reporter. 
  3.  Afterwards, the tool calls getSupportedOptions, and getSupportedSourceVersion. These methods are only called once. 
  4.  As appropriate, the tool calls the run method on the doclet object, giving it a DocletEnvironment object, from which the doclet can determine the elements to be included in the documentation. 



If a doclet object is created and used without the above protocol being followed,
then the doclet's behavior is not defined by this interface specification.

 To start the doclet, pass -doclet followed by the fully-qualified name of the entry point class (i.e. the implementation of this interface) on the javadoc tool command line. 
Since:9
/**
 * The user doclet must implement this interface, as described in the
 * <a href="package-summary.html#package.description">package description</a>.
 * Each implementation of a Doclet must provide a public no-argument constructor
 * to be used by tools to instantiate the doclet. The tool infrastructure will
 * interact with classes implementing this interface as follows:
 * <ol>
 * <li> The tool will create an instance of a doclet using the no-arg constructor
 *  of the doclet class.
 * <li> Next, the tool calls the {@link #init init} method with an appropriate locale
 *  and reporter.
 * <li> Afterwards, the tool calls {@link #getSupportedOptions getSupportedOptions},
 * and {@link #getSupportedSourceVersion getSupportedSourceVersion}.
 * These methods are only called once.
 * <li> As appropriate, the tool calls the {@link #run run} method on the doclet
 * object, giving it a DocletEnvironment object, from which the doclet can determine
 * the elements to be included in the documentation.
 * </ol>
 * <p>
 * If a doclet object is created and used without the above protocol being followed,
 * then the doclet's behavior is not defined by this interface specification.
 * <p> To start the doclet, pass {@code -doclet} followed by the fully-qualified
 * name of the entry point class (i.e. the implementation of this interface) on
 * the javadoc tool command line.
 *
 * @since 9
 */
public interface Doclet {

    
Initializes this doclet with the given locale and error reporter.
This locale will be used by the reporter and the doclet components.

Params:
  • locale – the locale to be used
  • reporter – the reporter to be used
/**
     * Initializes this doclet with the given locale and error reporter.
     * This locale will be used by the reporter and the doclet components.
     *
     * @param locale the locale to be used
     * @param reporter the reporter to be used
     */
    void init(Locale locale, Reporter reporter);

    
Returns a name identifying the doclet. A name is a simple identifier
without white spaces, as defined in The Java Language Specification,
section 6.2 "Names and Identifiers".

Returns:name of the Doclet
/**
     * Returns a name identifying the doclet. A name is a simple identifier
     * without white spaces, as defined in <cite>The Java Language Specification</cite>,
     * section 6.2 "Names and Identifiers".
     *
     * @return name of the Doclet
     */
    String getName();

    
Returns all the supported options.

Returns:a set containing all the supported options, an empty set if none
/**
     * Returns all the supported options.
     *
     * @return a set containing all the supported options, an empty set if none
     */
    Set<? extends Option> getSupportedOptions();

    
Returns the version of the Java Programming Language supported
by this doclet.

Returns: the language version supported by this doclet, usually
the latest version
/**
     * Returns the version of the Java Programming Language supported
     * by this doclet.
     *
     * @return  the language version supported by this doclet, usually
     * the latest version
     */
    SourceVersion getSupportedSourceVersion();

    
The entry point of the doclet. Further processing will commence as
instructed by this method.

Params:
  • environment – from which essential information can be extracted
Returns:true on success
/**
     * The entry point of the doclet. Further processing will commence as
     * instructed by this method.
     *
     * @param environment from which essential information can be extracted
     * @return true on success
     */
    boolean run(DocletEnvironment environment);

    
An encapsulation of option name, aliases, parameters and descriptions
as used by the Doclet.

/**
     * An encapsulation of option name, aliases, parameters and descriptions
     * as used by the Doclet.
     */
    interface Option {
        
Returns the number of arguments, this option will consume.

Returns:number of consumed arguments
/**
         * Returns the number of arguments, this option will consume.
         * @return number of consumed arguments
         */
        int getArgumentCount();

        
Returns the description of the option. For instance, the option "group", would
return the synopsis of the option such as, "groups the documents".

Returns:description if set, otherwise an empty String
/**
         * Returns the description of the option. For instance, the option "group", would
         * return the synopsis of the option such as, "groups the documents".
         * @return description if set, otherwise an empty String
         */
        String getDescription();

        
Returns the option kind.

Returns:the kind of this option
/**
         * Returns the option kind.
         * @return the kind of this option
         */
        Option.Kind getKind();

        
Returns the list of names that may be used to identify the option. For instance, the list could be ["-classpath", "--class-path"] for the option "-classpath", with an alias "--class-path". 
Returns:the names of the option
/**
         * Returns the list of names that may be used to identify the option. For instance, the
         * list could be {@code ["-classpath", "--class-path"]} for the
         * option "-classpath", with an alias "--class-path".
         * @return the names of the option
         */
        List<String> getNames();

        
Returns the parameters of the option. For instance "name <p1>:<p2>.."

Returns:parameters if set, otherwise an empty String
/**
         * Returns the parameters of the option. For instance "name &lt;p1&gt;:&lt;p2&gt;.."
         * @return parameters if set, otherwise an empty String
         */
        String getParameters();

        
Processes the option and arguments as needed. This method will
be invoked if the given option name matches the option.

Params:
  • option – the option
  • arguments – a list encapsulating the arguments
Returns:true if operation succeeded, false otherwise
/**
         * Processes the option and arguments as needed. This method will
         * be invoked if the given option name matches the option.
         * @param option the option
         * @param arguments a list encapsulating the arguments
         * @return true if operation succeeded, false otherwise
         */
        boolean process(String option, List<String> arguments);

        
The kind of an option.

/**
         * The kind of an option.
         */
        enum Kind {
            
An extended option, such as those prefixed with -X. 
/** An extended option, such as those prefixed with {@code -X}. */
            EXTENDED,
            
A standard option. 
/** A standard option. */
            STANDARD,
            
An implementation-reserved option. 
/** An implementation-reserved option. */
            OTHER;
        }
    }
}