1 /*
2 * Copyright (c) 2015, 2020, 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
26 package jdk.javadoc.doclet;
27
28 import java.util.List;
29 import java.util.Locale;
30 import java.util.Set;
31
32 import 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 */
61 public 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 enum Kind {
157 /** An extended option, such as those prefixed with {@code -X}. */
158 EXTENDED,
159 /** A standard option. */
160 STANDARD,
161 /** An implementation-reserved option. */
162 OTHER;
163 }
164 }
165 }