author | pmuthuswamy |
Wed, 02 Aug 2017 12:34:23 -0700 | |
changeset 46081 | 7c6d73d10b6b |
parent 42277 | 2668b0bc7ad7 |
permissions | -rw-r--r-- |
35426 | 1 |
/* |
46081
7c6d73d10b6b
8185194: Missing anchor for package description in package-summary.html pages
pmuthuswamy
parents:
42277
diff
changeset
|
2 |
* Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved. |
35426 | 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 |
||
42277 | 28 |
import java.util.List; |
35426 | 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 |
|
46081
7c6d73d10b6b
8185194: Missing anchor for package description in package-summary.html pages
pmuthuswamy
parents:
42277
diff
changeset
|
36 |
* <a href="package-summary.html#package.description">package description</a>. |
35426 | 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. |
|
40508
74ef30d16fb9
8159305: Enhance the javadoc tool to support module related options
ksrini
parents:
35426
diff
changeset
|
66 |
* |
35426 | 67 |
* @param locale the locale to be used |
68 |
* @param reporter the reporter to be used |
|
69 |
*/ |
|
42277 | 70 |
void init(Locale locale, Reporter reporter); |
35426 | 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". |
|
40508
74ef30d16fb9
8159305: Enhance the javadoc tool to support module related options
ksrini
parents:
35426
diff
changeset
|
76 |
* |
35426 | 77 |
* @return name of the Doclet |
78 |
*/ |
|
42277 | 79 |
String getName(); |
35426 | 80 |
|
81 |
/** |
|
82 |
* Returns all the supported options. |
|
83 |
* |
|
40508
74ef30d16fb9
8159305: Enhance the javadoc tool to support module related options
ksrini
parents:
35426
diff
changeset
|
84 |
* @return a set containing all the supported options, an empty set if none |
35426 | 85 |
*/ |
42277 | 86 |
Set<? extends Option> getSupportedOptions(); |
35426 | 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 |
|
40508
74ef30d16fb9
8159305: Enhance the javadoc tool to support module related options
ksrini
parents:
35426
diff
changeset
|
93 |
* the latest version |
35426 | 94 |
*/ |
42277 | 95 |
SourceVersion getSupportedSourceVersion(); |
35426 | 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 |
*/ |
|
42277 | 104 |
boolean run(DocletEnvironment environment); |
35426 | 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 |
/** |
|
42277 | 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 |
|
35426 | 135 |
*/ |
42277 | 136 |
List<String> getNames(); |
35426 | 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 |
|
42277 | 148 |
* @param arguments a list encapsulating the arguments |
35426 | 149 |
* @return true if operation succeeded, false otherwise |
150 |
*/ |
|
42277 | 151 |
boolean process(String option, List<String> arguments); |
35426 | 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 |
} |