author | jjg |
Thu, 15 Nov 2012 23:07:24 -0800 | |
changeset 14545 | 2e7bab0639b8 |
parent 14368 | 6f4c62de6985 |
child 16319 | e586bfeb39c5 |
permissions | -rw-r--r-- |
10 | 1 |
/* |
13842
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
2 |
* Copyright (c) 2001, 2012, Oracle and/or its affiliates. All rights reserved. |
10 | 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 |
|
5520 | 7 |
* published by the Free Software Foundation. Oracle designates this |
10 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5520 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
10 | 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 |
* |
|
5520 | 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. |
|
10 | 24 |
*/ |
25 |
||
26 |
package com.sun.tools.doclets.internal.toolkit.taglets; |
|
27 |
||
28 |
import java.io.*; |
|
29 |
import java.lang.reflect.*; |
|
30 |
import java.net.*; |
|
31 |
import java.util.*; |
|
32 |
||
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
33 |
import javax.tools.DocumentationTool; |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
34 |
import javax.tools.JavaFileManager; |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
35 |
|
14258 | 36 |
import com.sun.javadoc.*; |
37 |
import com.sun.tools.doclets.internal.toolkit.util.*; |
|
38 |
||
10 | 39 |
/** |
40 |
* Manages the<code>Taglet</code>s used by doclets. |
|
41 |
* |
|
14260
727a84636f12
8000665: fix "internal API" comments on javadoc files
jjg
parents:
14258
diff
changeset
|
42 |
* <p><b>This is NOT part of any supported API. |
727a84636f12
8000665: fix "internal API" comments on javadoc files
jjg
parents:
14258
diff
changeset
|
43 |
* If you write code that depends on this, you do so at your own risk. |
727a84636f12
8000665: fix "internal API" comments on javadoc files
jjg
parents:
14258
diff
changeset
|
44 |
* This code and its internal interfaces are subject to change or |
727a84636f12
8000665: fix "internal API" comments on javadoc files
jjg
parents:
14258
diff
changeset
|
45 |
* deletion without notice.</b> |
10 | 46 |
* |
47 |
* @author Jamie Ho |
|
48 |
* @since 1.4 |
|
49 |
*/ |
|
50 |
||
51 |
public class TagletManager { |
|
52 |
||
53 |
/** |
|
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
54 |
* The default separator for the simple tag option. |
10 | 55 |
*/ |
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
56 |
public static final char SIMPLE_TAGLET_OPT_SEPARATOR = ':'; |
10 | 57 |
|
58 |
/** |
|
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
59 |
* The alternate separator for simple tag options. Use this |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
60 |
* when you want the default separator to be in the name of the |
10 | 61 |
* custom tag. |
62 |
*/ |
|
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
63 |
public static final String ALT_SIMPLE_TAGLET_OPT_SEPARATOR = "-"; |
10 | 64 |
|
65 |
/** |
|
66 |
* The map of custom tags. |
|
67 |
*/ |
|
868 | 68 |
private LinkedHashMap<String,Taglet> customTags; |
10 | 69 |
|
70 |
/** |
|
71 |
* The array of custom tags that can appear in packages. |
|
72 |
*/ |
|
73 |
private Taglet[] packageTags; |
|
74 |
||
75 |
/** |
|
76 |
* The array of custom tags that can appear in classes or interfaces. |
|
77 |
*/ |
|
78 |
private Taglet[] typeTags; |
|
79 |
||
80 |
/** |
|
81 |
* The array of custom tags that can appear in fields. |
|
82 |
*/ |
|
83 |
private Taglet[] fieldTags; |
|
84 |
||
85 |
/** |
|
86 |
* The array of custom tags that can appear in constructors. |
|
87 |
*/ |
|
88 |
private Taglet[] constructorTags; |
|
89 |
||
90 |
/** |
|
91 |
* The array of custom tags that can appear in methods. |
|
92 |
*/ |
|
93 |
private Taglet[] methodTags; |
|
94 |
||
95 |
/** |
|
96 |
* The array of custom tags that can appear in the overview. |
|
97 |
*/ |
|
98 |
private Taglet[] overviewTags; |
|
99 |
||
100 |
/** |
|
101 |
* The array of custom tags that can appear in comments. |
|
102 |
*/ |
|
103 |
private Taglet[] inlineTags; |
|
104 |
||
105 |
/** |
|
106 |
* The array of custom tags that can appear in the serialized form. |
|
107 |
*/ |
|
108 |
private Taglet[] serializedFormTags; |
|
109 |
||
110 |
/** |
|
111 |
* The message retriever that will be used to print error messages. |
|
112 |
*/ |
|
113 |
private MessageRetriever message; |
|
114 |
||
115 |
/** |
|
116 |
* Keep track of standard tags. |
|
117 |
*/ |
|
868 | 118 |
private Set<String> standardTags; |
10 | 119 |
|
120 |
/** |
|
121 |
* Keep track of standard tags in lowercase to compare for better |
|
122 |
* error messages when a tag like @docRoot is mistakenly spelled |
|
123 |
* lowercase @docroot. |
|
124 |
*/ |
|
868 | 125 |
private Set<String> standardTagsLowercase; |
10 | 126 |
|
127 |
/** |
|
128 |
* Keep track of overriden standard tags. |
|
129 |
*/ |
|
868 | 130 |
private Set<String> overridenStandardTags; |
10 | 131 |
|
132 |
/** |
|
133 |
* Keep track of the tags that may conflict |
|
134 |
* with standard tags in the future (any custom tag without |
|
135 |
* a period in its name). |
|
136 |
*/ |
|
868 | 137 |
private Set<String> potentiallyConflictingTags; |
10 | 138 |
|
139 |
/** |
|
140 |
* The set of unseen custom tags. |
|
141 |
*/ |
|
868 | 142 |
private Set<String> unseenCustomTags; |
10 | 143 |
|
144 |
/** |
|
145 |
* True if we do not want to use @since tags. |
|
146 |
*/ |
|
147 |
private boolean nosince; |
|
148 |
||
149 |
/** |
|
150 |
* True if we want to use @version tags. |
|
151 |
*/ |
|
152 |
private boolean showversion; |
|
153 |
||
154 |
/** |
|
155 |
* True if we want to use @author tags. |
|
156 |
*/ |
|
157 |
private boolean showauthor; |
|
158 |
||
159 |
/** |
|
160 |
* Construct a new <code>TagletManager</code>. |
|
161 |
* @param nosince true if we do not want to use @since tags. |
|
162 |
* @param showversion true if we want to use @version tags. |
|
163 |
* @param showauthor true if we want to use @author tags. |
|
164 |
* @param message the message retriever to print warnings. |
|
165 |
*/ |
|
166 |
public TagletManager(boolean nosince, boolean showversion, |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
167 |
boolean showauthor, MessageRetriever message) { |
868 | 168 |
overridenStandardTags = new HashSet<String>(); |
169 |
potentiallyConflictingTags = new HashSet<String>(); |
|
170 |
standardTags = new HashSet<String>(); |
|
171 |
standardTagsLowercase = new HashSet<String>(); |
|
172 |
unseenCustomTags = new HashSet<String>(); |
|
173 |
customTags = new LinkedHashMap<String,Taglet>(); |
|
10 | 174 |
this.nosince = nosince; |
175 |
this.showversion = showversion; |
|
176 |
this.showauthor = showauthor; |
|
177 |
this.message = message; |
|
178 |
initStandardTags(); |
|
179 |
initStandardTagsLowercase(); |
|
180 |
} |
|
181 |
||
182 |
/** |
|
183 |
* Add a new <code>CustomTag</code>. This is used to add a Taglet from within |
|
184 |
* a Doclet. No message is printed to indicate that the Taglet is properly |
|
185 |
* registered because these Taglets are typically added for every execution of the |
|
186 |
* Doclet. We don't want to see this type of error message every time. |
|
187 |
* @param customTag the new <code>CustomTag</code> to add. |
|
188 |
*/ |
|
189 |
public void addCustomTag(Taglet customTag) { |
|
190 |
if (customTag != null) { |
|
191 |
String name = customTag.getName(); |
|
192 |
if (customTags.containsKey(name)) { |
|
193 |
customTags.remove(name); |
|
194 |
} |
|
195 |
customTags.put(name, customTag); |
|
196 |
checkTagName(name); |
|
197 |
} |
|
198 |
} |
|
199 |
||
200 |
/** |
|
201 |
* Add a new <code>Taglet</code>. Print a message to indicate whether or not |
|
202 |
* the Taglet was registered properly. |
|
203 |
* @param classname the name of the class representing the custom tag. |
|
204 |
* @param tagletPath the path to the class representing the custom tag. |
|
205 |
*/ |
|
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
206 |
public void addCustomTag(String classname, JavaFileManager fileManager, String tagletPath) { |
10 | 207 |
try { |
868 | 208 |
Class<?> customTagClass = null; |
10 | 209 |
// construct class loader |
210 |
String cpString = null; // make sure env.class.path defaults to dot |
|
211 |
||
14545
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
212 |
ClassLoader tagClassLoader; |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
213 |
if (fileManager != null && fileManager.hasLocation(DocumentationTool.Location.TAGLET_PATH)) { |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
214 |
tagClassLoader = fileManager.getClassLoader(DocumentationTool.Location.TAGLET_PATH); |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
215 |
} else { |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
216 |
// do prepends to get correct ordering |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
217 |
cpString = appendPath(System.getProperty("env.class.path"), cpString); |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
218 |
cpString = appendPath(System.getProperty("java.class.path"), cpString); |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
219 |
cpString = appendPath(tagletPath, cpString); |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
220 |
tagClassLoader = new URLClassLoader(pathToURLs(cpString)); |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
221 |
} |
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
222 |
|
2e7bab0639b8
6493690: javadoc should have a javax.tools.Tool service provider installed in tools.jar
jjg
parents:
14368
diff
changeset
|
223 |
customTagClass = tagClassLoader.loadClass(classname); |
10 | 224 |
Method meth = customTagClass.getMethod("register", |
1789
7ac8c0815000
6765045: Remove rawtypes warnings from langtools
mcimadamore
parents:
1264
diff
changeset
|
225 |
new Class<?>[] {java.util.Map.class}); |
10 | 226 |
Object[] list = customTags.values().toArray(); |
227 |
Taglet lastTag = (list != null && list.length > 0) |
|
228 |
? (Taglet) list[list.length-1] : null; |
|
229 |
meth.invoke(null, new Object[] {customTags}); |
|
230 |
list = customTags.values().toArray(); |
|
231 |
Object newLastTag = (list != null&& list.length > 0) |
|
868 | 232 |
? list[list.length-1] : null; |
10 | 233 |
if (lastTag != newLastTag) { |
234 |
//New taglets must always be added to the end of the LinkedHashMap. |
|
235 |
//If the current and previous last taglet are not equal, that |
|
236 |
//means a new Taglet has been added. |
|
237 |
message.notice("doclet.Notice_taglet_registered", classname); |
|
238 |
if (newLastTag != null) { |
|
239 |
checkTaglet(newLastTag); |
|
240 |
} |
|
241 |
} |
|
242 |
} catch (Exception exc) { |
|
243 |
message.error("doclet.Error_taglet_not_registered", exc.getClass().getName(), classname); |
|
244 |
} |
|
245 |
||
246 |
} |
|
247 |
||
248 |
private String appendPath(String path1, String path2) { |
|
249 |
if (path1 == null || path1.length() == 0) { |
|
250 |
return path2 == null ? "." : path2; |
|
251 |
} else if (path2 == null || path2.length() == 0) { |
|
252 |
return path1; |
|
253 |
} else { |
|
254 |
return path1 + File.pathSeparator + path2; |
|
255 |
} |
|
256 |
} |
|
257 |
||
258 |
/** |
|
259 |
* Utility method for converting a search path string to an array |
|
260 |
* of directory and JAR file URLs. |
|
261 |
* |
|
262 |
* @param path the search path string |
|
263 |
* @return the resulting array of directory and JAR file URLs |
|
264 |
*/ |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
265 |
private URL[] pathToURLs(String path) { |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
266 |
Set<URL> urls = new LinkedHashSet<URL>(); |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
267 |
for (String s: path.split(File.pathSeparator)) { |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
268 |
if (s.isEmpty()) continue; |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
269 |
try { |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
270 |
urls.add(new File(s).getAbsoluteFile().toURI().toURL()); |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
271 |
} catch (MalformedURLException e) { |
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
272 |
message.error("doclet.MalformedURL", s); |
10 | 273 |
} |
274 |
} |
|
14368
6f4c62de6985
8001664: refactor javadoc to use abstraction to handle files
jjg
parents:
14263
diff
changeset
|
275 |
return urls.toArray(new URL[urls.size()]); |
10 | 276 |
} |
277 |
||
278 |
||
279 |
/** |
|
280 |
* Add a new <code>SimpleTaglet</code>. If this tag already exists |
|
281 |
* and the header passed as an argument is null, move tag to the back of the |
|
282 |
* list. If this tag already exists and the header passed as an argument is |
|
283 |
* not null, overwrite previous tag with new one. Otherwise, add new |
|
284 |
* SimpleTaglet to list. |
|
285 |
* @param tagName the name of this tag |
|
286 |
* @param header the header to output. |
|
287 |
* @param locations the possible locations that this tag |
|
288 |
* can appear in. |
|
289 |
*/ |
|
290 |
public void addNewSimpleCustomTag(String tagName, String header, String locations) { |
|
291 |
if (tagName == null || locations == null) { |
|
292 |
return; |
|
293 |
} |
|
868 | 294 |
Taglet tag = customTags.get(tagName); |
10 | 295 |
locations = locations.toLowerCase(); |
296 |
if (tag == null || header != null) { |
|
297 |
customTags.remove(tagName); |
|
298 |
customTags.put(tagName, new SimpleTaglet(tagName, header, locations)); |
|
299 |
if (locations != null && locations.indexOf('x') == -1) { |
|
300 |
checkTagName(tagName); |
|
301 |
} |
|
302 |
} else { |
|
303 |
//Move to back |
|
304 |
customTags.remove(tagName); |
|
305 |
customTags.put(tagName, tag); |
|
306 |
} |
|
307 |
} |
|
308 |
||
309 |
/** |
|
310 |
* Given a tag name, add it to the set of tags it belongs to. |
|
311 |
*/ |
|
312 |
private void checkTagName(String name) { |
|
313 |
if (standardTags.contains(name)) { |
|
314 |
overridenStandardTags.add(name); |
|
315 |
} else { |
|
316 |
if (name.indexOf('.') == -1) { |
|
317 |
potentiallyConflictingTags.add(name); |
|
318 |
} |
|
319 |
unseenCustomTags.add(name); |
|
320 |
} |
|
321 |
} |
|
322 |
||
323 |
/** |
|
324 |
* Check the taglet to see if it is a legacy taglet. Also |
|
325 |
* check its name for errors. |
|
326 |
*/ |
|
327 |
private void checkTaglet(Object taglet) { |
|
328 |
if (taglet instanceof Taglet) { |
|
329 |
checkTagName(((Taglet) taglet).getName()); |
|
330 |
} else if (taglet instanceof com.sun.tools.doclets.Taglet) { |
|
331 |
com.sun.tools.doclets.Taglet legacyTaglet = (com.sun.tools.doclets.Taglet) taglet; |
|
332 |
customTags.remove(legacyTaglet.getName()); |
|
333 |
customTags.put(legacyTaglet.getName(), new LegacyTaglet(legacyTaglet)); |
|
334 |
checkTagName(legacyTaglet.getName()); |
|
335 |
} else { |
|
336 |
throw new IllegalArgumentException("Given object is not a taglet."); |
|
337 |
} |
|
338 |
} |
|
339 |
||
340 |
/** |
|
341 |
* Given a name of a seen custom tag, remove it from the set of unseen |
|
342 |
* custom tags. |
|
343 |
* @param name the name of the seen custom tag. |
|
344 |
*/ |
|
345 |
public void seenCustomTag(String name) { |
|
346 |
unseenCustomTags.remove(name); |
|
347 |
} |
|
348 |
||
349 |
/** |
|
350 |
* Given an array of <code>Tag</code>s, check for spelling mistakes. |
|
351 |
* @param doc the Doc object that holds the tags. |
|
352 |
* @param tags the list of <code>Tag</code>s to check. |
|
353 |
* @param areInlineTags true if the array of tags are inline and false otherwise. |
|
354 |
*/ |
|
355 |
public void checkTags(Doc doc, Tag[] tags, boolean areInlineTags) { |
|
356 |
if (tags == null) { |
|
357 |
return; |
|
358 |
} |
|
359 |
Taglet taglet; |
|
360 |
for (int i = 0; i < tags.length; i++) { |
|
361 |
String name = tags[i].name(); |
|
362 |
if (name.length() > 0 && name.charAt(0) == '@') { |
|
363 |
name = name.substring(1, name.length()); |
|
364 |
} |
|
365 |
if (! (standardTags.contains(name) || customTags.containsKey(name))) { |
|
366 |
if (standardTagsLowercase.contains(name.toLowerCase())) { |
|
367 |
message.warning(tags[i].position(), "doclet.UnknownTagLowercase", tags[i].name()); |
|
368 |
continue; |
|
369 |
} else { |
|
370 |
message.warning(tags[i].position(), "doclet.UnknownTag", tags[i].name()); |
|
371 |
continue; |
|
372 |
} |
|
373 |
} |
|
374 |
//Check if this tag is being used in the wrong location. |
|
868 | 375 |
if ((taglet = customTags.get(name)) != null) { |
10 | 376 |
if (areInlineTags && ! taglet.isInlineTag()) { |
377 |
printTagMisuseWarn(taglet, tags[i], "inline"); |
|
378 |
} |
|
379 |
if ((doc instanceof RootDoc) && ! taglet.inOverview()) { |
|
380 |
printTagMisuseWarn(taglet, tags[i], "overview"); |
|
381 |
} else if ((doc instanceof PackageDoc) && ! taglet.inPackage()) { |
|
382 |
printTagMisuseWarn(taglet, tags[i], "package"); |
|
383 |
} else if ((doc instanceof ClassDoc) && ! taglet.inType()) { |
|
384 |
printTagMisuseWarn(taglet, tags[i], "class"); |
|
385 |
} else if ((doc instanceof ConstructorDoc) && ! taglet.inConstructor()) { |
|
386 |
printTagMisuseWarn(taglet, tags[i], "constructor"); |
|
387 |
} else if ((doc instanceof FieldDoc) && ! taglet.inField()) { |
|
388 |
printTagMisuseWarn(taglet, tags[i], "field"); |
|
389 |
} else if ((doc instanceof MethodDoc) && ! taglet.inMethod()) { |
|
390 |
printTagMisuseWarn(taglet, tags[i], "method"); |
|
391 |
} |
|
392 |
} |
|
393 |
} |
|
394 |
} |
|
395 |
||
396 |
/** |
|
397 |
* Given the taglet, the tag and the type of documentation that the tag |
|
398 |
* was found in, print a tag misuse warning. |
|
399 |
* @param taglet the taglet representing the misused tag. |
|
400 |
* @param tag the misused tag. |
|
401 |
* @param holderType the type of documentation that the misused tag was found in. |
|
402 |
*/ |
|
403 |
private void printTagMisuseWarn(Taglet taglet, Tag tag, String holderType) { |
|
868 | 404 |
Set<String> locationsSet = new LinkedHashSet<String>(); |
10 | 405 |
if (taglet.inOverview()) { |
406 |
locationsSet.add("overview"); |
|
407 |
} |
|
408 |
if (taglet.inPackage()) { |
|
409 |
locationsSet.add("package"); |
|
410 |
} |
|
411 |
if (taglet.inType()) { |
|
412 |
locationsSet.add("class/interface"); |
|
413 |
} |
|
414 |
if (taglet.inConstructor()) { |
|
415 |
locationsSet.add("constructor"); |
|
416 |
} |
|
417 |
if (taglet.inField()) { |
|
418 |
locationsSet.add("field"); |
|
419 |
} |
|
420 |
if (taglet.inMethod()) { |
|
421 |
locationsSet.add("method"); |
|
422 |
} |
|
423 |
if (taglet.isInlineTag()) { |
|
424 |
locationsSet.add("inline text"); |
|
425 |
} |
|
868 | 426 |
String[] locations = locationsSet.toArray(new String[]{}); |
10 | 427 |
if (locations == null || locations.length == 0) { |
428 |
//This known tag is excluded. |
|
429 |
return; |
|
430 |
} |
|
14263 | 431 |
StringBuilder combined_locations = new StringBuilder(); |
10 | 432 |
for (int i = 0; i < locations.length; i++) { |
433 |
if (i > 0) { |
|
434 |
combined_locations.append(", "); |
|
435 |
} |
|
436 |
combined_locations.append(locations[i]); |
|
437 |
} |
|
438 |
message.warning(tag.position(), "doclet.tag_misuse", |
|
439 |
"@" + taglet.getName(), holderType, combined_locations.toString()); |
|
440 |
} |
|
441 |
||
442 |
/** |
|
443 |
* Return the array of <code>Taglet</code>s that can |
|
444 |
* appear in packages. |
|
445 |
* @return the array of <code>Taglet</code>s that can |
|
446 |
* appear in packages. |
|
447 |
*/ |
|
448 |
public Taglet[] getPackageCustomTags() { |
|
449 |
if (packageTags == null) { |
|
450 |
initCustomTagArrays(); |
|
451 |
} |
|
452 |
return packageTags; |
|
453 |
} |
|
454 |
||
455 |
/** |
|
456 |
* Return the array of <code>Taglet</code>s that can |
|
457 |
* appear in classes or interfaces. |
|
458 |
* @return the array of <code>Taglet</code>s that can |
|
459 |
* appear in classes or interfaces. |
|
460 |
*/ |
|
461 |
public Taglet[] getTypeCustomTags() { |
|
462 |
if (typeTags == null) { |
|
463 |
initCustomTagArrays(); |
|
464 |
} |
|
465 |
return typeTags; |
|
466 |
} |
|
467 |
||
468 |
/** |
|
469 |
* Return the array of inline <code>Taglet</code>s that can |
|
470 |
* appear in comments. |
|
471 |
* @return the array of <code>Taglet</code>s that can |
|
472 |
* appear in comments. |
|
473 |
*/ |
|
474 |
public Taglet[] getInlineCustomTags() { |
|
475 |
if (inlineTags == null) { |
|
476 |
initCustomTagArrays(); |
|
477 |
} |
|
478 |
return inlineTags; |
|
479 |
} |
|
480 |
||
481 |
/** |
|
482 |
* Return the array of <code>Taglet</code>s that can |
|
483 |
* appear in fields. |
|
484 |
* @return the array of <code>Taglet</code>s that can |
|
485 |
* appear in field. |
|
486 |
*/ |
|
487 |
public Taglet[] getFieldCustomTags() { |
|
488 |
if (fieldTags == null) { |
|
489 |
initCustomTagArrays(); |
|
490 |
} |
|
491 |
return fieldTags; |
|
492 |
} |
|
493 |
||
494 |
/** |
|
495 |
* Return the array of <code>Taglet</code>s that can |
|
496 |
* appear in the serialized form. |
|
497 |
* @return the array of <code>Taglet</code>s that can |
|
498 |
* appear in the serialized form. |
|
499 |
*/ |
|
500 |
public Taglet[] getSerializedFormTags() { |
|
501 |
if (serializedFormTags == null) { |
|
502 |
initCustomTagArrays(); |
|
503 |
} |
|
504 |
return serializedFormTags; |
|
505 |
} |
|
506 |
||
507 |
/** |
|
508 |
* @return the array of <code>Taglet</code>s that can |
|
509 |
* appear in the given Doc. |
|
510 |
*/ |
|
511 |
public Taglet[] getCustomTags(Doc doc) { |
|
512 |
if (doc instanceof ConstructorDoc) { |
|
513 |
return getConstructorCustomTags(); |
|
514 |
} else if (doc instanceof MethodDoc) { |
|
515 |
return getMethodCustomTags(); |
|
516 |
} else if (doc instanceof FieldDoc) { |
|
517 |
return getFieldCustomTags(); |
|
518 |
} else if (doc instanceof ClassDoc) { |
|
519 |
return getTypeCustomTags(); |
|
520 |
} else if (doc instanceof PackageDoc) { |
|
521 |
return getPackageCustomTags(); |
|
522 |
} else if (doc instanceof RootDoc) { |
|
523 |
return getOverviewCustomTags(); |
|
524 |
} |
|
525 |
return null; |
|
526 |
} |
|
527 |
||
528 |
/** |
|
529 |
* Return the array of <code>Taglet</code>s that can |
|
530 |
* appear in constructors. |
|
531 |
* @return the array of <code>Taglet</code>s that can |
|
532 |
* appear in constructors. |
|
533 |
*/ |
|
534 |
public Taglet[] getConstructorCustomTags() { |
|
535 |
if (constructorTags == null) { |
|
536 |
initCustomTagArrays(); |
|
537 |
} |
|
538 |
return constructorTags; |
|
539 |
} |
|
540 |
||
541 |
/** |
|
542 |
* Return the array of <code>Taglet</code>s that can |
|
543 |
* appear in methods. |
|
544 |
* @return the array of <code>Taglet</code>s that can |
|
545 |
* appear in methods. |
|
546 |
*/ |
|
547 |
public Taglet[] getMethodCustomTags() { |
|
548 |
if (methodTags == null) { |
|
549 |
initCustomTagArrays(); |
|
550 |
} |
|
551 |
return methodTags; |
|
552 |
} |
|
553 |
||
554 |
/** |
|
555 |
* Return the array of <code>Taglet</code>s that can |
|
556 |
* appear in an overview. |
|
557 |
* @return the array of <code>Taglet</code>s that can |
|
558 |
* appear in overview. |
|
559 |
*/ |
|
560 |
public Taglet[] getOverviewCustomTags() { |
|
561 |
if (overviewTags == null) { |
|
562 |
initCustomTagArrays(); |
|
563 |
} |
|
564 |
return overviewTags; |
|
565 |
} |
|
566 |
||
567 |
/** |
|
568 |
* Initialize the custom tag arrays. |
|
569 |
*/ |
|
570 |
private void initCustomTagArrays() { |
|
868 | 571 |
Iterator<Taglet> it = customTags.values().iterator(); |
572 |
ArrayList<Taglet> pTags = new ArrayList<Taglet>(customTags.size()); |
|
573 |
ArrayList<Taglet> tTags = new ArrayList<Taglet>(customTags.size()); |
|
574 |
ArrayList<Taglet> fTags = new ArrayList<Taglet>(customTags.size()); |
|
575 |
ArrayList<Taglet> cTags = new ArrayList<Taglet>(customTags.size()); |
|
576 |
ArrayList<Taglet> mTags = new ArrayList<Taglet>(customTags.size()); |
|
577 |
ArrayList<Taglet> iTags = new ArrayList<Taglet>(customTags.size()); |
|
578 |
ArrayList<Taglet> oTags = new ArrayList<Taglet>(customTags.size()); |
|
13842
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
579 |
ArrayList<Taglet> sTags = new ArrayList<Taglet>(); |
10 | 580 |
Taglet current; |
581 |
while (it.hasNext()) { |
|
868 | 582 |
current = it.next(); |
10 | 583 |
if (current.inPackage() && !current.isInlineTag()) { |
584 |
pTags.add(current); |
|
585 |
} |
|
586 |
if (current.inType() && !current.isInlineTag()) { |
|
587 |
tTags.add(current); |
|
588 |
} |
|
589 |
if (current.inField() && !current.isInlineTag()) { |
|
590 |
fTags.add(current); |
|
591 |
} |
|
592 |
if (current.inConstructor() && !current.isInlineTag()) { |
|
593 |
cTags.add(current); |
|
594 |
} |
|
595 |
if (current.inMethod() && !current.isInlineTag()) { |
|
596 |
mTags.add(current); |
|
597 |
} |
|
598 |
if (current.isInlineTag()) { |
|
599 |
iTags.add(current); |
|
600 |
} |
|
601 |
if (current.inOverview() && !current.isInlineTag()) { |
|
602 |
oTags.add(current); |
|
603 |
} |
|
604 |
} |
|
868 | 605 |
packageTags = pTags.toArray(new Taglet[] {}); |
606 |
typeTags = tTags.toArray(new Taglet[] {}); |
|
607 |
fieldTags = fTags.toArray(new Taglet[] {}); |
|
608 |
constructorTags = cTags.toArray(new Taglet[] {}); |
|
609 |
methodTags = mTags.toArray(new Taglet[] {}); |
|
610 |
overviewTags = oTags.toArray(new Taglet[] {}); |
|
611 |
inlineTags = iTags.toArray(new Taglet[] {}); |
|
10 | 612 |
|
613 |
//Init the serialized form tags |
|
13842
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
614 |
sTags.add(customTags.get("serialData")); |
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
615 |
sTags.add(customTags.get("throws")); |
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
616 |
if (!nosince) |
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
617 |
sTags.add(customTags.get("since")); |
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
618 |
sTags.add(customTags.get("see")); |
6908f6badce4
7180906: Javadoc tool does not apply parameter -nosince
bpatel
parents:
5520
diff
changeset
|
619 |
serializedFormTags = sTags.toArray(new Taglet[] {}); |
10 | 620 |
} |
621 |
||
622 |
/** |
|
623 |
* Initialize standard Javadoc tags for ordering purposes. |
|
624 |
*/ |
|
625 |
private void initStandardTags() { |
|
626 |
Taglet temp; |
|
627 |
customTags.put((temp = new ParamTaglet()).getName(), temp); |
|
628 |
customTags.put((temp = new ReturnTaglet()).getName(), temp); |
|
629 |
customTags.put((temp = new ThrowsTaglet()).getName(), temp); |
|
630 |
customTags.put((temp = new SimpleTaglet("exception", |
|
631 |
null, SimpleTaglet.METHOD + SimpleTaglet.CONSTRUCTOR)).getName(), temp); |
|
632 |
if (!nosince) { |
|
633 |
customTags.put((temp = new SimpleTaglet("since", message.getText("doclet.Since"), |
|
634 |
SimpleTaglet.ALL)).getName(), temp); |
|
635 |
} |
|
636 |
if (showversion) { |
|
637 |
customTags.put((temp = new SimpleTaglet("version", message.getText("doclet.Version"), |
|
638 |
SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW)).getName(), temp); |
|
639 |
} |
|
640 |
if (showauthor) { |
|
641 |
customTags.put((temp = new SimpleTaglet("author", message.getText("doclet.Author"), |
|
642 |
SimpleTaglet.PACKAGE + SimpleTaglet.TYPE + SimpleTaglet.OVERVIEW)).getName(), temp); |
|
643 |
} |
|
644 |
customTags.put((temp = new SimpleTaglet("serialData", message.getText("doclet.SerialData"), |
|
645 |
SimpleTaglet.EXCLUDED)).getName(), temp); |
|
646 |
customTags.put((temp = new SimpleTaglet("factory", message.getText("doclet.Factory"), |
|
647 |
SimpleTaglet.METHOD)).getName(), temp); |
|
648 |
customTags.put((temp = new SeeTaglet()).getName(), temp); |
|
649 |
//Standard inline tags |
|
650 |
customTags.put((temp = new DocRootTaglet()).getName(), temp); |
|
651 |
customTags.put((temp = new InheritDocTaglet()).getName(), temp); |
|
652 |
customTags.put((temp = new ValueTaglet()).getName(), temp); |
|
653 |
customTags.put((temp = new LegacyTaglet(new LiteralTaglet())).getName(), |
|
654 |
temp); |
|
655 |
customTags.put((temp = new LegacyTaglet(new CodeTaglet())).getName(), |
|
656 |
temp); |
|
657 |
||
658 |
//Keep track of the names of standard tags for error |
|
659 |
//checking purposes. |
|
660 |
standardTags.add("param"); |
|
661 |
standardTags.add("return"); |
|
662 |
standardTags.add("throws"); |
|
663 |
standardTags.add("exception"); |
|
664 |
standardTags.add("since"); |
|
665 |
standardTags.add("version"); |
|
666 |
standardTags.add("author"); |
|
667 |
standardTags.add("see"); |
|
668 |
standardTags.add("deprecated"); |
|
669 |
standardTags.add("link"); |
|
670 |
standardTags.add("linkplain"); |
|
671 |
standardTags.add("inheritDoc"); |
|
672 |
standardTags.add("docRoot"); |
|
673 |
standardTags.add("value"); |
|
674 |
standardTags.add("serial"); |
|
675 |
standardTags.add("serialData"); |
|
676 |
standardTags.add("serialField"); |
|
677 |
standardTags.add("Text"); |
|
678 |
standardTags.add("literal"); |
|
679 |
standardTags.add("code"); |
|
680 |
} |
|
681 |
||
682 |
/** |
|
683 |
* Initialize lowercase version of standard Javadoc tags. |
|
684 |
*/ |
|
685 |
private void initStandardTagsLowercase() { |
|
1789
7ac8c0815000
6765045: Remove rawtypes warnings from langtools
mcimadamore
parents:
1264
diff
changeset
|
686 |
Iterator<String> it = standardTags.iterator(); |
10 | 687 |
while (it.hasNext()) { |
1789
7ac8c0815000
6765045: Remove rawtypes warnings from langtools
mcimadamore
parents:
1264
diff
changeset
|
688 |
standardTagsLowercase.add(it.next().toLowerCase()); |
10 | 689 |
} |
690 |
} |
|
691 |
||
692 |
public boolean isKnownCustomTag(String tagName) { |
|
693 |
return customTags.containsKey(tagName); |
|
694 |
} |
|
695 |
||
696 |
/** |
|
697 |
* Print a list of {@link Taglet}s that might conflict with |
|
698 |
* standard tags in the future and a list of standard tags |
|
699 |
* that have been overriden. |
|
700 |
*/ |
|
701 |
public void printReport() { |
|
702 |
printReportHelper("doclet.Notice_taglet_conflict_warn", potentiallyConflictingTags); |
|
703 |
printReportHelper("doclet.Notice_taglet_overriden", overridenStandardTags); |
|
704 |
printReportHelper("doclet.Notice_taglet_unseen", unseenCustomTags); |
|
705 |
} |
|
706 |
||
868 | 707 |
private void printReportHelper(String noticeKey, Set<String> names) { |
10 | 708 |
if (names.size() > 0) { |
868 | 709 |
String[] namesArray = names.toArray(new String[] {}); |
10 | 710 |
String result = " "; |
711 |
for (int i = 0; i < namesArray.length; i++) { |
|
712 |
result += "@" + namesArray[i]; |
|
713 |
if (i + 1 < namesArray.length) { |
|
714 |
result += ", "; |
|
715 |
} |
|
716 |
} |
|
717 |
message.notice(noticeKey, result); |
|
718 |
} |
|
719 |
} |
|
720 |
||
721 |
/** |
|
722 |
* Given the name of a tag, return the corresponding taglet. |
|
723 |
* Return null if the tag is unknown. |
|
724 |
* |
|
725 |
* @param name the name of the taglet to retrieve. |
|
726 |
* @return return the corresponding taglet. Return null if the tag is |
|
727 |
* unknown. |
|
728 |
*/ |
|
729 |
public Taglet getTaglet(String name) { |
|
730 |
if (name.indexOf("@") == 0) { |
|
868 | 731 |
return customTags.get(name.substring(1)); |
10 | 732 |
} else { |
868 | 733 |
return customTags.get(name); |
10 | 734 |
} |
735 |
||
736 |
} |
|
737 |
} |