1/* 2 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package jdk.javadoc.doclet; 27 28import java.util.List; 29import java.util.Locale; 30import java.util.Set; 31 32import javax.lang.model.SourceVersion; 33 34/** 35 * The user doclet must implement this interface, as described in the 36 * <a href="package-summary.html#package.description">package description</a>. 37 * Each implementation of a Doclet must provide a public no-argument constructor 38 * to be used by tools to instantiate the doclet. The tool infrastructure will 39 * interact with classes implementing this interface as follows: 40 * <ol> 41 * <li> The tool will create an instance of a doclet using the no-arg constructor 42 * of the doclet class. 43 * <li> Next, the tool calls the {@link #init init} method with an appropriate locale 44 * and reporter. 45 * <li> Afterwards, the tool calls {@link #getSupportedOptions getSupportedOptions}, 46 * and {@link #getSupportedSourceVersion getSupportedSourceVersion}. 47 * These methods are only called once. 48 * <li> As appropriate, the tool calls the {@link #run run} method on the doclet 49 * object, giving it a DocletEnvironment object, from which the doclet can determine 50 * the elements to be included in the documentation. 51 * </ol> 52 * <p> 53 * If a doclet object is created and used without the above protocol being followed, 54 * then the doclet's behavior is not defined by this interface specification. 55 * <p> To start the doclet, pass {@code -doclet} followed by the fully-qualified 56 * name of the entry point class (i.e. the implementation of this interface) on 57 * the javadoc tool command line. 58 * 59 * @since 9 60 */ 61public interface Doclet { 62 63 /** 64 * Initializes this doclet with the given locale and error reporter. 65 * This locale will be used by the reporter and the doclet components. 66 * 67 * @param locale the locale to be used 68 * @param reporter the reporter to be used 69 */ 70 void init(Locale locale, Reporter reporter); 71 72 /** 73 * Returns a name identifying the doclet. A name is a simple identifier 74 * without white spaces, as defined in <cite>The Java™ Language Specification</cite>, 75 * section 6.2 "Names and Identifiers". 76 * 77 * @return name of the Doclet 78 */ 79 String getName(); 80 81 /** 82 * Returns all the supported options. 83 * 84 * @return a set containing all the supported options, an empty set if none 85 */ 86 Set<? extends Option> getSupportedOptions(); 87 88 /** 89 * Returns the version of the Java Programming Language supported 90 * by this doclet. 91 * 92 * @return the language version supported by this doclet, usually 93 * the latest version 94 */ 95 SourceVersion getSupportedSourceVersion(); 96 97 /** 98 * The entry point of the doclet. Further processing will commence as 99 * instructed by this method. 100 * 101 * @param environment from which essential information can be extracted 102 * @return true on success 103 */ 104 boolean run(DocletEnvironment environment); 105 106 /** 107 * An encapsulation of option name, aliases, parameters and descriptions 108 * as used by the Doclet. 109 */ 110 interface Option { 111 /** 112 * Returns the number of arguments, this option will consume. 113 * @return number of consumed arguments 114 */ 115 int getArgumentCount(); 116 117 /** 118 * Returns the description of the option. For instance, the option "group", would 119 * return the synopsis of the option such as, "groups the documents". 120 * @return description if set, otherwise an empty String 121 */ 122 String getDescription(); 123 124 /** 125 * Returns the option kind. 126 * @return the kind of this option 127 */ 128 Option.Kind getKind(); 129 130 /** 131 * Returns the list of names that may be used to identify the option. For instance, the 132 * list could be {@code ["-classpath", "--class-path"]} for the 133 * option "-classpath", with an alias "--class-path". 134 * @return the names of the option 135 */ 136 List<String> getNames(); 137 138 /** 139 * Returns the parameters of the option. For instance "name <p1>:<p2>.." 140 * @return parameters if set, otherwise an empty String 141 */ 142 String getParameters(); 143 144 /** 145 * Processes the option and arguments as needed. This method will 146 * be invoked if the given option name matches the option. 147 * @param option the option 148 * @param arguments a list encapsulating the arguments 149 * @return true if operation succeeded, false otherwise 150 */ 151 boolean process(String option, List<String> arguments); 152 153 /** 154 * The kind of an option. 155 */ 156 public static enum Kind { 157 /** an extended option, such as those prefixed with -X */ 158 EXTENDED, 159 /** a standard option */ 160 STANDARD, 161 /** an implementation reserved option */ 162 OTHER; 163 } 164 } 165} 166