organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-04 13:05:31 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 7

ICU-23040 Doclet migration: the real move from the JDK 8 APIs

Browse source
This commit is contained in:
Mihai Nita 2025-03-24 12:37:00 -07:00 • committed by Markus Scherer
parent 2628d4ed32
commit cfed9374b7
10 changed files with 953 additions and 2053 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
icu4j/pom.xml
View file

@ -688,21 +688,6 @@
</build>
</profile>
<!-- The tools/build module depends on the old tools.jar (jdk 1.8)
The com.sun.javadoc package was deprecated in Java 11, and has been removed for Java 17.
JDK 11 does not include tools.jar anymore. The code must be updated, see migration guide at
https://docs.oracle.com/en/java/javase/11/docs/api/jdk.javadoc/jdk/javadoc/doclet/package-summary.html#migration
-->
<profile>
<id>old_jdk_taglet</id>
<activation>
<jdk>[1.7,1.8]</jdk>
</activation>
<modules>
<module>tools/build</module>
</modules>
</profile>
<!-- Starting with JDK 9, the Java compiler supports the −−release version.
Unlike source (checking the language features) and target (the version of the classes generated),
this option also checks that newer APIs are not used.
@ -716,6 +701,7 @@
<jdk>[9,)</jdk>
</activation>
<modules>
<module>tools/build</module>
<module>tools/taglets</module>
</modules>
<build>

6
icu4j/releases_tools/api_reports.sh
View file

@ -11,8 +11,8 @@ fi
# ====================================================================================
# The start of the script proper
reportTitle "Checking the JDK version (must be 8)"
checkThatJdk8IsDefault
reportTitle "Checking the JDK version (must be newer than 8)"
checkThatJdk8IsNotDefault
# ====================================================================================
@ -22,7 +22,7 @@ mvn clean -q --batch-mode
# Build everything
mvn install -q --batch-mode -DskipITs -DskipTests
# Gather API info
mvn site -q --batch-mode -DskipITs -DskipTests -P gatherapi > /dev/null
mvn site -q --batch-mode -DskipITs -DskipTests -P gatherapi > /dev/null
checkFileCreated "${out_dir}/icu4j${api_report_version}.api3.gz"

4
icu4j/releases_tools/github_release.sh
View file

