Taglets used by doclets.
- *
- * This is NOT part of any supported API.
- * If you write code that depends on this, you do so at your own risk.
- * This code and its internal interfaces are subject to change or
- * deletion without notice.
- *
- * @author Jamie Ho
- * @since 1.4
- */
-
-public class TagletManager {
-
- /**
- * The default separator for the simple tag option.
- */
- public static final char SIMPLE_TAGLET_OPT_SEPARATOR = ':';
-
- /**
- * The alternate separator for simple tag options. Use this
- * when you want the default separator to be in the name of the
- * custom tag.
- */
- public static final String ALT_SIMPLE_TAGLET_OPT_SEPARATOR = "-";
-
- /**
- * The map of custom tags.
- */
- private LinkedHashMap This is NOT part of any supported API.
+ * If you write code that depends on this, you do so at your own risk.
+ * This code and its internal interfaces are subject to change or
+ * deletion without notice.
+ *
+ * @author Jamie Ho
+ * @since 1.4
+ */
+
+public class TagletManager {
+
+ /**
+ * The default separator for the simple tag option.
+ */
+ public static final char SIMPLE_TAGLET_OPT_SEPARATOR = ':';
+
+ /**
+ * The alternate separator for simple tag options. Use this
+ * when you want the default separator to be in the name of the
+ * custom tag.
+ */
+ public static final String ALT_SIMPLE_TAGLET_OPT_SEPARATOR = "-";
+
+ /**
+ * The map of custom tags.
+ */
+ private final LinkedHashMapTagletManager.
- * @param nosince true if we do not want to use @since tags.
- * @param showversion true if we want to use @version tags.
- * @param showauthor true if we want to use @author tags.
- * @param message the message retriever to print warnings.
- */
- public TagletManager(boolean nosince, boolean showversion,
- boolean showauthor, boolean javafx,
- MessageRetriever message) {
- overridenStandardTags = new HashSet<>();
- potentiallyConflictingTags = new HashSet<>();
- standardTags = new HashSet<>();
- standardTagsLowercase = new HashSet<>();
- unseenCustomTags = new HashSet<>();
- customTags = new LinkedHashMap<>();
- this.nosince = nosince;
- this.showversion = showversion;
- this.showauthor = showauthor;
- this.javafx = javafx;
- this.message = message;
- initStandardTaglets();
- initStandardTagsLowercase();
- }
-
- /**
- * Add a new CustomTag. This is used to add a Taglet from within
- * a Doclet. No message is printed to indicate that the Taglet is properly
- * registered because these Taglets are typically added for every execution of the
- * Doclet. We don't want to see this type of error message every time.
- * @param customTag the new CustomTag to add.
- */
- public void addCustomTag(Taglet customTag) {
- if (customTag != null) {
- String name = customTag.getName();
- if (customTags.containsKey(name)) {
- customTags.remove(name);
- }
- customTags.put(name, customTag);
- checkTagName(name);
- }
- }
-
- public SetTaglet. Print a message to indicate whether or not
- * the Taglet was registered properly.
- * @param classname the name of the class representing the custom tag.
- * @param tagletPath the path to the class representing the custom tag.
- */
- public void addCustomTag(String classname, JavaFileManager fileManager, String tagletPath) {
- try {
- Class customTagClass = null;
- // construct class loader
- String cpString = null; // make sure env.class.path defaults to dot
-
- ClassLoader tagClassLoader;
- if (fileManager != null && fileManager.hasLocation(DocumentationTool.Location.TAGLET_PATH)) {
- tagClassLoader = fileManager.getClassLoader(DocumentationTool.Location.TAGLET_PATH);
- } else {
- // do prepends to get correct ordering
- cpString = appendPath(System.getProperty("env.class.path"), cpString);
- cpString = appendPath(System.getProperty("java.class.path"), cpString);
- cpString = appendPath(tagletPath, cpString);
- tagClassLoader = new URLClassLoader(pathToURLs(cpString));
- }
-
- customTagClass = tagClassLoader.loadClass(classname);
- Method meth = customTagClass.getMethod("register",
- Map.class);
- Object[] list = customTags.values().toArray();
- Taglet lastTag = (list != null && list.length > 0)
- ? (Taglet) list[list.length-1] : null;
- meth.invoke(null, customTags);
- list = customTags.values().toArray();
- Object newLastTag = (list != null&& list.length > 0)
- ? list[list.length-1] : null;
- if (lastTag != newLastTag) {
- //New taglets must always be added to the end of the LinkedHashMap.
- //If the current and previous last taglet are not equal, that
- //means a new Taglet has been added.
- message.notice("doclet.Notice_taglet_registered", classname);
- if (newLastTag != null) {
- checkTaglet(newLastTag);
- }
- }
- } catch (Exception exc) {
- message.error("doclet.Error_taglet_not_registered", exc.getClass().getName(), classname);
- }
-
- }
-
- private String appendPath(String path1, String path2) {
- if (path1 == null || path1.length() == 0) {
- return path2 == null ? "." : path2;
- } else if (path2 == null || path2.length() == 0) {
- return path1;
- } else {
- return path1 + File.pathSeparator + path2;
- }
- }
-
- /**
- * Utility method for converting a search path string to an array
- * of directory and JAR file URLs.
- *
- * @param path the search path string
- * @return the resulting array of directory and JAR file URLs
- */
- private URL[] pathToURLs(String path) {
- SetSimpleTaglet. If this tag already exists
- * and the header passed as an argument is null, move tag to the back of the
- * list. If this tag already exists and the header passed as an argument is
- * not null, overwrite previous tag with new one. Otherwise, add new
- * SimpleTaglet to list.
- * @param tagName the name of this tag
- * @param header the header to output.
- * @param locations the possible locations that this tag
- * can appear in.
- */
- public void addNewSimpleCustomTag(String tagName, String header, String locations) {
- if (tagName == null || locations == null) {
- return;
- }
- Taglet tag = customTags.get(tagName);
- locations = StringUtils.toLowerCase(locations);
- if (tag == null || header != null) {
- customTags.remove(tagName);
- customTags.put(tagName, new SimpleTaglet(tagName, header, locations));
- if (locations != null && locations.indexOf('x') == -1) {
- checkTagName(tagName);
- }
- } else {
- //Move to back
- customTags.remove(tagName);
- customTags.put(tagName, tag);
- }
- }
-
- /**
- * Given a tag name, add it to the set of tags it belongs to.
- */
- private void checkTagName(String name) {
- if (standardTags.contains(name)) {
- overridenStandardTags.add(name);
- } else {
- if (name.indexOf('.') == -1) {
- potentiallyConflictingTags.add(name);
- }
- unseenCustomTags.add(name);
- }
- }
-
- /**
- * Check the taglet to see if it is a legacy taglet. Also
- * check its name for errors.
- */
- private void checkTaglet(Object taglet) {
- if (taglet instanceof Taglet) {
- checkTagName(((Taglet) taglet).getName());
- } else if (taglet instanceof com.sun.tools.doclets.Taglet) {
- com.sun.tools.doclets.Taglet legacyTaglet = (com.sun.tools.doclets.Taglet) taglet;
- customTags.remove(legacyTaglet.getName());
- customTags.put(legacyTaglet.getName(), new LegacyTaglet(legacyTaglet));
- checkTagName(legacyTaglet.getName());
- } else {
- throw new IllegalArgumentException("Given object is not a taglet.");
- }
- }
-
- /**
- * Given a name of a seen custom tag, remove it from the set of unseen
- * custom tags.
- * @param name the name of the seen custom tag.
- */
- public void seenCustomTag(String name) {
- unseenCustomTags.remove(name);
- }
-
- /**
- * Given an array of Tags, check for spelling mistakes.
- * @param doc the Doc object that holds the tags.
- * @param tags the list of Tags to check.
- * @param areInlineTags true if the array of tags are inline and false otherwise.
- */
- public void checkTags(Doc doc, Tag[] tags, boolean areInlineTags) {
- if (tags == null) {
- return;
- }
- Taglet taglet;
- for (Tag tag : tags) {
- String name = tag.name();
- if (name.length() > 0 && name.charAt(0) == '@') {
- name = name.substring(1, name.length());
- }
- if (! (standardTags.contains(name) || customTags.containsKey(name))) {
- if (standardTagsLowercase.contains(StringUtils.toLowerCase(name))) {
- message.warning(tag.position(), "doclet.UnknownTagLowercase", tag.name());
- continue;
- } else {
- message.warning(tag.position(), "doclet.UnknownTag", tag.name());
- continue;
- }
- }
- //Check if this tag is being used in the wrong location.
- if ((taglet = customTags.get(name)) != null) {
- if (areInlineTags && ! taglet.isInlineTag()) {
- printTagMisuseWarn(taglet, tag, "inline");
- }
- if ((doc instanceof RootDoc) && ! taglet.inOverview()) {
- printTagMisuseWarn(taglet, tag, "overview");
- } else if ((doc instanceof PackageDoc) && ! taglet.inPackage()) {
- printTagMisuseWarn(taglet, tag, "package");
- } else if ((doc instanceof ClassDoc) && ! taglet.inType()) {
- printTagMisuseWarn(taglet, tag, "class");
- } else if ((doc instanceof ConstructorDoc) && ! taglet.inConstructor()) {
- printTagMisuseWarn(taglet, tag, "constructor");
- } else if ((doc instanceof FieldDoc) && ! taglet.inField()) {
- printTagMisuseWarn(taglet, tag, "field");
- } else if ((doc instanceof MethodDoc) && ! taglet.inMethod()) {
- printTagMisuseWarn(taglet, tag, "method");
- }
- }
- }
- }
-
- /**
- * Given the taglet, the tag and the type of documentation that the tag
- * was found in, print a tag misuse warning.
- * @param taglet the taglet representing the misused tag.
- * @param tag the misused tag.
- * @param holderType the type of documentation that the misused tag was found in.
- */
- private void printTagMisuseWarn(Taglet taglet, Tag tag, String holderType) {
- SetTaglets that can
- * appear in packages.
- * @return the array of Taglets that can
- * appear in packages.
- */
- public Taglet[] getPackageCustomTaglets() {
- if (packageTags == null) {
- initCustomTagletArrays();
- }
- return packageTags;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in classes or interfaces.
- * @return the array of Taglets that can
- * appear in classes or interfaces.
- */
- public Taglet[] getTypeCustomTaglets() {
- if (typeTags == null) {
- initCustomTagletArrays();
- }
- return typeTags;
- }
-
- /**
- * Return the array of inline Taglets that can
- * appear in comments.
- * @return the array of Taglets that can
- * appear in comments.
- */
- public Taglet[] getInlineCustomTaglets() {
- if (inlineTags == null) {
- initCustomTagletArrays();
- }
- return inlineTags;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in fields.
- * @return the array of Taglets that can
- * appear in field.
- */
- public Taglet[] getFieldCustomTaglets() {
- if (fieldTags == null) {
- initCustomTagletArrays();
- }
- return fieldTags;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in the serialized form.
- * @return the array of Taglets that can
- * appear in the serialized form.
- */
- public Taglet[] getSerializedFormTaglets() {
- if (serializedFormTags == null) {
- initCustomTagletArrays();
- }
- return serializedFormTags;
- }
-
- /**
- * @return the array of Taglets that can
- * appear in the given Doc.
- */
- public Taglet[] getCustomTaglets(Doc doc) {
- if (doc instanceof ConstructorDoc) {
- return getConstructorCustomTaglets();
- } else if (doc instanceof MethodDoc) {
- return getMethodCustomTaglets();
- } else if (doc instanceof FieldDoc) {
- return getFieldCustomTaglets();
- } else if (doc instanceof ClassDoc) {
- return getTypeCustomTaglets();
- } else if (doc instanceof PackageDoc) {
- return getPackageCustomTaglets();
- } else if (doc instanceof RootDoc) {
- return getOverviewCustomTaglets();
- }
- return null;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in constructors.
- * @return the array of Taglets that can
- * appear in constructors.
- */
- public Taglet[] getConstructorCustomTaglets() {
- if (constructorTags == null) {
- initCustomTagletArrays();
- }
- return constructorTags;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in methods.
- * @return the array of Taglets that can
- * appear in methods.
- */
- public Taglet[] getMethodCustomTaglets() {
- if (methodTags == null) {
- initCustomTagletArrays();
- }
- return methodTags;
- }
-
- /**
- * Return the array of Taglets that can
- * appear in an overview.
- * @return the array of Taglets that can
- * appear in overview.
- */
- public Taglet[] getOverviewCustomTaglets() {
- if (overviewTags == null) {
- initCustomTagletArrays();
- }
- return overviewTags;
- }
-
- /**
- * Initialize the custom tag arrays.
- */
- private void initCustomTagletArrays() {
- IteratorTaglets used by doclets.
+ *
+ * TagletManager.
+ * @param nosince true if we do not want to use @since tags.
+ * @param showversion true if we want to use @version tags.
+ * @param showauthor true if we want to use @author tags.
+ * @param javafx indicates whether javafx is active.
+ * @param message the message retriever to print warnings.
+ */
+ public TagletManager(boolean nosince, boolean showversion,
+ boolean showauthor, boolean javafx,
+ MessageRetriever message) {
+ overridenStandardTags = new HashSet<>();
+ potentiallyConflictingTags = new HashSet<>();
+ standardTags = new HashSet<>();
+ standardTagsLowercase = new HashSet<>();
+ unseenCustomTags = new HashSet<>();
+ customTags = new LinkedHashMap<>();
+ this.nosince = nosince;
+ this.showversion = showversion;
+ this.showauthor = showauthor;
+ this.javafx = javafx;
+ this.message = message;
+ initStandardTaglets();
+ initStandardTagsLowercase();
+ }
+
+ /**
+ * Add a new CustomTag. This is used to add a Taglet from within
+ * a Doclet. No message is printed to indicate that the Taglet is properly
+ * registered because these Taglets are typically added for every execution of the
+ * Doclet. We don't want to see this type of error message every time.
+ * @param customTag the new CustomTag to add.
+ */
+ public void addCustomTag(Taglet customTag) {
+ if (customTag != null) {
+ String name = customTag.getName();
+ if (customTags.containsKey(name)) {
+ customTags.remove(name);
+ }
+ customTags.put(name, customTag);
+ checkTagName(name);
+ }
+ }
+
+ public SetTaglet. Print a message to indicate whether or not
+ * the Taglet was registered properly.
+ * @param classname the name of the class representing the custom tag.
+ * @param fileManager the filemanager to load classes and resources.
+ * @param tagletPath the path to the class representing the custom tag.
+ */
+ public void addCustomTag(String classname, JavaFileManager fileManager, String tagletPath) {
+ try {
+ ClassLoader tagClassLoader;
+ if (!fileManager.hasLocation(TAGLET_PATH)) {
+ ListSimpleTaglet. If this tag already exists
+ * and the header passed as an argument is null, move tag to the back of the
+ * list. If this tag already exists and the header passed as an argument is
+ * not null, overwrite previous tag with new one. Otherwise, add new
+ * SimpleTaglet to list.
+ * @param tagName the name of this tag
+ * @param header the header to output.
+ * @param locations the possible locations that this tag
+ * can appear in.
+ */
+ public void addNewSimpleCustomTag(String tagName, String header, String locations) {
+ if (tagName == null || locations == null) {
+ return;
+ }
+ Taglet tag = customTags.get(tagName);
+ locations = Utils.toLowerCase(locations);
+ if (tag == null || header != null) {
+ customTags.remove(tagName);
+ customTags.put(tagName, new SimpleTaglet(tagName, header, locations));
+ if (locations != null && locations.indexOf('x') == -1) {
+ checkTagName(tagName);
+ }
+ } else {
+ //Move to back
+ customTags.remove(tagName);
+ customTags.put(tagName, tag);
+ }
+ }
+
+ /**
+ * Given a tag name, add it to the set of tags it belongs to.
+ */
+ private void checkTagName(String name) {
+ if (standardTags.contains(name)) {
+ overridenStandardTags.add(name);
+ } else {
+ if (name.indexOf('.') == -1) {
+ potentiallyConflictingTags.add(name);
+ }
+ unseenCustomTags.add(name);
+ }
+ }
+
+ /**
+ * Check the taglet to see if it is a legacy taglet. Also
+ * check its name for errors.
+ */
+ private void checkTaglet(Object taglet) {
+ if (taglet instanceof Taglet) {
+ checkTagName(((Taglet) taglet).getName());
+ } else if (taglet instanceof jdk.javadoc.doclet.taglet.Taglet) {
+ jdk.javadoc.doclet.taglet.Taglet legacyTaglet = (jdk.javadoc.doclet.taglet.Taglet) taglet;
+ customTags.remove(legacyTaglet.getName());
+ customTags.put(legacyTaglet.getName(), new UserTaglet(legacyTaglet));
+ checkTagName(legacyTaglet.getName());
+ } else {
+ throw new IllegalArgumentException("Given object is not a taglet.");
+ }
+ }
+
+ /**
+ * Given a name of a seen custom tag, remove it from the set of unseen
+ * custom tags.
+ * @param name the name of the seen custom tag.
+ */
+ public void seenCustomTag(String name) {
+ unseenCustomTags.remove(name);
+ }
+
+ /**
+ * Given an array of Tags, check for spelling mistakes.
+ * @param utils the utility class to use
+ * @param element the tags holder
+ * @param trees the trees containing the comments
+ * @param areInlineTags true if the array of tags are inline and false otherwise.
+ */
+ public void checkTags(final Utils utils, Element element,
+ Iterable trees, boolean areInlineTags) {
+ if (trees == null) {
+ return;
+ }
+ CommentHelper ch = utils.getCommentHelper(element);
+ for (DocTree tag : trees) {
+ String name = tag.getKind().tagName;
+ if (name == null) {
+ continue;
+ }
+ if (name.length() > 0 && name.charAt(0) == '@') {
+ name = name.substring(1, name.length());
+ }
+ if (! (standardTags.contains(name) || customTags.containsKey(name))) {
+ if (standardTagsLowercase.contains(Utils.toLowerCase(name))) {
+ message.warning(ch.getDocTreePath(tag), "doclet.UnknownTagLowercase", ch.getTagName(tag));
+ continue;
+ } else {
+ message.warning(ch.getDocTreePath(tag), "doclet.UnknownTag", ch.getTagName(tag));
+ continue;
+ }
+ }
+ final Taglet taglet = customTags.get(name);
+ // Check and verify tag usage
+ if (taglet != null) {
+ if (areInlineTags && !taglet.isInlineTag()) {
+ printTagMisuseWarn(ch, taglet, tag, "inline");
+ }
+ // nothing more to do
+ if (element == null) {
+ return;
+ }
+ new SimpleElementVisitor9Taglets that can
+ * appear in packages.
+ * @return the array of Taglets that can
+ * appear in packages.
+ */
+ public ListTaglets that can
+ * appear in classes or interfaces.
+ * @return the array of Taglets that can
+ * appear in classes or interfaces.
+ */
+ public ListTaglets that can
+ * appear in comments.
+ * @return the array of Taglets that can
+ * appear in comments.
+ */
+ public ListTaglets that can
+ * appear in fields.
+ * @return the array of Taglets that can
+ * appear in field.
+ */
+ public ListTaglets that can
+ * appear in the serialized form.
+ * @return the array of Taglets that can
+ * appear in the serialized form.
+ */
+ public ListTaglets that can
+ * appear in the given element.
+ */
+ public ListTaglets that can
+ * appear in constructors.
+ * @return the array of Taglets that can
+ * appear in constructors.
+ */
+ public ListTaglets that can
+ * appear in methods.
+ * @return the array of Taglets that can
+ * appear in methods.
+ */
+ public ListTaglets that can
+ * appear in an overview.
+ * @return the array of Taglets that can
+ * appear in overview.
+ */
+ public List