001package ball.tools.javadoc;
002/*-
003 * ##########################################################################
004 * Utilities
005 * $Id: Doclet.java 5285 2020-02-05 04:23:21Z ball $
006 * $HeadURL: svn+ssh://svn.hcf.dev/var/spool/scm/repository.svn/ball-util/trunk/src/main/java/ball/tools/javadoc/Doclet.java $
007 * %%
008 * Copyright (C) 2008 - 2020 Allen D. Ball
009 * %%
010 * Licensed under the Apache License, Version 2.0 (the "License");
011 * you may not use this file except in compliance with the License.
012 * You may obtain a copy of the License at
013 *
014 *      http://www.apache.org/licenses/LICENSE-2.0
015 *
016 * Unless required by applicable law or agreed to in writing, software
017 * distributed under the License is distributed on an "AS IS" BASIS,
018 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
019 * See the License for the specific language governing permissions and
020 * limitations under the License.
021 * ##########################################################################
022 */
023import com.sun.javadoc.RootDoc;
024import com.sun.javadoc.DocErrorReporter;
025import com.sun.javadoc.LanguageVersion;
026
027/**
028 * {@link com.sun.javadoc.Doclet} "interface."  {@link Doclet}s are not
029 * actually part of a class hierarchy.  The methods described here are
030 * {@code static} in the implementations.  This interface is provided to
031 * document the methods and to use as a possible basis for creating
032 * {@link java.lang.reflect.Proxy}-based solutions.
033 *
034 * The standard {@code OpenJDK} {@link javax.tools.DocumentationTool}
035 * dispatches to {@link com.sun.tools.doclets.standard.Standard} which
036 * in-turn dispatches to
037 * {@link com.sun.tools.doclets.formats.html.HtmlDoclet}.
038 *
039 * @author {@link.uri mailto:ball@hcf.dev Allen D. Ball}
040 * @version $Revision: 5285 $
041 */
042public interface Doclet {
043
044    /**
045     * Check {@code options} have correct arguments.
046     *
047     * The {@link com.sun.tools.doclets.standard.Standard} supplies an
048     * instance of {@code com.sun.tools.javadoc.Messager} {@link Doclet} for
049     * {@link DocErrorReporter}.
050     *
051     * @param   options         The {@code options} and their arguments.
052     * @param   reporter        The {@link DocErrorReporter}.
053     *
054     * @return  {@code true} if the {@code options} are valid; {@code false}
055     *          otherwise.
056     */
057    public boolean validOptions(String[][] options, DocErrorReporter reporter);
058
059    /**
060     * Check for {@link Doclet} added options.  E.g., {@code "-d docs"}
061     * should return {@code 2}.
062     *
063     * @param   option          The {@link String option} to check.
064     *
065     * @return  Number of arguments required to specify; {@code 0} means the
066     *          option is unknown and a negative value indicates an error.
067     */
068    public int optionLength(String option);
069
070    /**
071     * Starting point for document generation.
072     *
073     * The {@link com.sun.tools.doclets.standard.Standard} supplies an
074     * instance of {@code com.sun.tools.javadoc.RootDocImpl} {@link Doclet}
075     * for {@link RootDoc}.
076     *
077     * @param   root            The {@link RootDoc}.
078     *
079     * @return  {@code true} on success; {@code false} otherwise.
080     */
081    public boolean start(RootDoc root);
082
083    /**
084     * Return the version of the Java Programming Language supported
085     * by this {@link Doclet}.
086     *
087     * @return  The minimum {@link LanguageVersion} supported by this
088     *          {@link Doclet}.
089     */
090    public LanguageVersion languageVersion();
091}