• Home
• com.google.errorprone
• javac
• 9-dev-r3297-2
• source code
• Doclet.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

jdk.javadoc.doclet.Doclet Maven / Gradle / Ivy

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

package jdk.javadoc.doclet;

import java.util.ListIterator;
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:
 * 

 * 
 The tool will create an instance of a doclet using the no-arg constructor
 *  of the doclet class.
 * 
 Next, the tool calls the {@link #init init} method with an appropriate locale
 *  and reporter.
 * 
 Afterwards, the tool calls {@link #getSupportedOptions getSupportedOptions},
 * and {@link #getSupportedSourceVersion getSupportedSourceVersion}.
 * These methods are only called once.
 * 
 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.
 * 
 * 

 * 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 {@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.
     * It is recommended to call this as early as possible, for a
     * uniform localized user experience,
     * @param locale the locale to be used
     * @param reporter the reporter to be used
     */
    public 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".
     * @return name of the Doclet
     */
    public abstract String getName();

    /**
     * Returns all the supported options.
     *
     * @return a Set containing all the supported options, an empty set if none.
     */
    public Set getSupportedOptions();

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

    /**
     * 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
     */
    public boolean run(DocletEnvironment environment);

    /**
     * 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.
         * @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".
         * @return description if set, otherwise an empty String
         */
        String getDescription();

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

        /**
         * Returns the option name. For instance for option "-group", will return "group"
         * @return name of the option, if set, otherwise an empty String
         */
        String getName();

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

        /**
         * Checks if the given option name is handled by this option.
         * @param option the option name with or without the leading "-"
         * @return true if same
         */
        boolean matches(String option);

        /**
         * 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 ListIterator encapsulating the arguments
         * @return true if operation succeeded, false otherwise
         */
        boolean process(String option, ListIterator arguments);

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