From 7e633707847e7861e247ed97bf8b3d5382ac2adc Mon Sep 17 00:00:00 2001 From: Mihai Nita Date: Mon, 24 Mar 2025 16:31:48 -0700 Subject: [PATCH] ICU-23040 Doclet migration: rename variables that don't match the type --- .../com/ibm/icu/dev/tool/docs/CheckTags.java | 206 +++++++++--------- .../ibm/icu/dev/tool/docs/GatherAPIData.java | 149 +++++++------ .../ibm/icu/dev/tool/docs/JavadocHelper.java | 131 +++++------ 3 files changed, 242 insertions(+), 244 deletions(-) diff --git a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckTags.java b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckTags.java index a1fed3ecb9c..f7c61b00b3c 100644 --- a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckTags.java +++ b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckTags.java @@ -57,11 +57,10 @@ import jdk.javadoc.doclet.Reporter; public class CheckTags implements Doclet { private DocTrees docTrees; private Elements elements; - - boolean log; - boolean brief; - boolean isShort; - DocStack stack = new DocStack(); + private boolean log; + private boolean brief; + private boolean isShort; + private DocStack stack = new DocStack(); class DocNode { private String header; @@ -119,7 +118,7 @@ public class CheckTags implements Doclet { // propagate to parent if (index > 0) { - stack[index-1].errorCount += ec; + stack[index - 1].errorCount += ec; } } if (index == 0) { @@ -232,7 +231,7 @@ public class CheckTags implements Doclet { List allClasses = environment.getIncludedElements().stream() .filter(e-> e.getKind().isClass()) .collect(Collectors.toList()); - doDocs(allClasses, "Package", true); + doElements(allClasses, "Package", true); return true; } @@ -277,34 +276,34 @@ public class CheckTags implements Doclet { tagErr("", element, tag); } - void doDocs(Collection elements, String header, boolean reportError) { + void doElements(Collection elements, String header, boolean reportError) { if (elements != null && !elements.isEmpty()) { stack.push(header, reportError); for (Element element : elements) { - doDoc(element); + doElement(element); } stack.pop(); } } - void doDoc(Element doc) { - if (doc != null && (JavadocHelper.isPublic(doc) || JavadocHelper.isProtected(doc)) - && !(JavadocHelper.isKindConstructor(doc) && JavadocHelper.isSynthetic(elements, doc))) { + void doElement(Element element) { + if (element != null && (JavadocHelper.isPublic(element) || JavadocHelper.isProtected(element)) + && !(JavadocHelper.isKindConstructor(element) && JavadocHelper.isSynthetic(elements, element))) { // unfortunately, in JDK 1.4.1 MemberDoc.isSynthetic is not properly implemented for // synthetic constructors. So you'll have to live with spurious errors or 'implement' // the synthetic constructors... - boolean isClass = JavadocHelper.isKindClassOrInterface(doc); + boolean isClass = JavadocHelper.isKindClassOrInterface(element); String header; if (!isShort || isClass) { header = "--- "; } else { header = ""; } - if (doc instanceof ExecutableElement) { - header += JavadocHelper.flatSignature(doc); + if (element instanceof ExecutableElement) { + header += JavadocHelper.flatSignature(element); } else { - header += (isClass ? ((QualifiedNameable) doc).getQualifiedName() : doc.getSimpleName()); + header += (isClass ? ((QualifiedNameable) element).getQualifiedName() : element.getSimpleName()); } if (!isShort || isClass) { header += " ---"; @@ -313,25 +312,25 @@ public class CheckTags implements Doclet { if (log) { logln(); } - boolean recurse = doTags(doc); + boolean recurse = doTags(element); if (recurse && isClass) { - TypeElement cdoc = (TypeElement)doc; - List fields = cdoc.getEnclosedElements().stream() + TypeElement typeElement = (TypeElement)element; + List fields = typeElement.getEnclosedElements().stream() .filter(JavadocHelper::isKindField).collect(Collectors.toList()); - doDocs(fields, "Fields", !brief); - List constructors = cdoc.getEnclosedElements().stream() + doElements(fields, "Fields", !brief); + List constructors = typeElement.getEnclosedElements().stream() .filter(JavadocHelper::isKindConstructor).collect(Collectors.toList()); - doDocs(constructors, "Constructors", !brief); - List methods = cdoc.getEnclosedElements().stream() + doElements(constructors, "Constructors", !brief); + List methods = typeElement.getEnclosedElements().stream() .filter(JavadocHelper::isKindMethod).collect(Collectors.toList()); - doDocs(methods, "Methods", !brief); + doElements(methods, "Methods", !brief); } stack.pop(); } } - /** Return true if subelements of this doc should be checked */ - boolean doTags(Element doc) { + /** Return true if sub-elements of this element should be checked */ + boolean doTags(Element element) { boolean foundRequiredTag = false; boolean foundDraftTag = false; boolean foundProvisionalTag = false; @@ -341,132 +340,129 @@ public class CheckTags implements Doclet { boolean foundStableTag = false; boolean retainAll = false; - if (JavadocHelper.isIgnoredEnumMethod(doc)) { + if (JavadocHelper.isIgnoredEnumMethod(element)) { return false; } // first check inline tags - for (InlineTagTree tag : JavadocHelper.getInnerTags(docTrees, doc)) { - JavadocHelper.IcuTagKind index = JavadocHelper.IcuTagKind.ofTag(tag); + for (InlineTagTree tag : JavadocHelper.getInnerTags(docTrees, element)) { + JavadocHelper.IcuTagKind tagKind = JavadocHelper.IcuTagKind.ofTag(tag); String text = JavadocHelper.toText(tag).trim(); - // System.out.println("SPY ==== " + tag + " === " + index + " == '" + text + "'"); - switch (index) { + switch (tagKind) { case ICU: { - if (JavadocHelper.isKindClassOrInterface(doc)) { - tagErr("tag should appear only in member docs", doc, tag); + if (JavadocHelper.isKindClassOrInterface(element)) { + tagErr("tag should appear only in member elements", element, tag); } } break; case ICUNOTE: { if (!text.isEmpty()) { - tagErr("tag should not contain text", doc, tag); + tagErr("tag should not contain text", element, tag); } } break; case ICUENHANCED: { if (text.isEmpty()) { - tagErr("text should name related jdk class", doc, tag); + tagErr("text should name related jdk class", element, tag); } - if (!(JavadocHelper.isKindClassOrInterface(doc))) { - tagErr("tag should appear only in class/interface docs", doc, tag); + if (!(JavadocHelper.isKindClassOrInterface(element))) { + tagErr("tag should appear only in class/interface elements", element, tag); } } break; case UNKNOWN: // It might be a standard tag, so we don't complain about this break; default: - tagErr("unrecognized tag index for tag", doc, tag); + tagErr("unrecognized tagKind for tag", element, tag); break; } } - // System.out.println("SPY====== " + doc); // next check regular tags - for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, doc)) { - JavadocHelper.TagKind ix = JavadocHelper.TagKind.ofTag(tag); + for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, element)) { + JavadocHelper.TagKind tagKind = JavadocHelper.TagKind.ofTag(tag); String tagText = JavadocHelper.toText(tag); - // System.out.println("SPY ==== " + tag + " === " + ix + " == '" + tagText + "'"); - switch (ix) { - case UNKNOWN: - errln("unknown kind: " + tag.getTagName()); - break; - - case INTERNAL: - foundRequiredTag = true; - foundInternalTag = true; - break; - - case DRAFT: - foundRequiredTag = true; - foundDraftTag = true; - if (tagText.indexOf("ICU 2.8") != -1 && - tagText.indexOf("(retain") == -1) { // catch both retain and retainAll - tagErr(doc, tag); + switch (tagKind) { + case UNKNOWN: + errln("unknown kind: " + tag.getTagName()); break; - } - if (tagText.indexOf("ICU") != 0) { - tagErr(doc, tag); - break; - } - retainAll |= (tagText.indexOf("(retainAll)") != -1); - break; - case PROVISIONAL: - foundProvisionalTag = true; - break; - - case DEPRECATED: - foundDeprecatedTag = true; - if (tagText.indexOf("ICU") == 0) { + case INTERNAL: foundRequiredTag = true; - } - break; + foundInternalTag = true; + break; - case OBSOLETE: - if (tagText.indexOf("ICU") != 0) { - tagErr(doc, tag); - } - foundObsoleteTag = true; - foundRequiredTag = true; - break; + case DRAFT: + foundRequiredTag = true; + foundDraftTag = true; + if (tagText.indexOf("ICU 2.8") != -1 && + tagText.indexOf("(retain") == -1) { // catch both retain and retainAll + tagErr(element, tag); + break; + } + if (tagText.indexOf("ICU") != 0) { + tagErr(element, tag); + break; + } + retainAll |= (tagText.indexOf("(retainAll)") != -1); + break; - case STABLE: + case PROVISIONAL: + foundProvisionalTag = true; + break; + + case DEPRECATED: + foundDeprecatedTag = true; + if (tagText.indexOf("ICU") == 0) { + foundRequiredTag = true; + } + break; + + case OBSOLETE: + if (tagText.indexOf("ICU") != 0) { + tagErr(element, tag); + } + foundObsoleteTag = true; + foundRequiredTag = true; + break; + + case STABLE: { if (tagText.length() != 0 && tagText.indexOf("ICU") != 0) { - tagErr(tagText, doc, tag); + tagErr(tagText, element, tag); } foundRequiredTag = true; foundStableTag = true; } break; - case SINCE: - tagErr(doc, tag); - break; + case SINCE: + tagErr(element, tag); + break; - case EXCEPTION: - //TODO: Why would we report this? - // logln("You really ought to use @throws, you know... :-)"); - break; + case EXCEPTION: + //TODO: Why would we report this? + // logln("You really ought to use @throws, you know... :-)"); + break; - case AUTHOR: - case SEE: - case PARAM: - case RETURN: - case THROWS: - case SERIAL: - case DISCOURAGED: - case CATEGORY: - break; + case AUTHOR: + case SEE: + case PARAM: + case RETURN: + case THROWS: + case SERIAL: + case DISCOURAGED: + case CATEGORY: + break; - case VERSION: - tagErr(doc, tag); - break; + case VERSION: + tagErr(element, tag); + break; - default: - errln("unknown index: " + ix); + default: + errln("unknown tagKind: " + tagKind); } // end if switch } // end of iteration on tags if (!foundRequiredTag) { - errln("missing required tag [" + JavadocHelper.position(elements, docTrees, doc) + "]"); + errln("missing required tag [" + JavadocHelper.position(elements, docTrees, element) + "]"); } if (foundInternalTag && !foundDeprecatedTag) { errln("internal tag missing deprecated"); diff --git a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIData.java b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIData.java index afb8d911d5b..51a84d8ae44 100644 --- a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIData.java +++ b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIData.java @@ -135,7 +135,7 @@ public class GatherAPIData implements Doclet { docTrees = environment.getDocTrees(); initFromOptions(); - doDocs(environment.getIncludedElements()); + doElements(environment.getIncludedElements()); try (OutputStream os = getOutputFileAsStream(output); OutputStreamWriter osw = new OutputStreamWriter(os, StandardCharsets.UTF_8)) { @@ -171,24 +171,24 @@ public class GatherAPIData implements Doclet { return new FileOutputStream(output); } - private void doDocs(Collection docs) { - if (docs != null) { - for (Element doc : docs) { - doDoc(doc); + private void doElements(Collection elements) { + if (elements != null) { + for (Element element : elements) { + doElement(element); } } } - private void doDoc(Element doc) { - if (ignore(doc)) return; + private void doElement(Element element) { + if (ignore(element)) return; // isClass() ==> CLASS || ENUM; // isInterface() ==> INTERFACE || ANNOTATION_TYPE - if (JavadocHelper.isKindClassOrInterface(doc)) { - doDocs(doc.getEnclosedElements()); + if (JavadocHelper.isKindClassOrInterface(element)) { + doElements(element.getEnclosedElements()); } - APIInfo info = createInfo(doc); + APIInfo info = createInfo(element); if (info != null) { results.add(info); } @@ -205,55 +205,55 @@ public class GatherAPIData implements Doclet { // javadoc comments by the policy. So, we no longer ignore abstract // class's no-arg constructor blindly. -Yoshito 2014-05-21 - private boolean isAbstractClassDefaultConstructor(Element doc) { - return JavadocHelper.isKindConstructor(doc) - && JavadocHelper.isAbstract(doc.getEnclosingElement()) - && ((ExecutableElement) doc).getParameters().isEmpty(); + private boolean isAbstractClassDefaultConstructor(Element element) { + return JavadocHelper.isKindConstructor(element) + && JavadocHelper.isAbstract(element.getEnclosingElement()) + && ((ExecutableElement) element).getParameters().isEmpty(); } private static final boolean IGNORE_NO_ARG_ABSTRACT_CTOR = false; - private boolean ignore(Element doc) { - if (doc == null) { + private boolean ignore(Element element) { + if (element == null) { return true; } - if (JavadocHelper.isPrivate(doc) || JavadocHelper.isDefault(doc)) { + if (JavadocHelper.isPrivate(element) || JavadocHelper.isDefault(element)) { return true; } - if (JavadocHelper.isVisibilityPackage(doc)) { + if (JavadocHelper.isVisibilityPackage(element)) { return true; } - if (JavadocHelper.isKindPackage(doc)) { + if (JavadocHelper.isKindPackage(element)) { return true; } - if (doc.toString().contains(".misc")) { - System.out.println("misc: " + doc.toString()); { + if (element.toString().contains(".misc")) { + System.out.println("misc: " + element.toString()); { return true; } } - if (JavadocHelper.isIgnoredEnumMethod(doc)) { + if (JavadocHelper.isIgnoredEnumMethod(element)) { return true; } - if (IGNORE_NO_ARG_ABSTRACT_CTOR && isAbstractClassDefaultConstructor(doc)) { + if (IGNORE_NO_ARG_ABSTRACT_CTOR && isAbstractClassDefaultConstructor(element)) { return true; } if (!internal) { // debug - for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, doc)) { + for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, element)) { if (JavadocHelper.TagKind.ofTag(tag) == JavadocHelper.TagKind.INTERNAL) { return true; } } } - if (pat != null && JavadocHelper.isKindClassOrInterface(doc)) { - if (!pat.matcher(doc.getSimpleName().toString()).matches()) { + if (pat != null && JavadocHelper.isKindClassOrInterface(element)) { + if (!pat.matcher(element.getSimpleName().toString()).matches()) { return true; } } @@ -277,8 +277,8 @@ public class GatherAPIData implements Doclet { return arg; } - private APIInfo createInfo(Element doc) { - if (ignore(doc)) return null; + private APIInfo createInfo(Element element) { + if (ignore(element)) return null; APIInfo info = new APIInfo(); if (version) { @@ -287,86 +287,86 @@ public class GatherAPIData implements Doclet { // status String[] version = new String[1]; - info.setType(APIInfo.STA, tagStatus(doc, version)); + info.setType(APIInfo.STA, tagStatus(element, version)); info.setStatusVersion(version[0]); // visibility - if (JavadocHelper.isPublic(doc)) { + if (JavadocHelper.isPublic(element)) { info.setPublic(); - } else if (JavadocHelper.isProtected(doc)) { + } else if (JavadocHelper.isProtected(element)) { info.setProtected(); - } else if (JavadocHelper.isPrivate(doc)) { + } else if (JavadocHelper.isPrivate(element)) { info.setPrivate(); } else { // default is package } // static - if (JavadocHelper.isStatic(doc)) { + if (JavadocHelper.isStatic(element)) { info.setStatic(); } else { // default is non-static } // Final. Enums are final by default. - if (JavadocHelper.isFinal(doc) && !JavadocHelper.isKindEnum(doc)) { + if (JavadocHelper.isFinal(element) && !JavadocHelper.isKindEnum(element)) { info.setFinal(); } else { // default is non-final } // type - if (JavadocHelper.isKindFieldExact(doc)) { + if (JavadocHelper.isKindFieldExact(element)) { info.setField(); - } else if (JavadocHelper.isKindMethod(doc)) { + } else if (JavadocHelper.isKindMethod(element)) { info.setMethod(); - } else if (JavadocHelper.isKindConstructor(doc)) { + } else if (JavadocHelper.isKindConstructor(element)) { info.setConstructor(); - } else if (JavadocHelper.isKindClassOrInterface(doc)) { - if (JavadocHelper.isKindEnum(doc)) { + } else if (JavadocHelper.isKindClassOrInterface(element)) { + if (JavadocHelper.isKindEnum(element)) { info.setEnum(); } else { info.setClass(); } - } else if (JavadocHelper.isKindEnumConstant(doc)) { + } else if (JavadocHelper.isKindEnumConstant(element)) { info.setEnumConstant(); } - PackageElement packageElement = elementUtils.getPackageOf(doc); + PackageElement packageElement = elementUtils.getPackageOf(element); info.setPackage(trimBase(packageElement.getQualifiedName().toString())); - String className = (JavadocHelper.isKindClassOrInterface(doc) || doc.getEnclosingElement() == null) + String className = (JavadocHelper.isKindClassOrInterface(element) || element.getEnclosingElement() == null) ? "" - : withoutPackage(doc.getEnclosingElement()); + : withoutPackage(element.getEnclosingElement()); info.setClassName(className); - String name = doc.getSimpleName().toString(); - if (JavadocHelper.isKindConstructor(doc)) { + String name = element.getSimpleName().toString(); + if (JavadocHelper.isKindConstructor(element)) { // The constructor name is always `` with the javax.lang APIs. // For backward compatibility with older generated files we use the class name instead. name = className; - } else if (JavadocHelper.isKindClassOrInterface(doc)) { - name = withoutPackage(doc); + } else if (JavadocHelper.isKindClassOrInterface(element)) { + name = withoutPackage(element); } info.setName(name); - if (JavadocHelper.isKindField(doc)) { - VariableElement fdoc = (VariableElement) doc; - hackSetSignature(info, trimBase(fdoc.asType().toString())); - } else if (JavadocHelper.isKindClassOrInterface(doc)) { - TypeElement cdoc = (TypeElement) doc; + if (JavadocHelper.isKindField(element)) { + VariableElement varElement = (VariableElement) element; + hackSetSignature(info, trimBase(varElement.asType().toString())); + } else if (JavadocHelper.isKindClassOrInterface(element)) { + TypeElement typeElementc = (TypeElement) element; - if (!JavadocHelper.isKindInterface(doc) && JavadocHelper.isAbstract(cdoc)) { + if (!JavadocHelper.isKindInterface(element) && JavadocHelper.isAbstract(typeElementc)) { // interfaces are abstract by default, don't mark them as abstract info.setAbstract(); } StringBuffer buf = new StringBuffer(); - if (JavadocHelper.isKindClass(cdoc)) { + if (JavadocHelper.isKindClass(typeElementc)) { buf.append("extends "); - buf.append(cdoc.getSuperclass().toString()); + buf.append(typeElementc.getSuperclass().toString()); } - List imp = cdoc.getInterfaces(); + List imp = typeElementc.getInterfaces(); if (!imp.isEmpty()) { if (buf.length() > 0) { buf.append(" "); @@ -385,36 +385,36 @@ public class GatherAPIData implements Doclet { } } hackSetSignature(info, trimBase(buf.toString())); - } else if (JavadocHelper.isKindMethod(doc) || JavadocHelper.isKindConstructor(doc)) { - ExecutableElement emdoc = (ExecutableElement)doc; - if (JavadocHelper.isSynchronized(emdoc)) { + } else if (JavadocHelper.isKindMethod(element) || JavadocHelper.isKindConstructor(element)) { + ExecutableElement execElement = (ExecutableElement) element; + if (JavadocHelper.isSynchronized(execElement)) { info.setSynchronized(); } - if (JavadocHelper.isKindMethod(doc)) { - if (JavadocHelper.isAbstract(emdoc)) { + if (JavadocHelper.isKindMethod(element)) { + if (JavadocHelper.isAbstract(execElement)) { // Workaround for Javadoc incompatibility between 7 and 8. // isAbstract() returns false for a method in an interface // on Javadoc 7, while Javadoc 8 returns true. Because existing // API signature data files were generated before, we do not // set abstract if a method is in an interface. - if (!JavadocHelper.isKindInterface(emdoc.getEnclosingElement())) { + if (!JavadocHelper.isKindInterface(execElement.getEnclosingElement())) { info.setAbstract(); } } - String retSig = stringFromTypeMirror(emdoc.getReturnType()); + String retSig = stringFromTypeMirror(execElement.getReturnType()); // Signature, as returned by default, can be something like this: "booleancontainsAll(java.util.Iterator)" // The old API returned "boolean(java.util.Iterator)" // Consider using the signature "as is" (including the method name) - hackSetSignature(info, trimBase(retSig + toTheBracket(emdoc.toString()))); + hackSetSignature(info, trimBase(retSig + toTheBracket(execElement.toString()))); } else { // constructor - hackSetSignature(info, toTheBracket(emdoc.toString())); + hackSetSignature(info, toTheBracket(execElement.toString())); } } else { - throw new RuntimeException("Unknown element kind: " + doc.getKind()); + throw new RuntimeException("Unknown element kind: " + element.getKind()); } return info; @@ -456,7 +456,7 @@ public class GatherAPIData implements Doclet { return openBr > 1 ? str.substring(openBr) : str; } - private int tagStatus(final Element doc, String[] version) { + private int tagStatus(final Element element, String[] version) { class Result { boolean deprecatedFlag = false; int res = -1; @@ -492,7 +492,7 @@ public class GatherAPIData implements Doclet { isValid = false; } if (!isValid) { - System.err.println("bad doc: " + doc + " both: " + System.err.println("bad element: " + element + " both: " + APIInfo.getTypeValName(APIInfo.STA, res) + " and: " + APIInfo.getTypeValName(APIInfo.STA, val)); return; @@ -507,22 +507,21 @@ public class GatherAPIData implements Doclet { } int get() { if (res == -1) { - System.err.println("warning: no tag for " + doc); + System.err.println("warning: no tag for " + element); return 0; } else if (res == APIInfo.STA_INTERNAL && !deprecatedFlag) { - System.err.println("warning: no @deprecated tag for @internal API: " + doc); + System.err.println("warning: no @deprecated tag for @internal API: " + element); } return res; } } - List tags = JavadocHelper.getBlockTags(docTrees, doc); + List tags = JavadocHelper.getBlockTags(docTrees, element); Result result = new Result(); String statusVer = ""; for (BlockTagTree tag : tags) { - JavadocHelper.TagKind ix = JavadocHelper.TagKind.ofTag(tag); - - switch (ix) { + JavadocHelper.TagKind tagKind = JavadocHelper.TagKind.ofTag(tag); + switch (tagKind) { case INTERNAL: result.set(internal ? APIInfo.STA_INTERNAL : -2); // -2 for legacy compatibility statusVer = getStatusVersion(tag); @@ -563,7 +562,7 @@ public class GatherAPIData implements Doclet { break; default: - throw new RuntimeException("unknown index " + ix + " for tag: " + tag); + throw new RuntimeException("unknown tagKind " + tagKind + " for tag: " + tag); } } diff --git a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/JavadocHelper.java b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/JavadocHelper.java index a128ce6e521..6be44a8aef0 100644 --- a/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/JavadocHelper.java +++ b/icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/JavadocHelper.java @@ -23,8 +23,6 @@ * * flags names of classes and their members that have no tags or incorrect syntax. * - * Requires JDK 1.4 or later - * * Use build.xml 'checktags' ant target, or * run from directory containing CheckTags.class as follows: * javadoc -classpath ${JAVA_HOME}/lib/tools.jar -doclet CheckTags -sourcepath ${ICU4J_src} [packagenames] @@ -52,6 +50,7 @@ import com.sun.source.util.TreePath; import jdk.javadoc.doclet.Doclet; class JavadocHelper { + // ===== Kind ===== /** The standard {@code isClass()} test returns true for both {@code CLASS} @@ -115,7 +114,8 @@ class JavadocHelper { return kind.isClass() || kind.isInterface(); } - // Visibility + // ===== Visibility ===== + static boolean isPublic(Element element) { return element.getModifiers().contains(Modifier.PUBLIC); } @@ -187,6 +187,8 @@ class JavadocHelper { return position(el, docTrees, element); } + // ===== Accessing tags ===== + static List getBlockTags(DocTrees docTrees, Element element) { List result = new ArrayList<>(); DocCommentTree dct = docTrees.getDocCommentTree(element); @@ -247,7 +249,68 @@ class JavadocHelper { return false; } - // Doclet options + // Known taglets, standard or ICU extensions + static enum TagKind { + UNKNOWN(""), + INTERNAL("internal"), + DRAFT("draft"), + STABLE("stable"), + SINCE("since"), + DEPRECATED("deprecated"), + AUTHOR("author"), + SEE("see"), + VERSION("version"), + PARAM("param"), + RETURN("return"), + THROWS("throws"), + OBSOLETE("obsolete"), + EXCEPTION("exception"), + SERIAL("serial"), + PROVISIONAL("provisional"), // never used + DISCOURAGED("discouraged"), // DecimalFormatSymbols(x13), IslamicCalendar(x2) + CATEGORY("category"); // only used in DecimalFormat(x82) + + private final String value; + + private TagKind(String value) { + this.value = value; + } + + static TagKind ofTag(BlockTagTree tag) { + for (TagKind tk : TagKind.values()) { + if (tk.value.equals(tag.getTagName())) { + return tk; + } + } + return TagKind.UNKNOWN; + } + } + + // Known ICU taglets + static enum IcuTagKind { + UNKNOWN(""), + ICU("icu"), + ICUNOTE("icunote"), + ICUENHANCED("icuenhanced"); + + private final String value; + + private IcuTagKind(String value) { + this.value = value; + } + + static IcuTagKind ofTag(InlineTagTree tag) { + for (IcuTagKind tk : IcuTagKind.values()) { + if (tk.value.equals(tag.getTagName())) { + return tk; + } + } + return IcuTagKind.UNKNOWN; + } + } + + // ===== Doclet options convenience class ===== + static class GatherApiDataOption implements Doclet.Option { final int length; final String name; @@ -320,64 +383,4 @@ class JavadocHelper { return strValue != null ? strValue : fallbackValue; } } - - // Known taglets, standard or ICU extensions - static enum TagKind { - UNKNOWN(""), - INTERNAL("internal"), - DRAFT("draft"), - STABLE("stable"), - SINCE("since"), - DEPRECATED("deprecated"), - AUTHOR("author"), - SEE("see"), - VERSION("version"), - PARAM("param"), - RETURN("return"), - THROWS("throws"), - OBSOLETE("obsolete"), - EXCEPTION("exception"), - SERIAL("serial"), - PROVISIONAL("provisional"), // never used - DISCOURAGED("discouraged"), // DecimalFormatSymbols(x13), IslamicCalendar(x2) - CATEGORY("category"); // only used in DecimalFormat(x82) - - private final String value; - - private TagKind(String value) { - this.value = value; - } - - static TagKind ofTag(BlockTagTree tag) { - for (TagKind tk : TagKind.values()) { - if (tk.value.equals(tag.getTagName())) { - return tk; - } - } - return TagKind.UNKNOWN; - } - } - - // Known ICU taglets - static enum IcuTagKind { - UNKNOWN(""), - ICU("icu"), - ICUNOTE("icunote"), - ICUENHANCED("icuenhanced"); - - private final String value; - - private IcuTagKind(String value) { - this.value = value; - } - - static IcuTagKind ofTag(InlineTagTree tag) { - for (IcuTagKind tk : IcuTagKind.values()) { - if (tk.value.equals(tag.getTagName())) { - return tk; - } - } - return IcuTagKind.UNKNOWN; - } - } }