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}