@ -24,8 +24,8 @@ function copyArtifactForGithubRelease() {
# The start of the script proper
release_folder=${out_dir}/github_release
# We still need JDK 8 to generate the javadoc (because of the doclets)
checkThatJdk8IsDefault
# We can't use JDK 8 to generate the javadoc (because of the doclets)
checkThatJdk8IsNotDefault
# ====================================================================================
# Build artifacts and copy them in the output folder

11
icu4j/releases_tools/shared.sh
View file

@ -11,16 +11,15 @@ export api_report_version='77'
export api_report_prev_version='76'
export out_dir=target
function checkThatJdk8IsDefault() {
function checkThatJdk8IsNotDefault() {
javac -version appPath 2>&1 | grep -E 'javac 1\.8\.' > /dev/null
if [ $? -eq 0 ]; then
echo "The default JDK is JDK 8, all good!"
javac -version
else
echo "This step can only be executed with JDK 8!"
echo "Make sure that you have the PATH pointing to a JDK 8!"
echo "This step can only be executed with a JDK newer than 8!"
javac -version
exit
else
echo "The default JDK is newer than JDK 8, all good!"
javac -version
fi
}

30
icu4j/tools/build/pom.xml
View file

@ -15,17 +15,27 @@
<artifactId>tools_build</artifactId>
<properties>
<icu4j.api.doc.root.dir>${project.basedir}/../..</icu4j.api.doc.root.dir>
<maven.compiler.source>11</maven.compiler.source>
<maven.compiler.target>11</maven.compiler.target>
</properties>
<dependencies>
<dependency>
<groupId>jdk.tools</groupId>
<artifactId>jdk.tools</artifactId>
<version>1.8</version>
<scope>system</scope>
<systemPath>${JAVA_HOME}/lib/tools.jar</systemPath>
</dependency>
</dependencies>
<profiles>
<profile>
<id>newer_jdk</id>
<activation>
<jdk>[11,)</jdk>
</activation>
<build>
<plugins>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<release>11</release>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

1052
icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckAPI.java
View file

File diff suppressed because it is too large Load diff

289
icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/CheckTags.java
View file

@ -32,15 +32,32 @@
package com.ibm.icu.dev.tool.docs;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.stream.Collectors;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.QualifiedNameable;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.Elements;
import com.sun.source.doctree.BlockTagTree;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.InlineTagTree;
import com.sun.source.util.DocTrees;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;
public class CheckTags implements Doclet {
private DocTrees docTrees;
private Elements elements;
public class CheckTags {
RootDoc root;
boolean log;
boolean brief;
boolean isShort;
@ -118,7 +135,7 @@ public class CheckTags {
DocNode last = stack[ix];
if (error) {
last.errorCount += 1;
}
}
boolean show = !brief || last.reportError;
// boolean nomsg = show && brief && error;
@ -162,86 +179,61 @@ public class CheckTags {
}
}
public static boolean start(RootDoc root) {
return new CheckTags(root).run();
@Override
public SourceVersion getSupportedSourceVersion() {
// The documentation says "usually the latest version"
// But even if at this time JDK 23 is already released, we
// want to be able to compile / use this doclet with at least JDK 11.
// So anything above RELEASE_11 is undefined
return SourceVersion.RELEASE_11;
}
public static int optionLength(String option) {
if (option.equals("-log")) {
return 1;
} else if (option.equals("-brief")) {
return 1;
} else if (option.equals("-short")) {
return 1;
}
return 0;
@Override
public void init(Locale locale, Reporter reporter) {
}
CheckTags(RootDoc root) {
this.root = root;
@Override
public String getName() {
return this.getClass().getSimpleName();
}
String[][] options = root.options();
for (int i = 0; i < options.length; ++i) {
String opt = options[i][0];
if (opt.equals("-log")) {
this.log = true;
} else if (opt.equals("-brief")) {
this.brief = true;
} else if (opt.equals("-short")) {
this.isShort = true;
@Override
public Set<Option> getSupportedOptions() {
return SUPPORTED_OPTIONS;
}
private final static Set<Option> SUPPORTED_OPTIONS = Set.of(
new JavadocHelper.GatherApiDataOption(0, "-log", "log", "the description of name"),
new JavadocHelper.GatherApiDataOption(0, "-brief", "brief", "the description of output"),
new JavadocHelper.GatherApiDataOption(0, "-short", "short", "the description of base"));
private void initFromOptions() {
for (Option opt : SUPPORTED_OPTIONS) {
JavadocHelper.GatherApiDataOption option = (JavadocHelper.GatherApiDataOption) opt;
switch (option.getName()) {
case "-log":
this.log = option.getBooleanValue(false);
break;
case "-brief":
this.brief = option.getBooleanValue(false);
break;
case "-isShort":
this.isShort = option.getBooleanValue(false);
break;
}
}
}
boolean run() {
doDocs(root.classes(), "Package", true);
return false;
}
static final String[] tagKinds = {
"@internal", "@draft", "@stable", "@since", "@deprecated", "@author", "@see", "@version",
"@param", "@return", "@throws", "@obsolete", "@exception", "@serial", "@provisional"
};
static final int UNKNOWN = -1;
static final int INTERNAL = 0;
static final int DRAFT = 1;
static final int STABLE = 2;
static final int SINCE = 3;
static final int DEPRECATED = 4;
static final int AUTHOR = 5;
static final int SEE = 6;
static final int VERSION = 7;
static final int PARAM = 8;
static final int RETURN = 9;
static final int THROWS = 10;
static final int OBSOLETE = 11;
static final int EXCEPTION = 12;
static final int SERIAL = 13;
static final int PROVISIONAL = 14;
static int tagKindIndex(String kind) {
for (int i = 0; i < tagKinds.length; ++i) {
if (kind.equals(tagKinds[i])) {
return i;
}
}
return UNKNOWN;
}
static final String[] icuTagNames = {
"@icu", "@icunote", "@icuenhanced"
};
static final int ICU = 0;
static final int ICUNOTE = 1;
static final int ICUENHANCED = 2;
static int icuTagIndex(String name) {
for (int i = 0; i < icuTagNames.length; ++i) {
if (icuTagNames[i].equals(name)) {
return i;
}
}
return UNKNOWN;
@Override
public boolean run(DocletEnvironment environment) {
docTrees = environment.getDocTrees();
elements = environment.getElementUtils();
initFromOptions();
List<? extends Element> allClasses = environment.getIncludedElements().stream()
.filter(e-> e.getKind().isClass())
.collect(Collectors.toList());
doDocs(allClasses, "Package", true);
return true;
}
boolean newline = false;
@ -274,46 +266,45 @@ public class CheckTags {
output(msg, true, true);
}
void tagErr(String msg, Tag tag) {
// Tag.position() requires JDK 1.4, build.xml tests for this
void tagErr(String msg, Element element, DocTree tag) {
if (msg.length() > 0) {
msg += ": ";
}
errln(msg + tag.toString() + " [" + tag.position() + "]");
errln(msg + tag.toString() + " [" + JavadocHelper.position(elements, docTrees, element, tag) + "]");
};
void tagErr(Tag tag) {
tagErr("", tag);
void tagErr(Element element, BlockTagTree tag) {
tagErr("", element, tag);
}
void doDocs(ProgramElementDoc[] docs, String header, boolean reportError) {
if (docs != null && docs.length > 0) {
void doDocs(Collection<? extends Element> elements, String header, boolean reportError) {
if (elements != null && !elements.isEmpty()) {
stack.push(header, reportError);
for (int i = 0; i < docs.length; ++i) {
doDoc(docs[i]);
for (Element element : elements) {
doDoc(element);
}
stack.pop();
}
}
void doDoc(ProgramElementDoc doc) {
if (doc != null && (doc.isPublic() || doc.isProtected())
&& !(doc instanceof ConstructorDoc && ((ConstructorDoc)doc).isSynthetic())) {
void doDoc(Element doc) {
if (doc != null && (JavadocHelper.isPublic(doc) || JavadocHelper.isProtected(doc))
&& !(JavadocHelper.isKindConstructor(doc) && JavadocHelper.isSynthetic(elements, doc))) {
// 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 = doc.isClass() || doc.isInterface();
boolean isClass = JavadocHelper.isKindClassOrInterface(doc);
String header;
if (!isShort || isClass) {
header = "--- ";
} else {
header = "";
}
header += (isClass ? doc.qualifiedName() : doc.name());
if (doc instanceof ExecutableMemberDoc) {
header += ((ExecutableMemberDoc)doc).flatSignature();
if (doc instanceof ExecutableElement) {
header += JavadocHelper.flatSignature(doc);
} else {
header += (isClass ? ((QualifiedNameable) doc).getQualifiedName() : doc.getSimpleName());
}
if (!isShort || isClass) {
header += " ---";
@ -324,17 +315,23 @@ public class CheckTags {
}
boolean recurse = doTags(doc);
if (recurse && isClass) {
ClassDoc cdoc = (ClassDoc)doc;
doDocs(cdoc.fields(), "Fields", !brief);
doDocs(cdoc.constructors(), "Constructors", !brief);
doDocs(cdoc.methods(), "Methods", !brief);
TypeElement cdoc = (TypeElement)doc;
List<? extends Element> fields = cdoc.getEnclosedElements().stream()
.filter(JavadocHelper::isKindField).collect(Collectors.toList());
doDocs(fields, "Fields", !brief);
List<? extends Element> constructors = cdoc.getEnclosedElements().stream()
.filter(JavadocHelper::isKindConstructor).collect(Collectors.toList());
doDocs(constructors, "Constructors", !brief);
List<? extends Element> methods = cdoc.getEnclosedElements().stream()
.filter(JavadocHelper::isKindMethod).collect(Collectors.toList());
doDocs(methods, "Methods", !brief);
}
stack.pop();
}
}
/** Return true if subelements of this doc should be checked */
boolean doTags(ProgramElementDoc doc) {
boolean doTags(Element doc) {
boolean foundRequiredTag = false;
boolean foundDraftTag = false;
boolean foundProvisionalTag = false;
@ -344,45 +341,52 @@ public class CheckTags {
boolean foundStableTag = false;
boolean retainAll = false;
if (JavadocHelper.isIgnoredEnumMethod(doc)) {
return false;
}
// first check inline tags
for (Tag tag : doc.inlineTags()) {
int index = icuTagIndex(tag.name());
if (index >= 0) {
String text = tag.text().trim();
switch (index) {
for (InlineTagTree tag : JavadocHelper.getInnerTags(docTrees, doc)) {
JavadocHelper.IcuTagKind index = JavadocHelper.IcuTagKind.ofTag(tag);
String text = JavadocHelper.toText(tag).trim();
// System.out.println("SPY ==== " + tag + " === " + index + " == '" + text + "'");
switch (index) {
case ICU: {
if (doc.isClass() || doc.isInterface()) {
tagErr("tag should appear only in member docs", tag);
if (JavadocHelper.isKindClassOrInterface(doc)) {
tagErr("tag should appear only in member docs", doc, tag);
}
} break;
case ICUNOTE: {
if (text.length() > 0) {
tagErr("tag should not contain text", tag);
if (!text.isEmpty()) {
tagErr("tag should not contain text", doc, tag);
}
} break;
case ICUENHANCED: {
if (text.length() == 0) {
tagErr("text should name related jdk class", tag);
if (text.isEmpty()) {
tagErr("text should name related jdk class", doc, tag);
}
if (!(doc.isClass() || doc.isInterface())) {
tagErr("tag should appear only in class/interface docs", tag);
if (!(JavadocHelper.isKindClassOrInterface(doc))) {
tagErr("tag should appear only in class/interface docs", doc, tag);
}
} break;
default:
tagErr("unrecognized tag index for tag", tag);
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);
break;
}
}
}
// System.out.println("SPY====== " + doc);
// next check regular tags
for (Tag tag : doc.tags()) {
String kind = tag.kind();
int ix = tagKindIndex(kind);
for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, doc)) {
JavadocHelper.TagKind ix = JavadocHelper.TagKind.ofTag(tag);
String tagText = JavadocHelper.toText(tag);
// System.out.println("SPY ==== " + tag + " === " + ix + " == '" + tagText + "'");
switch (ix) {
case UNKNOWN:
errln("unknown kind: " + kind);
errln("unknown kind: " + tag.getTagName());
break;
case INTERNAL:
@ -393,16 +397,16 @@ public class CheckTags {
case DRAFT:
foundRequiredTag = true;
foundDraftTag = true;
if (tag.text().indexOf("ICU 2.8") != -1 &&
tag.text().indexOf("(retain") == -1) { // catch both retain and retainAll
tagErr(tag);
if (tagText.indexOf("ICU 2.8") != -1 &&
tagText.indexOf("(retain") == -1) { // catch both retain and retainAll
tagErr(doc, tag);
break;
}
if (tag.text().indexOf("ICU") != 0) {
tagErr(tag);
if (tagText.indexOf("ICU") != 0) {
tagErr(doc, tag);
break;
}
retainAll |= (tag.text().indexOf("(retainAll)") != -1);
retainAll |= (tagText.indexOf("(retainAll)") != -1);
break;
case PROVISIONAL:
@ -411,14 +415,14 @@ public class CheckTags {
case DEPRECATED:
foundDeprecatedTag = true;
if (tag.text().indexOf("ICU") == 0) {
if (tagText.indexOf("ICU") == 0) {
foundRequiredTag = true;
}
break;
case OBSOLETE:
if (tag.text().indexOf("ICU") != 0) {
tagErr(tag);
if (tagText.indexOf("ICU") != 0) {
tagErr(doc, tag);
}
foundObsoleteTag = true;
foundRequiredTag = true;
@ -426,9 +430,8 @@ public class CheckTags {
case STABLE:
{
String text = tag.text();
if (text.length() != 0 && text.indexOf("ICU") != 0) {
tagErr(tag);
if (tagText.length() != 0 && tagText.indexOf("ICU") != 0) {
tagErr(tagText, doc, tag);
}
foundRequiredTag = true;
foundStableTag = true;
@ -436,11 +439,13 @@ public class CheckTags {
break;
case SINCE:
tagErr(tag);
tagErr(doc, tag);
break;
case EXCEPTION:
logln("You really ought to use @throws, you know... :-)");
//TODO: Why would we report this?
// logln("You really ought to use @throws, you know... :-)");
break;
case AUTHOR:
case SEE:
@ -448,18 +453,20 @@ public class CheckTags {
case RETURN:
case THROWS:
case SERIAL:
case DISCOURAGED:
case CATEGORY:
break;
case VERSION:
tagErr(tag);
tagErr(doc, tag);
break;
default:
errln("unknown index: " + ix);
}
}
} // end if switch
} // end of iteration on tags
if (!foundRequiredTag) {
errln("missing required tag [" + doc.position() + "]");
errln("missing required tag [" + JavadocHelper.position(elements, docTrees, doc) + "]");
}
if (foundInternalTag && !foundDeprecatedTag) {
errln("internal tag missing deprecated");

706
icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIData.java
View file

@ -50,136 +50,96 @@ import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.nio.charset.StandardCharsets;
import java.util.Collection;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.TreeSet;
import java.util.regex.Pattern;
import java.util.zip.GZIPOutputStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.LanguageVersion;
import com.sun.javadoc.MemberDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
import javax.annotation.processing.SupportedAnnotationTypes;
import javax.annotation.processing.SupportedSourceVersion;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
import javax.lang.model.type.ArrayType;
import javax.lang.model.type.DeclaredType;
import javax.lang.model.type.ErrorType;
import javax.lang.model.type.ExecutableType;
import javax.lang.model.type.IntersectionType;
import javax.lang.model.type.NoType;
import javax.lang.model.type.NullType;
import javax.lang.model.type.PrimitiveType;
import javax.lang.model.type.TypeMirror;
import javax.lang.model.type.TypeVariable;
import javax.lang.model.type.TypeVisitor;
import javax.lang.model.type.UnionType;
import javax.lang.model.type.WildcardType;
import javax.lang.model.util.Elements;
public class GatherAPIData {
RootDoc root;
TreeSet results;
String srcName = "Current"; // default source name
String output; // name of output file to write
String base; // strip this prefix
Pattern pat;
boolean zip;
boolean gzip;
boolean internal;
boolean version;
import com.sun.source.doctree.BlockTagTree;
import com.sun.source.util.DocTrees;
public static int optionLength(String option) {
if (option.equals("-name")) {
return 2;
} else if (option.equals("-output")) {
return 2;
} else if (option.equals("-base")) {
return 2;
} else if (option.equals("-filter")) {
return 2;
} else if (option.equals("-zip")) {
return 1;
} else if (option.equals("-gzip")) {
return 1;
} else if (option.equals("-internal")) {
return 1;
} else if (option.equals("-version")) {
return 1;
}
return 0;
import jdk.javadoc.doclet.Doclet;
import jdk.javadoc.doclet.DocletEnvironment;
import jdk.javadoc.doclet.Reporter;
@SupportedAnnotationTypes("*")
@SupportedSourceVersion(SourceVersion.RELEASE_9)
public class GatherAPIData implements Doclet {
private Elements elementUtils;
private DocTrees docTrees;
private TreeSet<APIInfo> results = new TreeSet<>(APIInfo.defaultComparator());
private String srcName = ""; // default source name
private String output; // name of output file to write
private String base; // strip this prefix
private Pattern pat;
private boolean zip;
private boolean gzip;
private boolean internal;
private boolean version;
@Override
public SourceVersion getSupportedSourceVersion() {
// The documentation says "usually the latest version"
// But even if at this time JDK 23 is already released, we
// want to be able to compile / use this doclet with at least JDK 11.
// So anything above RELEASE_11 is undefined
return SourceVersion.RELEASE_11;
}
public static boolean start(RootDoc root) {
return new GatherAPIData(root).run();
@Override
public void init(Locale locale, Reporter reporter) {
}
/**
* If you don't do this, javadoc treats enums like regular classes!
* doesn't matter if you pass -source 1.5 or not.
*/
public static LanguageVersion languageVersion() {
return LanguageVersion.JAVA_1_5;
@Override
public String getName() {
return this.getClass().getSimpleName();
}
GatherAPIData(RootDoc root) {
this.root = root;
String[][] options = root.options();
for (int i = 0; i < options.length; ++i) {
String opt = options[i][0];
if (opt.equals("-name")) {
this.srcName = options[i][1];
} else if (opt.equals("-output")) {
this.output = options[i][1];
} else if (opt.equals("-base")) {
this.base = options[i][1]; // should not include '.'
} else if (opt.equals("-filter")) {
this.pat = Pattern.compile(options[i][1], Pattern.CASE_INSENSITIVE);
} else if (opt.equals("-zip")) {
this.zip = true;
} else if (opt.equals("-gzip")) {
this.gzip = true;
} else if (opt.equals("-internal")) {
this.internal = true;
} else if (opt.equals("-version")) {
this.version = true;
}
}
results = new TreeSet(APIInfo.defaultComparator());
@Override
public Set<Doclet.Option> getSupportedOptions() {
return SUPPORTED_OPTIONS;
}
private boolean run() {
doDocs(root.classes());
@Override
public boolean run(DocletEnvironment environment) {
elementUtils = environment.getElementUtils();
docTrees = environment.getDocTrees();
OutputStream os = System.out;
if (output != null) {
ZipOutputStream zos = null;
try {
if (zip) {
zos = new ZipOutputStream(new FileOutputStream(output + ".zip"));
zos.putNextEntry(new ZipEntry(output));
os = zos;
} else if (gzip) {
os = new GZIPOutputStream(new FileOutputStream(output + ".gz"));
} else {
os = new FileOutputStream(output);
}
}
catch (IOException e) {
RuntimeException re = new RuntimeException(e.getMessage());
re.initCause(e);
throw re;
}
finally {
if (zos != null) {
try {
zos.close();
} catch (Exception e) {
// ignore
}
}
}
}
BufferedWriter bw = null;
try {
OutputStreamWriter osw = new OutputStreamWriter(os, "UTF-8");
bw = new BufferedWriter(osw);
initFromOptions();
doDocs(environment.getIncludedElements());
try (OutputStream os = getOutputFileAsStream(output);
OutputStreamWriter osw = new OutputStreamWriter(os, StandardCharsets.UTF_8)) {
BufferedWriter bw = new BufferedWriter(osw);
// writing data file
bw.write(String.valueOf(APIInfo.VERSION) + APIInfo.SEP); // header version
bw.write(srcName + APIInfo.SEP); // source name
@ -188,35 +148,44 @@ public class GatherAPIData {
writeResults(results, bw);
bw.close(); // should flush, close all, etc
} catch (IOException e) {
try { bw.close(); } catch (IOException e2) {}
RuntimeException re = new RuntimeException("write error: " + e.getMessage());
RuntimeException re = new RuntimeException(e.getMessage());
re.initCause(e);
throw re;
}
return false;
return true;
}
private void doDocs(ProgramElementDoc[] docs) {
if (docs != null && docs.length > 0) {
for (int i = 0; i < docs.length; ++i) {
doDoc(docs[i]);
private OutputStream getOutputFileAsStream(String output) throws IOException {
if (output == null) {
return System.out;
}
if (zip) {
ZipOutputStream zos = new ZipOutputStream(new FileOutputStream(output + ".zip"));
zos.putNextEntry(new ZipEntry(output));
return zos;
}
if (gzip) {
return new GZIPOutputStream(new FileOutputStream(output + ".gz"));
}
return new FileOutputStream(output);
}
private void doDocs(Collection<? extends Element> docs) {
if (docs != null) {
for (Element doc : docs) {
doDoc(doc);
}
}
}
private void doDoc(ProgramElementDoc doc) {
private void doDoc(Element doc) {
if (ignore(doc)) return;
if (doc.isClass() || doc.isInterface()) {
ClassDoc cdoc = (ClassDoc)doc;
doDocs(cdoc.fields());
doDocs(cdoc.constructors());
doDocs(cdoc.methods());
doDocs(cdoc.enumConstants());
// don't call this to iterate over inner classes,
// root.classes already includes them
// doDocs(cdoc.innerClasses());
// isClass() ==> CLASS || ENUM;
// isInterface() ==> INTERFACE || ANNOTATION_TYPE
if (JavadocHelper.isKindClassOrInterface(doc)) {
doDocs(doc.getEnclosedElements());
}
APIInfo info = createInfo(doc);
@ -225,28 +194,6 @@ public class GatherAPIData {
}
}
// Sigh. Javadoc doesn't indicate when the compiler generates
// the values and valueOf enum methods. The position of the
// method for these is not always the same as the position of
// the class, though it often is, so we can't use that.
private boolean isIgnoredEnumMethod(ProgramElementDoc doc) {
if (doc.isMethod() && doc.containingClass().isEnum()) {
// System.out.println("*** " + doc.qualifiedName() + " pos: " +
// doc.position().line() +
// " contained by: " +
// doc.containingClass().name() +
// " pos: " +
// doc.containingClass().position().line());
// return doc.position().line() == doc.containingClass().position().line();
String name = doc.name();
// assume we don't have enums that overload these method names.
return "values".equals(name) || "valueOf".equals(name);
}
return false;
}
// isSynthesized also doesn't seem to work. Let's do this, documenting
// synthesized constructors for abstract classes is kind of weird.
// We can't actually tell if the constructor was synthesized or is
@ -258,22 +205,38 @@ public class GatherAPIData {
// javadoc comments by the policy. So, we no longer ignore abstract
// class's no-arg constructor blindly. -Yoshito 2014-05-21
private boolean isAbstractClassDefaultConstructor(ProgramElementDoc doc) {
return doc.isConstructor()
&& doc.containingClass().isAbstract()
&& "()".equals(((ConstructorDoc) doc).signature());
private boolean isAbstractClassDefaultConstructor(Element doc) {
return JavadocHelper.isKindConstructor(doc)
&& JavadocHelper.isAbstract(doc.getEnclosingElement())
&& ((ExecutableElement) doc).getParameters().isEmpty();
}
private static final boolean IGNORE_NO_ARG_ABSTRACT_CTOR = false;
private boolean ignore(ProgramElementDoc doc) {
if (doc == null) return true;
if (doc.isPrivate() || doc.isPackagePrivate()) return true;
if (doc instanceof MemberDoc && ((MemberDoc)doc).isSynthetic()) return true;
if (doc.qualifiedName().indexOf(".misc") != -1) {
System.out.println("misc: " + doc.qualifiedName()); return true;
private boolean ignore(Element doc) {
if (doc == null) {
return true;
}
if (isIgnoredEnumMethod(doc)) {
if (JavadocHelper.isPrivate(doc) || JavadocHelper.isDefault(doc)) {
return true;
}
if (JavadocHelper.isVisibilityPackage(doc)) {
return true;
}
if (JavadocHelper.isKindPackage(doc)) {
return true;
}
if (doc.toString().contains(".misc")) {
System.out.println("misc: " + doc.toString()); {
return true;
}
}
if (JavadocHelper.isIgnoredEnumMethod(doc)) {
return true;
}
@ -281,66 +244,41 @@ public class GatherAPIData {
return true;
}
if (false && doc.qualifiedName().indexOf("LocaleDisplayNames") != -1) {
System.err.print("*** " + doc.qualifiedName() + ":");
if (doc.isClass()) System.err.print(" class");
if (doc.isConstructor()) System.err.print(" constructor");
if (doc.isEnum()) System.err.print(" enum");
if (doc.isEnumConstant()) System.err.print(" enum_constant");
if (doc.isError()) System.err.print(" error");
if (doc.isException()) System.err.print(" exception");
if (doc.isField()) System.err.print(" field");
if (doc.isInterface()) System.err.print(" interface");
if (doc.isMethod()) System.err.print(" method");
if (doc.isOrdinaryClass()) System.err.print(" ordinary_class");
System.err.println();
}
if (!internal) { // debug
Tag[] tags = doc.tags();
for (int i = 0; i < tags.length; ++i) {
if (tagKindIndex(tags[i].kind()) == INTERNAL) { return true; }
for (BlockTagTree tag : JavadocHelper.getBlockTags(docTrees, doc)) {
if (JavadocHelper.TagKind.ofTag(tag) == JavadocHelper.TagKind.INTERNAL) {
return true;
}
}
}
if (pat != null && (doc.isClass() || doc.isInterface())) {
if (!pat.matcher(doc.name()).matches()) {
if (pat != null && JavadocHelper.isKindClassOrInterface(doc)) {
if (!pat.matcher(doc.getSimpleName().toString()).matches()) {
return true;
}
}
return false;
}
private static void writeResults(Collection c, BufferedWriter w) {
Iterator iter = c.iterator();
while (iter.hasNext()) {
APIInfo info = (APIInfo)iter.next();
private static void writeResults(Collection<APIInfo> c, BufferedWriter w) {
for (APIInfo info : c) {
info.writeln(w);
}
}
private String trimBase(String arg) {
String orgArg = arg;
if (base != null) {
for (int n = arg.indexOf(base); n != -1; n = arg.indexOf(base, n)) {
arg = arg.substring(0, n) + arg.substring(n+base.length());
arg = arg.substring(0, n) + arg.substring(n + base.length());
}
}
return arg;
}
public APIInfo createInfo(ProgramElementDoc doc) {
// Doc. name
// Doc. isField, isMethod, isConstructor, isClass, isInterface
// ProgramElementDoc. containingClass, containingPackage
// ProgramElementDoc. isPublic, isProtected, isPrivate, isPackagePrivate
// ProgramElementDoc. isStatic, isFinal
// MemberDoc.isSynthetic
// ExecutableMemberDoc isSynchronized, signature
// Type.toString() // e.g. "String[][]"
// ClassDoc.isAbstract, superClass, interfaces, fields, methods, constructors, innerClasses
// FieldDoc type
// ConstructorDoc qualifiedName
// MethodDoc isAbstract, returnType
private APIInfo createInfo(Element doc) {
if (ignore(doc)) return null;
APIInfo info = new APIInfo();
if (version) {
@ -353,128 +291,172 @@ public class GatherAPIData {
info.setStatusVersion(version[0]);
// visibility
if (doc.isPublic()) {
if (JavadocHelper.isPublic(doc)) {
info.setPublic();
} else if (doc.isProtected()) {
} else if (JavadocHelper.isProtected(doc)) {
info.setProtected();
} else if (doc.isPrivate()) {
} else if (JavadocHelper.isPrivate(doc)) {
info.setPrivate();
} else {
// default is package
}
// static
if (doc.isStatic()) {
if (JavadocHelper.isStatic(doc)) {
info.setStatic();
} else {
// default is non-static
}
// final
if (doc.isFinal() && !doc.isEnum()) {
// Final. Enums are final by default.
if (JavadocHelper.isFinal(doc) && !JavadocHelper.isKindEnum(doc)) {
info.setFinal();
} else {
// default is non-final
}
// type
if (doc.isField()) {
if (JavadocHelper.isKindFieldExact(doc)) {
info.setField();
} else if (doc.isMethod()) {
} else if (JavadocHelper.isKindMethod(doc)) {
info.setMethod();
} else if (doc.isConstructor()) {
} else if (JavadocHelper.isKindConstructor(doc)) {
info.setConstructor();
} else if (doc.isClass() || doc.isInterface()) {
if (doc.isEnum()) {
} else if (JavadocHelper.isKindClassOrInterface(doc)) {
if (JavadocHelper.isKindEnum(doc)) {
info.setEnum();
} else {
info.setClass();
}
} else if (doc.isEnumConstant()) {
} else if (JavadocHelper.isKindEnumConstant(doc)) {
info.setEnumConstant();
}
info.setPackage(trimBase(doc.containingPackage().name()));
PackageElement packageElement = elementUtils.getPackageOf(doc);
info.setPackage(trimBase(packageElement.getQualifiedName().toString()));
String className = (doc.isClass() || doc.isInterface() || (doc.containingClass() == null))
String className = (JavadocHelper.isKindClassOrInterface(doc) || doc.getEnclosingElement() == null)
? ""
: doc.containingClass().name();
: withoutPackage(doc.getEnclosingElement());
info.setClassName(className);
String name = doc.name();
if (doc.isConstructor()) {
// Workaround for Javadoc incompatibility between 7 and 8.
// Javadoc 7 prepends enclosing class name for a nested
// class's constructor. We need to generate the same format
// because existing ICU API signature were generated with
// Javadoc 7 or older verions.
int dotIdx = className.lastIndexOf('.');
if (!name.contains(".") && dotIdx > 0) {
name = className.substring(0, dotIdx + 1) + name;
}
String name = doc.getSimpleName().toString();
if (JavadocHelper.isKindConstructor(doc)) {
// The constructor name is always `<init>` 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);
}
info.setName(name);
if (doc instanceof FieldDoc) {
FieldDoc fdoc = (FieldDoc)doc;
info.setSignature(trimBase(fdoc.type().toString()));
} else if (doc instanceof ClassDoc) {
ClassDoc cdoc = (ClassDoc)doc;
if (JavadocHelper.isKindField(doc)) {
VariableElement fdoc = (VariableElement) doc;
hackSetSignature(info, trimBase(fdoc.asType().toString()));
} else if (JavadocHelper.isKindClassOrInterface(doc)) {
TypeElement cdoc = (TypeElement) doc;
if (cdoc.isClass() && cdoc.isAbstract()) {
if (!JavadocHelper.isKindInterface(doc) && JavadocHelper.isAbstract(cdoc)) {
// interfaces are abstract by default, don't mark them as abstract
info.setAbstract();
}
StringBuffer buf = new StringBuffer();
if (cdoc.isClass()) {
if (JavadocHelper.isKindClass(cdoc)) {
buf.append("extends ");
buf.append(cdoc.superclassType().toString());
buf.append(cdoc.getSuperclass().toString());
}
ClassDoc[] imp = cdoc.interfaces();
if (imp != null && imp.length > 0) {
List<? extends TypeMirror> imp = cdoc.getInterfaces();
if (!imp.isEmpty()) {
if (buf.length() > 0) {
buf.append(" ");
}
buf.append("implements");
for (int i = 0; i < imp.length; ++i) {
for (int i = 0; i < imp.size(); ++i) {
if (i != 0) {
buf.append(",");
}
buf.append(" ");
buf.append(imp[i].qualifiedName());
buf.append(imp.get(i).toString()
.replaceAll("<[^<>]+>", "") // interfaces with parameters.
.replaceAll("<[^<>]+>", "") // 3 nesting levels should be enough
.replaceAll("<[^<>]+>", "") // max I've seen was 2
);
}
}
info.setSignature(trimBase(buf.toString()));
} else {
ExecutableMemberDoc emdoc = (ExecutableMemberDoc)doc;
if (emdoc.isSynchronized()) {
hackSetSignature(info, trimBase(buf.toString()));
} else if (JavadocHelper.isKindMethod(doc) || JavadocHelper.isKindConstructor(doc)) {
ExecutableElement emdoc = (ExecutableElement)doc;
if (JavadocHelper.isSynchronized(emdoc)) {
info.setSynchronized();
}
if (doc instanceof MethodDoc) {
MethodDoc mdoc = (MethodDoc)doc;
if (mdoc.isAbstract()) {
if (JavadocHelper.isKindMethod(doc)) {
if (JavadocHelper.isAbstract(emdoc)) {
// 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 (!mdoc.containingClass().isInterface()) {
if (!JavadocHelper.isKindInterface(emdoc.getEnclosingElement())) {
info.setAbstract();
}
}
info.setSignature(trimBase(mdoc.returnType().toString() + emdoc.signature()));
String retSig = stringFromTypeMirror(emdoc.getReturnType());
// Signature, as returned by default, can be something like this: "boolean<T>containsAll(java.util.Iterator<T>)"
// The old API returned "boolean(java.util.Iterator<T>)"
// Consider using the signature "as is" (including the method name)
hackSetSignature(info, trimBase(retSig + toTheBracket(emdoc.toString())));
} else {
// constructor
info.setSignature(trimBase(emdoc.signature()));
hackSetSignature(info, toTheBracket(emdoc.toString()));
}
} else {
throw new RuntimeException("Unknown element kind: " + doc.getKind());
}
return info;
}
private int tagStatus(final ProgramElementDoc doc, String[] version) {
private static String stringFromTypeMirror(TypeMirror rrt) {
StringBuilder retSig = new StringBuilder();
rrt.accept(new ToStringTypeVisitor(), retSig);
return retSig.toString();
}
private void hackSetSignature(APIInfo info, String value) {
value = value.replace(",", ", ").replace(", ", ", ");
info.setSignature(value);
}
private String withoutPackage(Element enclosingElement) {
if (enclosingElement == null) {
return "";
}
String result = enclosingElement.toString();
PackageElement pack = this.elementUtils.getPackageOf(enclosingElement);
if (pack == null) {
return result;
}
// Takes something like "com.ibm.icu.charset.CharsetCallback.Decoder"
// and removes the package, resulting in "CharsetCallback.Decoder"
// This can't really be done just by looking at the string form.
String packName = pack.getQualifiedName().toString() + ".";
return result.startsWith(packName) ? result.substring(packName.length()) : result;
}
private String toTheBracket(String str) {
if (str == null) return null;
int openBr = str.indexOf('(');
return openBr > 1 ? str.substring(openBr) : str;
}
private int tagStatus(final Element doc, String[] version) {
class Result {
boolean deprecatedFlag = false;
int res = -1;
@ -534,55 +516,54 @@ public class GatherAPIData {
}
}
Tag[] tags = doc.tags();
List<BlockTagTree> tags = JavadocHelper.getBlockTags(docTrees, doc);
Result result = new Result();
String statusVer = "";
for (int i = 0; i < tags.length; ++i) {
Tag tag = tags[i];
String kind = tag.kind();
int ix = tagKindIndex(kind);
for (BlockTagTree tag : tags) {
JavadocHelper.TagKind ix = JavadocHelper.TagKind.ofTag(tag);
switch (ix) {
case INTERNAL:
result.set(internal ? APIInfo.STA_INTERNAL : -2); // -2 for legacy compatibility
statusVer = getStatusVersion(tag);
break;
case INTERNAL:
result.set(internal ? APIInfo.STA_INTERNAL : -2); // -2 for legacy compatibility
statusVer = getStatusVersion(tag);
break;
case DRAFT:
result.set(APIInfo.STA_DRAFT);
statusVer = getStatusVersion(tag);
break;
case DRAFT:
result.set(APIInfo.STA_DRAFT);
statusVer = getStatusVersion(tag);
break;
case STABLE:
result.set(APIInfo.STA_STABLE);
statusVer = getStatusVersion(tag);
break;
case STABLE:
result.set(APIInfo.STA_STABLE);
statusVer = getStatusVersion(tag);
break;
case DEPRECATED:
result.set(APIInfo.STA_DEPRECATED);
statusVer = getStatusVersion(tag);
break;
case DEPRECATED:
result.set(APIInfo.STA_DEPRECATED);
statusVer = getStatusVersion(tag);
break;
case OBSOLETE:
result.set(APIInfo.STA_OBSOLETE);
statusVer = getStatusVersion(tag);
break;
case OBSOLETE:
result.set(APIInfo.STA_OBSOLETE);
statusVer = getStatusVersion(tag);
break;
case SINCE:
case EXCEPTION:
case VERSION:
case UNKNOWN:
case AUTHOR:
case SEE:
case PARAM:
case RETURN:
case THROWS:
case SERIAL:
break;
case SINCE:
case EXCEPTION:
case VERSION:
case UNKNOWN:
case AUTHOR:
case SEE:
case PARAM:
case RETURN:
case THROWS:
case SERIAL:
case DISCOURAGED:
case CATEGORY:
break;
default:
throw new RuntimeException("unknown index " + ix + " for tag: " + kind);
default:
throw new RuntimeException("unknown index " + ix + " for tag: " + tag);
}
}
@ -592,8 +573,8 @@ public class GatherAPIData {
return result.get();
}
private String getStatusVersion(Tag tag) {
String text = tag.text();
private String getStatusVersion(BlockTagTree tag) {
String text = tag.toString();
if (text != null && text.length() > 0) {
// Extract version string
int start = -1;
@ -615,33 +596,128 @@ public class GatherAPIData {
return "";
}
private static final int UNKNOWN = -1;
private static final int INTERNAL = 0;
private static final int DRAFT = 1;
private static final int STABLE = 2;
private static final int SINCE = 3;
private static final int DEPRECATED = 4;
private static final int AUTHOR = 5;
private static final int SEE = 6;
private static final int VERSION = 7;
private static final int PARAM = 8;
private static final int RETURN = 9;
private static final int THROWS = 10;
private static final int OBSOLETE = 11;
private static final int EXCEPTION = 12;
private static final int SERIAL = 13;
private final static Set<Doclet.Option> SUPPORTED_OPTIONS = Set.of(
new JavadocHelper.GatherApiDataOption(1, "-name", "the_name", "the description of name"),
new JavadocHelper.GatherApiDataOption(1, "-output", "the_output", "the description of output"),
new JavadocHelper.GatherApiDataOption(1, "-base", "the_base", "the description of base"),
new JavadocHelper.GatherApiDataOption(1, "--filter", "the_filter", "the description of filter"),
new JavadocHelper.GatherApiDataOption(0, "-zip", "the description of zip"),
new JavadocHelper.GatherApiDataOption(0, "-gzip", "the description of gzip"),
new JavadocHelper.GatherApiDataOption(0, "-internal", "the description of internal"),
new JavadocHelper.GatherApiDataOption(0, "-version", "the description of version")
);
private static int tagKindIndex(String kind) {
final String[] tagKinds = {
"@internal", "@draft", "@stable", "@since", "@deprecated", "@author", "@see",
"@version", "@param", "@return", "@throws", "@obsolete", "@exception", "@serial"
};
for (int i = 0; i < tagKinds.length; ++i) {
if (kind.equals(tagKinds[i])) {
return i;
private void initFromOptions() {
for (Doclet.Option opt : SUPPORTED_OPTIONS) {
JavadocHelper.GatherApiDataOption option = (JavadocHelper.GatherApiDataOption) opt;
switch (option.getName()) {
case "-name":
this.srcName = option.getStringValue("");
break;
case "-output":
this.output = option.getStringValue(null);
break;
case "-base":
this.base = option.getStringValue(null); // should not include '.'
break;
case "-filter":
String filt = option.getStringValue(null);
if (filt != null) {
this.pat = Pattern.compile(filt, Pattern.CASE_INSENSITIVE);
}
break;
case "-zip":
this.zip = option.getBooleanValue(false);
break;
case "-gzip":
this.gzip = option.getBooleanValue(false);
break;
case "-internal":
this.internal = option.getBooleanValue(false);
break;
case "-version":
this.version = option.getBooleanValue(false);
break;
}
}
return UNKNOWN;
}
static class ToStringTypeVisitor implements TypeVisitor<StringBuilder, StringBuilder> {
@Override
public StringBuilder visitPrimitive(PrimitiveType t, StringBuilder p) {
return p.append(t);
}
@Override
public StringBuilder visitArray(ArrayType t, StringBuilder p) {
return p.append(t);
}
@Override
public StringBuilder visitDeclared(DeclaredType t, StringBuilder p) {
return p.append(t);
}
@Override
public StringBuilder visitTypeVariable(TypeVariable t, StringBuilder p) {
String upperBound = t.getUpperBound().toString();
p.append(t.asElement().getSimpleName());
if (!"java.lang.Object".equals(upperBound)) {
return p.append(" extends ").append(upperBound);
}
return p;
}
@Override
public StringBuilder visitNoType(NoType t, StringBuilder p) {
return p.append(t);
}
// ==================================================================
// Below this line there are unexpected types.
// But we must implement them because the interface requires it.
// And also because we want to throw (so that we can fix it).
@Override
public StringBuilder visitNull(NullType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor NullType:" + t);
}
@Override
public StringBuilder visitUnknown(TypeMirror t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor TypeMirror:" + t);
}
@Override
public StringBuilder visitUnion(UnionType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor UnionType:" + t);
}
@Override
public StringBuilder visit(TypeMirror t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor TypeMirror:" + t);
}
@Override
public StringBuilder visitIntersection(IntersectionType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor IntersectionType:" + t);
}
@Override
public StringBuilder visitWildcard(WildcardType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor WildcardType:" + t);
}
@Override
public StringBuilder visitExecutable(ExecutableType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor ExecutableType:" + t);
}
@Override
public StringBuilder visitError(ErrorType t, StringBuilder p) {
throw new RuntimeException("Unexpected visitor ErrorType:" + t);
}
}
}

509
icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/GatherAPIDataOld.java
View file

@ -1,509 +0,0 @@
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/**
*******************************************************************************
* Copyright (C) 2004-2012, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
*/
/**
* Generate a list of ICU's public APIs, sorted by qualified name and signature
* public APIs are all non-internal, non-package apis in com.ibm.icu.[lang|math|text|util].
* For each API, list
* - public, package, protected, or private (PB PK PT PR)
* - static or non-static (STK NST)
* - final or non-final (FN NF)
* - synchronized or non-synchronized (SYN NSY)
* - stable, draft, deprecated, obsolete (ST DR DP OB)
* - abstract or non-abstract (AB NA)
* - constructor, member, field (C M F)
*
* Requires JDK 1.4.2 or later
*
* Sample compilation:
* c:/doug/java/jdk1.4.2/build/windows-i586/bin/javac *.java
*
* Sample execution
* c:/j2sdk1.4.2/bin/javadoc
* -classpath c:/jd2sk1.4.2/lib/tools.jar
* -doclet com.ibm.icu.dev.tool.docs.GatherAPIData
* -docletpath c:/doug/cvsproj/icu4j/src
* -sourcepath c:/doug/cvsproj/icu4j/src
* -name "ICU4J 3.0"
* -output icu4j30.api
* -gzip
* -source 1.4
* com.ibm.icu.lang com.ibm.icu.math com.ibm.icu.text com.ibm.icu.util
*
* todo: provide command-line control of filters of which subclasses/packages to process
* todo: record full inheritance hierarchy, not just immediate inheritance
* todo: allow for aliasing comparisons (force (pkg.)*class to be treated as though it
* were in a different pkg/class hierarchy (facilitates comparison of icu4j and java)
*/
package com.ibm.icu.dev.tool.docs;
// standard release sdk won't work, need internal build to get access to javadoc
import java.io.BufferedWriter;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.util.Collection;
import java.util.Iterator;
import java.util.TreeSet;
import java.util.regex.Pattern;
import java.util.zip.GZIPOutputStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.Doc;
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
public class GatherAPIDataOld {
RootDoc root;
TreeSet results;
String srcName = "Current"; // default source name
String output; // name of output file to write
String base; // strip this prefix
Pattern pat;
boolean zip;
boolean gzip;
boolean internal;
boolean version;
public static int optionLength(String option) {
if (option.equals("-name")) {
return 2;
} else if (option.equals("-output")) {
return 2;
} else if (option.equals("-base")) {
return 2;
} else if (option.equals("-filter")) {
return 2;
} else if (option.equals("-zip")) {
return 1;
} else if (option.equals("-gzip")) {
return 1;
} else if (option.equals("-internal")) {
return 1;
} else if (option.equals("-version")) {
return 1;
}
return 0;
}
public static boolean start(RootDoc root) {
return new GatherAPIDataOld(root).run();
}
GatherAPIDataOld(RootDoc root) {
this.root = root;
String[][] options = root.options();
for (int i = 0; i < options.length; ++i) {
String opt = options[i][0];
if (opt.equals("-name")) {
this.srcName = options[i][1];
} else if (opt.equals("-output")) {
this.output = options[i][1];
} else if (opt.equals("-base")) {
this.base = options[i][1]; // should not include '.'
} else if (opt.equals("-filter")) {
this.pat = Pattern.compile(options[i][1], Pattern.CASE_INSENSITIVE);
} else if (opt.equals("-zip")) {
this.zip = true;
} else if (opt.equals("-gzip")) {
this.gzip = true;
} else if (opt.equals("-internal")) {
this.internal = true;
} else if (opt.equals("-version")) {
this.version = true;
}
}
results = new TreeSet(APIInfo.defaultComparator());
}
private boolean run() {
doDocs(root.classes());
OutputStream os = System.out;
if (output != null) {
ZipOutputStream zos = null;
try {
if (zip) {
zos = new ZipOutputStream(new FileOutputStream(output + ".zip"));
zos.putNextEntry(new ZipEntry(output));
os = zos;
} else if (gzip) {
os = new GZIPOutputStream(new FileOutputStream(output + ".gz"));
} else {
os = new FileOutputStream(output);
}
}
catch (IOException e) {
RuntimeException re = new RuntimeException(e.getMessage());
re.initCause(e);
throw re;
}
finally {
if (zos != null) {
try {
zos.close();
} catch (Exception e) {
// ignore
}
}
}
}
BufferedWriter bw = null;
try {
OutputStreamWriter osw = new OutputStreamWriter(os, "UTF-8");
bw = new BufferedWriter(osw);
// writing data file
bw.write(String.valueOf(APIInfo.VERSION) + APIInfo.SEP); // header version
bw.write(srcName + APIInfo.SEP); // source name
bw.write((base == null ? "" : base) + APIInfo.SEP); // base
bw.newLine();
writeResults(results, bw);
bw.close(); // should flush, close all, etc
} catch (IOException e) {
try { bw.close(); } catch (IOException e2) {}
RuntimeException re = new RuntimeException("write error: " + e.getMessage());
re.initCause(e);
throw re;
}
return false;
}
private void doDocs(ProgramElementDoc[] docs) {
if (docs != null && docs.length > 0) {
for (int i = 0; i < docs.length; ++i) {
doDoc(docs[i]);
}
}
}
private void doDoc(ProgramElementDoc doc) {
if (ignore(doc)) return;
if (doc.isClass() || doc.isInterface()) {
ClassDoc cdoc = (ClassDoc)doc;
doDocs(cdoc.fields());
doDocs(cdoc.constructors());
doDocs(cdoc.methods());
doDocs(cdoc.innerClasses());
}
APIInfo info = createInfo(doc);
if (info != null) {
results.add(info);
}
}
private boolean ignore(ProgramElementDoc doc) {
if (doc == null) return true;
if (doc.isPrivate() || doc.isPackagePrivate()) return true;
if (doc instanceof ConstructorDoc && ((ConstructorDoc)doc).isSynthetic()) return true;
if (doc.qualifiedName().indexOf(".misc") != -1) {
System.out.println("misc: " + doc.qualifiedName()); return true;
}
if (!internal) { // debug
Tag[] tags = doc.tags();
for (int i = 0; i < tags.length; ++i) {
if (tagKindIndex(tags[i].kind()) == INTERNAL) { return true; }
}
}
if (pat != null && (doc.isClass() || doc.isInterface())) {
if (!pat.matcher(doc.name()).matches()) {
return true;
}
}
return false;
}
private static void writeResults(Collection c, BufferedWriter w) {
Iterator iter = c.iterator();
while (iter.hasNext()) {
APIInfo info = (APIInfo)iter.next();
info.writeln(w);
}
}
private String trimBase(String arg) {
if (base != null) {
for (int n = arg.indexOf(base); n != -1; n = arg.indexOf(base, n)) {
arg = arg.substring(0, n) + arg.substring(n+base.length());
}
}
return arg;
}
public APIInfo createInfo(ProgramElementDoc doc) {
// Doc. name
// Doc. isField, isMethod, isConstructor, isClass, isInterface
// ProgramElementDoc. containingClass, containingPackage
// ProgramElementDoc. isPublic, isProtected, isPrivate, isPackagePrivate
// ProgramElementDoc. isStatic, isFinal
// MemberDoc.isSynthetic
// ExecutableMemberDoc isSynchronized, signature
// Type.toString() // e.g. "String[][]"
// ClassDoc.isAbstract, superClass, interfaces, fields, methods, constructors, innerClasses
// FieldDoc type
// ConstructorDoc qualifiedName
// MethodDoc isAbstract, returnType
APIInfo info = new APIInfo();
if (version) {
info.includeStatusVersion(true);
}
// status
String[] version = new String[1];
info.setType(APIInfo.STA, tagStatus(doc, version));
info.setStatusVersion(version[0]);
// visibility
if (doc.isPublic()) {
info.setPublic();
} else if (doc.isProtected()) {
info.setProtected();
} else if (doc.isPrivate()) {
info.setPrivate();
} else {
// default is package
}
// static
if (doc.isStatic()) {
info.setStatic();
} else {
// default is non-static
}
// final
if (doc.isFinal()) {
info.setFinal();
} else {
// default is non-final
}
// type
if (doc.isField()) {
info.setField();
} else if (doc.isMethod()) {
info.setMethod();
} else if (doc.isConstructor()) {
info.setConstructor();
} else if (doc.isClass() || doc.isInterface()) {
info.setClass();
}
info.setPackage(trimBase(doc.containingPackage().name()));
info.setClassName((doc.isClass() || doc.isInterface() || (doc.containingClass() == null))
? ""
: trimBase(doc.containingClass().name()));
info.setName(trimBase(doc.name()));
if (doc instanceof FieldDoc) {
FieldDoc fdoc = (FieldDoc)doc;
info.setSignature(trimBase(fdoc.type().toString()));
} else if (doc instanceof ClassDoc) {
ClassDoc cdoc = (ClassDoc)doc;
if (cdoc.isClass() && cdoc.isAbstract()) {
// interfaces are abstract by default, don't mark them as abstract
info.setAbstract();
}
StringBuffer buf = new StringBuffer();
if (cdoc.isClass()) {
buf.append("extends ");
buf.append(cdoc.superclass().qualifiedName());
}
ClassDoc[] imp = cdoc.interfaces();
if (imp != null && imp.length > 0) {
if (buf.length() > 0) {
buf.append(" ");
}
buf.append("implements");
for (int i = 0; i < imp.length; ++i) {
if (i != 0) {
buf.append(",");
}
buf.append(" ");
buf.append(imp[i].qualifiedName());
}
}
info.setSignature(trimBase(buf.toString()));
} else {
ExecutableMemberDoc emdoc = (ExecutableMemberDoc)doc;
if (emdoc.isSynchronized()) {
info.setSynchronized();
}
if (doc instanceof MethodDoc) {
MethodDoc mdoc = (MethodDoc)doc;
if (mdoc.isAbstract()) {
info.setAbstract();
}
info.setSignature(trimBase(mdoc.returnType().toString() + emdoc.signature()));
} else {
// constructor
info.setSignature(trimBase(emdoc.signature()));
}
}
return info;
}
private int tagStatus(final Doc doc, String[] version) {
class Result {
int res = -1;
void set(int val) {
if (res != -1) {
if (val == APIInfo.STA_DEPRECATED) {
// ok to have both a 'standard' tag and deprecated
return;
} else if (res != APIInfo.STA_DEPRECATED) {
// if already not deprecated, this is an error
System.err.println("bad doc: " + doc + " both: " + APIInfo.getTypeValName(APIInfo.STA, res) + " and: " + APIInfo.getTypeValName(APIInfo.STA, val));
return;
}
}
// ok to replace with new tag
res = val;
}
int get() {
if (res == -1) {
System.err.println("warning: no tag for " + doc);
return 0;
}
return res;
}
}
Tag[] tags = doc.tags();
Result result = new Result();
String statusVer = "";
for (int i = 0; i < tags.length; ++i) {
Tag tag = tags[i];
String kind = tag.kind();
int ix = tagKindIndex(kind);
switch (ix) {
case INTERNAL:
result.set(internal ? APIInfo.STA_INTERNAL : -2); // -2 for legacy compatibility
statusVer = getStatusVersion(tag);
break;
case DRAFT:
result.set(APIInfo.STA_DRAFT);
statusVer = getStatusVersion(tag);
break;
case STABLE:
result.set(APIInfo.STA_STABLE);
statusVer = getStatusVersion(tag);
break;
case DEPRECATED:
result.set(APIInfo.STA_DEPRECATED);
statusVer = getStatusVersion(tag);
break;
case OBSOLETE:
result.set(APIInfo.STA_OBSOLETE);
statusVer = getStatusVersion(tag);
break;
case SINCE:
case EXCEPTION:
case VERSION:
case UNKNOWN:
case AUTHOR:
case SEE:
case PARAM:
case RETURN:
case THROWS:
case SERIAL:
break;
default:
throw new RuntimeException("unknown index " + ix + " for tag: " + kind);
}
}
if (version != null) {
version[0] = statusVer;
}
return result.get();
}
private String getStatusVersion(Tag tag) {
String text = tag.text();
if (text != null && text.length() > 0) {
// Extract version string
int start = -1;
int i = 0;
for (; i < text.length(); i++) {
char ch = text.charAt(i);
if (ch == '.' || (ch >= '0' && ch <= '9')) {
if (start == -1) {
start = i;
}
} else if (start != -1) {
break;
}
}
if (start != -1) {
return text.substring(start, i);
}
}
return "";
}
private static final int UNKNOWN = -1;
private static final int INTERNAL = 0;
private static final int DRAFT = 1;
private static final int STABLE = 2;
private static final int SINCE = 3;
private static final int DEPRECATED = 4;
private static final int AUTHOR = 5;
private static final int SEE = 6;
private static final int VERSION = 7;
private static final int PARAM = 8;
private static final int RETURN = 9;
private static final int THROWS = 10;
private static final int OBSOLETE = 11;
private static final int EXCEPTION = 12;
private static final int SERIAL = 13;
private static int tagKindIndex(String kind) {
final String[] tagKinds = {
"@internal", "@draft", "@stable", "@since", "@deprecated", "@author", "@see", "@version",
"@param", "@return", "@throws", "@obsolete", "@exception", "@serial"
};
for (int i = 0; i < tagKinds.length; ++i) {
if (kind.equals(tagKinds[i])) {
return i;
}
}
return UNKNOWN;
}
}

383
icu4j/tools/build/src/main/java/com/ibm/icu/dev/tool/docs/JavadocHelper.java Normal file
View file

@ -0,0 +1,383 @@
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/**
*******************************************************************************
* Copyright (C) 2002-2010, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
*/
/**
* This is a tool to check the tags on ICU4J files. In particular, we're looking for:
*
* - methods that have no tags
* - custom tags: @draft, @stable, @internal?
* - standard tags: @since, @deprecated
*
* Syntax of tags:
* '@draft ICU X.X.X'
* '@stable ICU X.X.X'
* '@internal'
* '@since (don't use)'
* '@obsolete ICU X.X.X'
* '@deprecated to be removed in ICU X.X. [Use ...]'
*
* 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]
*/
package com.ibm.icu.dev.tool.docs;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.Modifier;
import javax.lang.model.util.Elements;
import com.sun.source.doctree.BlockTagTree;
import com.sun.source.doctree.InlineTagTree;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.DocTree;
import com.sun.source.tree.CompilationUnitTree;
import com.sun.source.util.DocTrees;
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}
* and {@code ENUM}.
* If what you need is CLASS only, use {@link #isKindClassExact(Element element)}@
*/
static boolean isKindClass(Element element) {
return element.getKind().isClass();
}
static boolean isKindClassExact(Element element) {
return element.getKind() == ElementKind.CLASS;
}
/** The standard {@code isInterface()} test returns true for both {@code INTERFACE}
* and {@code ANNOTATION_TYPE}.
* If what you need is INTERFACE only, use {@link #isKindInterfaceExact(Element element)}@
*/
static boolean isKindInterface(Element element) {
return element.getKind().isInterface();
}
static boolean isKindInterfaceExact(Element element) {
return element.getKind() == ElementKind.INTERFACE;
}
static boolean isKindConstructor(Element element) {
return element.getKind() == ElementKind.CONSTRUCTOR;
}
static boolean isKindMethod(Element element) {
return element.getKind() == ElementKind.METHOD;
}
static boolean isKindEnum(Element element) {
return element.getKind() == ElementKind.ENUM;
}
/** The standard {@code isField()} test returns true for both {@code FIELD}
* and {@code ENUM_CONSTANT}.
* If what you need is FIELD only, use {@link #isKindFieldExact(Element element)}@
*/
static boolean isKindField(Element element) {
return element.getKind().isField();
}
static boolean isKindFieldExact(Element element) {
return element.getKind() == ElementKind.FIELD;
}
static boolean isKindEnumConstant(Element element) {
return element.getKind() == ElementKind.ENUM_CONSTANT;
}
static boolean isKindPackage(Element element) {
return element.getKind() == ElementKind.PACKAGE;
}
static boolean isKindClassOrInterface(Element element) {
ElementKind kind = element.getKind();
return kind.isClass() || kind.isInterface();
}
// Visibility
static boolean isPublic(Element element) {
return element.getModifiers().contains(Modifier.PUBLIC);
}
static boolean isProtected(Element element) {
return element.getModifiers().contains(Modifier.PROTECTED);
}
static boolean isPrivate(Element element) {
return element.getModifiers().contains(Modifier.PRIVATE);
}
static boolean isAbstract(Element element) {
return element.getModifiers().contains(Modifier.ABSTRACT);
}
static boolean isStatic(Element element) {
return element.getModifiers().contains(Modifier.STATIC);
}
static boolean isFinal(Element element) {
return element.getModifiers().contains(Modifier.FINAL);
}
static boolean isDefault(Element element) {
return element.getModifiers().contains(Modifier.DEFAULT);
}
static boolean isSynchronized(Element element) {
return element.getModifiers().contains(Modifier.SYNCHRONIZED);
}
static boolean isVisibilityPackage(Element element) {
Set<Modifier> modifiers = element.getModifiers();
if (modifiers.contains(Modifier.PUBLIC)
|| modifiers.contains(Modifier.PROTECTED)
|| modifiers.contains(Modifier.PRIVATE)) {
return false;
}
return true;
}
static boolean isSynthetic(Elements elements, Element element) {
return elements.getOrigin(element) == Elements.Origin.SYNTHETIC;
}
static String flatSignature(Element element) {
return element == null ? "null" : element.toString().replace("java.lang.", "");
}
/** Returns the location of the element, in the /absolute/path/to/File.java[1234] form. */
static String position(Elements el, DocTrees docTrees, Element element) {
TreePath path = docTrees.getPath(element);
if (path == null) {
// I've seen this happening for values() and valueOf(), which are created by the compiler
// in enums. So they "exist", but there is no location in the file for them.
// After ignoring values() and valueOf() (we can't tag them anyway), this error never happens.
// But let's keep it here, for future safety. Who knows what else the compiler will start creating.
return "<unknown_location>:<unknown_line>";
}
CompilationUnitTree cu = path.getCompilationUnit();
long startPos = docTrees.getSourcePositions().getStartPosition(cu, docTrees.getTree(element));
return cu.getSourceFile().getName() + ":" + cu.getLineMap().getLineNumber(startPos);
}
static String position(Elements el, DocTrees docTrees, Element element, DocTree tag) {
// I didn't manage to get the location of a tag, but at least we can show the location
// of the parent element.
return position(el, docTrees, element);
}
static List<BlockTagTree> getBlockTags(DocTrees docTrees, Element element) {
List<BlockTagTree> result = new ArrayList<>();
DocCommentTree dct = docTrees.getDocCommentTree(element);
if (dct == null) {
return result;
}
List<? extends DocTree> blockTags = dct.getBlockTags();
if (blockTags == null) {
return result;
}
for (DocTree btags : blockTags) {
result.add((BlockTagTree) btags);
}
return result;
}
static List<InlineTagTree> getInnerTags(DocTrees docTrees, Element element) {
List<InlineTagTree> result = new ArrayList<>();
DocCommentTree dct = docTrees.getDocCommentTree(element);
if (dct == null) {
return result;
}
List<? extends DocTree> fullBody = dct.getFullBody();
if (fullBody == null) {
return result;
}
for (DocTree tag : fullBody) {
if (tag instanceof InlineTagTree) {
result.add((InlineTagTree) tag);
}
}
return result;
}
static String toText(DocTree dt) {
String result = dt == null ? "<null>" : dt.toString();
if (result.startsWith("{@") && result.endsWith("}")) {
// Remove the `{` and `}` from an inline tag (`{@foo some text here}`)
result = result.substring(1, result.length() - 1);
}
// Remove the `@foo` part of the tag, applies to the block tags, and the inline tag cleaned above
if (result.startsWith("@")) {
result = result.replaceFirst("^@[a-zA-Z0-9_]+\\s+", "");
}
return result;
}
// Sigh. Javadoc doesn't indicate when the compiler generates
// the values and valueOf enum methods. The position of the
// method for these is not always the same as the position of
// the class, though it often is, so we can't use that.
static boolean isIgnoredEnumMethod(Element doc) {
if (JavadocHelper.isKindMethod(doc) && JavadocHelper.isKindEnum(doc.getEnclosingElement())) {
String name = doc.getSimpleName().toString();
// assume we don't have enums that overload these method names.
return "values".equals(name) || "valueOf".equals(name);
}
return false;
}
// Doclet options
static class GatherApiDataOption implements Doclet.Option {
final int length;
final String name;
final String paramName;
final String description;
String strValue = null;
Boolean boolValue = null;
GatherApiDataOption(int length, String name, String description) {
this(length, name, null, description); // no parameter
}
GatherApiDataOption(int length, String name, String paramName, String description) {
this.length = length;
this.name = name;
this.paramName = paramName;
this.description = description;
}
@Override
public int getArgumentCount() {
return length;
}
@Override
public String getDescription() {
return description;
}
@Override
public Doclet.Option.Kind getKind() {
return Doclet.Option.Kind.STANDARD;
}
@Override
public List<String> getNames() {
return List.of(name);
}
@Override
public String getParameters() {
return this.paramName;
}
@Override
public boolean process(String option, List<String> arguments) {
if (!option.equals(name)) {
return false;
}
if (length == 0) {
boolValue = true;
return true;
}
if (arguments == null || arguments.size() < 1) {
return false;
}
strValue = arguments.get(0);
return true;
}
public String getName() {
return name;
}
public Boolean getBooleanValue(Boolean fallbackValue) {
return boolValue != null ? boolValue : fallbackValue;
}
public String getStringValue(String fallbackValue) {
return strValue != null ? strValue : fallbackValue;
}
}
// Known taglets, standard or ICU extensions
static enum TagKind {
UNKNOWN("<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("<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;
}
}
}