From: Jochen Sprickerhof Date: Mon, 17 Jun 2024 23:13:33 +0200 Subject: Drop (Resource)Doclet.java (does not compile with JDK 17) --- src/tools/org/h2/build/Build.java | 40 -- src/tools/org/h2/build/doclet/Doclet.java | 590 ---------------------- src/tools/org/h2/build/doclet/ResourceDoclet.java | 132 ----- 3 files changed, 762 deletions(-) delete mode 100644 src/tools/org/h2/build/doclet/Doclet.java delete mode 100644 src/tools/org/h2/build/doclet/ResourceDoclet.java diff --git a/src/tools/org/h2/build/Build.java b/src/tools/org/h2/build/Build.java index 7b9262d..89f2ee5 100644 --- a/src/tools/org/h2/build/Build.java +++ b/src/tools/org/h2/build/Build.java @@ -627,19 +627,6 @@ public void jarSmall() { */ @Description(summary = "Create the API Javadocs (incl. JDBC API and tools).") public void javadoc() { - compileTools(); - delete("docs"); - mkdir("docs/javadoc"); - javadoc("-sourcepath", "src/main", "org.h2.jdbc", "org.h2.jdbcx", - "org.h2.tools", "org.h2.api", "org.h2.engine", "org.h2.fulltext", - "-classpath", - "ext/lucene-core-5.5.5.jar" + - File.pathSeparator + "ext/lucene-analyzers-common-5.5.5.jar" + - File.pathSeparator + "ext/lucene-queryparser-5.5.5.jar" + - File.pathSeparator + "ext/jts-core-1.15.0.jar", - "-docletpath", "bin" + File.pathSeparator + "temp", - "-doclet", "org.h2.build.doclet.Doclet"); - copy("docs/javadoc", files("src/docsrc/javadoc"), "src/docsrc/javadoc"); } /** @@ -690,25 +677,6 @@ public void javadocImpl() { System.setProperty("h2.interfacesOnly", "false"); System.setProperty("h2.javadocDestDir", "docs/javadocImpl"); - javadoc("-sourcepath", "src/main" + - File.pathSeparator + "src/test" + - File.pathSeparator + "src/tools", - "-classpath", javaToolsJar + - File.pathSeparator + "ext/slf4j-api-1.6.0.jar" + - File.pathSeparator + "ext/servlet-api-3.1.0.jar" + - File.pathSeparator + "ext/lucene-core-5.5.5.jar" + - File.pathSeparator + "ext/lucene-analyzers-common-5.5.5.jar" + - File.pathSeparator + "ext/lucene-queryparser-5.5.5.jar" + - File.pathSeparator + "ext/org.osgi.core-4.2.0.jar" + - File.pathSeparator + "ext/org.osgi.enterprise-4.2.0.jar" + - File.pathSeparator + "ext/jts-core-1.15.0.jar" + - File.pathSeparator + "ext/asm-7.0.jar" + - File.pathSeparator + "ext/junit-4.12.jar", - "-subpackages", "org.h2", - "-package", - "-docletpath", "bin" + File.pathSeparator + "temp", - "-doclet", "org.h2.build.doclet.Doclet"); - copy("docs/javadocImpl", files("src/docsrc/javadoc"), "src/docsrc/javadoc"); } private static void manifest(String path) { @@ -900,14 +868,6 @@ public void offline() { private void resources(boolean clientOnly, boolean basicOnly) { if (!clientOnly) { java("org.h2.build.doc.GenerateHelp", null); - javadoc("-sourcepath", "src/main", "org.h2.tools", "org.h2.jmx", - "-classpath", - "ext/lucene-core-5.5.5.jar" + - File.pathSeparator + "ext/lucene-analyzers-common-5.5.5.jar" + - File.pathSeparator + "ext/lucene-queryparser-5.5.5.jar" + - File.pathSeparator + "ext/jts-core-1.15.0.jar", - "-docletpath", "bin" + File.pathSeparator + "temp", - "-doclet", "org.h2.build.doclet.ResourceDoclet"); } FileList files = files("src/main"). exclude("*.MF"). diff --git a/src/tools/org/h2/build/doclet/Doclet.java b/src/tools/org/h2/build/doclet/Doclet.java deleted file mode 100644 index c0141ce..0000000 --- a/src/tools/org/h2/build/doclet/Doclet.java +++ /dev/null @@ -1,590 +0,0 @@ -/* - * Copyright 2004-2019 H2 Group. Multiple-Licensed under the MPL 2.0, - * and the EPL 1.0 (http://h2database.com/html/license.html). - * Initial Developer: H2 Group - */ -package org.h2.build.doclet; - -import java.io.BufferedWriter; -import java.io.File; -import java.io.FileWriter; -import java.io.IOException; -import java.io.PrintWriter; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Comparator; -import java.util.HashSet; -import org.h2.util.StringUtils; -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.MethodDoc; -import com.sun.javadoc.ParamTag; -import com.sun.javadoc.Parameter; -import com.sun.javadoc.RootDoc; -import com.sun.javadoc.Tag; -import com.sun.javadoc.ThrowsTag; -import com.sun.javadoc.Type; - -/** - * This class is a custom doclet implementation to generate the - * Javadoc for this product. - */ -public class Doclet { - - private static final boolean INTERFACES_ONLY = Boolean - .getBoolean("h2.interfacesOnly"); - private String destDir = System.getProperty("h2.javadocDestDir", - "docs/javadoc"); - private int errorCount; - private final HashSet errors = new HashSet<>(); - - /** - * This method is called by the javadoc framework and is required for all - * doclets. - * - * @param root the root - * @return true if successful - */ - public static boolean start(RootDoc root) throws IOException { - return new Doclet().startDoc(root); - } - - private boolean startDoc(RootDoc root) throws IOException { - ClassDoc[] classes = root.classes(); - String[][] options = root.options(); - for (String[] op : options) { - if (op[0].equals("destdir")) { - destDir = op[1]; - } - } - for (ClassDoc clazz : classes) { - processClass(clazz); - } - if (errorCount > 0) { - throw new IOException("FAILED: " + errorCount + " errors found"); - } - return true; - } - - private static String getClass(ClassDoc clazz) { - String name = clazz.name(); - if (clazz.qualifiedName().indexOf(".jdbc.") > 0 && name.startsWith("Jdbc")) { - return name.substring(4); - } - return name; - } - - private void processClass(ClassDoc clazz) throws IOException { - String packageName = clazz.containingPackage().name(); - String dir = destDir + "/" + packageName.replace('.', '/'); - (new File(dir)).mkdirs(); - String fileName = dir + "/" + clazz.name() + ".html"; - String className = getClass(clazz); - FileWriter out = new FileWriter(fileName); - PrintWriter writer = new PrintWriter(new BufferedWriter(out)); - writer.println(""); - String language = "en"; - writer.println(""); - writer.println("" + - ""); - writer.println(className); - writer.println("" + - ""); - writer.println(""); - writer.println(""); - writer.println("" + - "" + - "
" + - "
"); - writer.println("

" + className + "

"); - writer.println(formatText(clazz.commentText()) + "

"); - - // methods - ConstructorDoc[] constructors = clazz.constructors(); - MethodDoc[] methods = clazz.methods(); - ExecutableMemberDoc[] constructorsMethods = - new ExecutableMemberDoc[constructors.length - + methods.length]; - System.arraycopy(constructors, 0, constructorsMethods, 0, - constructors.length); - System.arraycopy(methods, 0, constructorsMethods, constructors.length, - methods.length); - Arrays.sort(constructorsMethods, new Comparator() { - @Override - public int compare(ExecutableMemberDoc a, ExecutableMemberDoc b) { - // sort static method before non-static methods - if (a.isStatic() != b.isStatic()) { - return a.isStatic() ? -1 : 1; - } - return a.name().compareTo(b.name()); - } - }); -// -// -// Arrays.sort(methods, new Comparator() { -// public int compare(MethodDoc a, MethodDoc b) { -// // sort static method before non-static methods -// if (a.isStatic() != b.isStatic()) { -// return a.isStatic() ? -1 : 1; -// } -// return a.name().compareTo(b.name()); -// } -// }); - ArrayList signatures = new ArrayList<>(); - boolean hasMethods = false; - int id = 0; - for (int i = 0; i < constructorsMethods.length; i++) { - ExecutableMemberDoc method = constructorsMethods[i]; - String name = method.name(); - if (skipMethod(method)) { - continue; - } - if (!hasMethods) { - writer.println("" + - "" + - ""); - hasMethods = true; - } - String type = getTypeName(method.isStatic(), false, - getReturnType(method)); - writer.println(""); - writer.println(""); - writer.println(""); - writer.println(""); - id++; - } - if (hasMethods) { - writer.println("
Methods
" + type + - ""); - Parameter[] params = method.parameters(); - StringBuilder buff = new StringBuilder(); - StringBuilder buffSignature = new StringBuilder(name); - buff.append('('); - for (int j = 0; j < params.length; j++) { - if (j > 0) { - buff.append(", "); - } - buffSignature.append('_'); - Parameter param = params[j]; - boolean isVarArgs = method.isVarArgs() && j == params.length - 1; - String typeName = getTypeName(false, isVarArgs, param.type()); - buff.append(typeName); - buffSignature.append(StringUtils.replaceAll(typeName, "[]", "-")); - buff.append(' '); - buff.append(param.name()); - } - buff.append(')'); - if (isDeprecated(method)) { - name = "" + name + ""; - } - String signature = buffSignature.toString(); - while (signatures.size() < i) { - signatures.add(null); - } - signatures.add(i, signature); - writer.println("" + - name + "" + buff.toString()); - String firstSentence = getFirstSentence(method.firstSentenceTags()); - if (firstSentence != null) { - writer.println("
" + - formatText(firstSentence) + "
"); - } - writer.println("
" + - type + ""); - writeMethodDetails(writer, clazz, method, signature); - writer.println("
"); - } - - // field overview - FieldDoc[] fields = clazz.fields(); - if (clazz.interfaces().length > 0) { - fields = clazz.interfaces()[0].fields(); - } - Arrays.sort(fields, new Comparator() { - @Override - public int compare(FieldDoc a, FieldDoc b) { - return a.name().compareTo(b.name()); - } - }); - int fieldId = 0; - for (FieldDoc field : fields) { - if (skipField(clazz, field)) { - continue; - } - String name = field.name(); - String text = field.commentText(); - if (text == null || text.trim().length() == 0) { - addError("Undocumented field (" + - getLink(clazz, field.position().line()) + ") " + name); - } - if (text != null && text.startsWith("INTERNAL")) { - continue; - } - if (fieldId == 0) { - writer.println("
"); - } - String type = getTypeName(true, false, field.type()); - writer.println(""); - fieldId++; - } - if (fieldId > 0) { - writer.println("
Fields
" + type + - ""); - String constant = field.constantValueExpression(); - - // add a link (a name) if there is a tag - String link = getFieldLink(text, constant, clazz, name); - writer.print("" + name + ""); - if (constant == null) { - writer.println(); - } else { - writer.println(" = " + constant); - } - writer.println("
"); - } - - // field details - Arrays.sort(fields, new Comparator() { - @Override - public int compare(FieldDoc a, FieldDoc b) { - String ca = a.constantValueExpression(); - if (ca == null) { - ca = a.name(); - } - String cb = b.constantValueExpression(); - if (cb == null) { - cb = b.name(); - } - return ca.compareTo(cb); - } - }); - for (FieldDoc field : fields) { - writeFieldDetails(writer, clazz, field); - } - - writer.println("
"); - writer.close(); - out.close(); - } - - private void writeFieldDetails(PrintWriter writer, ClassDoc clazz, - FieldDoc field) { - if (skipField(clazz, field)) { - return; - } - String text = field.commentText(); - if (text.startsWith("INTERNAL")) { - return; - } - String name = field.name(); - String constant = field.constantValueExpression(); - String link = getFieldLink(text, constant, clazz, name); - writer.println("

" + - name); - if (constant == null) { - writer.println(); - } else { - writer.println(" = " + constant); - } - writer.println("

"); - writer.println("
" + formatText(text) + "
"); - writer.println("
"); - } - - private void writeMethodDetails(PrintWriter writer, ClassDoc clazz, - ExecutableMemberDoc method, String signature) { - String name = method.name(); - if (skipMethod(method)) { - return; - } - Parameter[] params = method.parameters(); - StringBuilder builder = new StringBuilder(); - builder.append('('); - for (int i = 0, l = params.length; i < l; i++) { - if (i > 0) { - builder.append(", "); - } - boolean isVarArgs = method.isVarArgs() && i == params.length - 1; - Parameter p = params[i]; - builder.append(getTypeName(false, isVarArgs, p.type())); - builder.append(' '); - builder.append(p.name()); - } - builder.append(')'); - ClassDoc[] exceptions = method.thrownExceptions(); - if (exceptions.length > 0) { - builder.append(" throws "); - for (int i = 0, l = exceptions.length; i < l; i++) { - if (i > 0) { - builder.append(", "); - } - builder.append(exceptions[i].typeName()); - } - } - if (isDeprecated(method)) { - name = "" + name + ""; - } - writer.println("" + - name + "" + builder.toString()); - boolean hasComment = method.commentText() != null && - method.commentText().trim().length() != 0; - writer.println("
" + - formatText(method.commentText()) + "
"); - ParamTag[] paramTags = method.paramTags(); - ThrowsTag[] throwsTags = method.throwsTags(); - boolean hasThrowsTag = throwsTags != null && throwsTags.length > 0; - if (paramTags.length != params.length) { - if (hasComment && !method.commentText().startsWith("[")) { - // [Not supported] and such are not problematic - addError("Undocumented parameter(s) (" + - getLink(clazz, method.position().line()) + ") " + - name + " documented: " + paramTags.length + - " params: "+ params.length); - } - } - for (int j = 0; j < paramTags.length; j++) { - String paramName = paramTags[j].parameterName(); - String comment = paramTags[j].parameterComment(); - if (comment.trim().length() == 0) { - addError("Undocumented parameter (" + - getLink(clazz, method.position().line()) + ") " + - name + " " + paramName); - } - String p = paramName + " - " + comment; - if (j == 0) { - writer.println("
Parameters:
"); - } - writer.println("
" + p + "
"); - } - Tag[] returnTags = method.tags("return"); - Type returnType = getReturnType(method); - if (returnTags != null && returnTags.length > 0) { - writer.println("
Returns:
"); - String returnComment = returnTags[0].text(); - if (returnComment.trim().length() == 0) { - addError("Undocumented return value (" + - getLink(clazz, method.position().line()) + ") " + name); - } - writer.println("
" + returnComment + "
"); - } else if (returnType != null && !returnType.toString().equals("void")) { - if (hasComment && !method.commentText().startsWith("[") && - !hasThrowsTag) { - // [Not supported] and such are not problematic - // also not problematic are methods that always throw an - // exception - addError("Undocumented return value (" - + getLink(clazz, method.position().line()) + ") " - + name + " " + getReturnType(method)); - } - } - if (hasThrowsTag) { - writer.println("
Throws:
"); - for (ThrowsTag tag : throwsTags) { - String p = tag.exceptionName(); - String c = tag.exceptionComment(); - if (c.length() > 0) { - p += " - " + c; - } - writer.println("
" + p + "
"); - } - } - } - - private static String getLink(ClassDoc clazz, int line) { - String c = clazz.name(); - int x = c.lastIndexOf('.'); - if (x >= 0) { - c = c.substring(0, x); - } - return c + ".java:" + line; - } - - private String getFieldLink(String text, String constant, ClassDoc clazz, - String name) { - String link = constant != null ? constant : name.toLowerCase(); - int linkStart = text.indexOf(""); - if (linkStart >= 0) { - int linkEnd = text.indexOf("", linkStart); - link = text.substring(linkStart + "".length(), linkEnd); - if (constant != null && !constant.equals(link)) { - System.out.println("Wrong code tag? " + clazz.name() + "." + - name + - " code: " + link + " constant: " + constant); - errorCount++; - } - } - if (link.startsWith("\"")) { - link = name; - } else if (Character.isDigit(link.charAt(0))) { - link = "c" + link; - } - return link; - } - - private static String formatText(String text) { - if (text == null) { - return text; - } - text = StringUtils.replaceAll(text, "\n ", ""); - return text; - } - - private static boolean skipField(ClassDoc clazz, FieldDoc field) { - if (field.isPrivate() || field.containingClass() != clazz) { - return true; - } - return false; - } - - private boolean skipMethod(ExecutableMemberDoc method) { - ClassDoc clazz = method.containingClass(); - boolean isAbstract = method instanceof MethodDoc - && ((MethodDoc) method).isAbstract(); - boolean isInterface = clazz.isInterface() - || (clazz.isAbstract() && isAbstract); - if (INTERFACES_ONLY && !isInterface) { - return true; - } - String name = method.name(); - if (method.isPrivate() || name.equals("finalize")) { - return true; - } - if (method.isConstructor() - && method.getRawCommentText().trim().length() == 0) { - return true; - } - if (method.getRawCommentText().trim() - .startsWith("@deprecated INTERNAL")) { - return true; - } - String firstSentence = getFirstSentence(method.firstSentenceTags()); - String raw = method.getRawCommentText(); - if (firstSentence != null && firstSentence.startsWith("INTERNAL")) { - return true; - } - if ((firstSentence == null || firstSentence.trim().length() == 0) - && raw.indexOf("{@inheritDoc}") < 0) { - if (!doesOverride(method)) { - boolean setterOrGetter = name.startsWith("set") - && method.parameters().length == 1; - setterOrGetter |= name.startsWith("get") - && method.parameters().length == 0; - Type returnType = getReturnType(method); - setterOrGetter |= name.startsWith("is") - && method.parameters().length == 0 - && returnType != null - && returnType.toString().equals("boolean"); - boolean enumValueMethod = name.equals("values") || name.equals("valueOf"); - if (!setterOrGetter && !enumValueMethod) { - addError("Undocumented method " + " (" - + getLink(clazz, method.position().line()) + ") " - + clazz + "." + name + " " + raw); - return true; - } - } - } - return false; - } - - private static Type getReturnType(ExecutableMemberDoc method) { - if (method instanceof MethodDoc) { - MethodDoc m = (MethodDoc) method; - return m.returnType(); - } - return null; - } - - private void addError(String s) { - if (errors.add(s)) { - System.out.println(s); - errorCount++; - } - } - - private boolean doesOverride(ExecutableMemberDoc method) { - if (method.isConstructor()) { - return true; - } - ClassDoc clazz = method.containingClass(); - int parameterCount = method.parameters().length; - return foundMethod(clazz, false, method.name(), parameterCount); - } - - private boolean foundMethod(ClassDoc clazz, boolean include, - String methodName, int parameterCount) { - if (include) { - for (MethodDoc m : clazz.methods()) { - if (m.name().equals(methodName) - && m.parameters().length == parameterCount) { - return true; - } - } - } - for (ClassDoc doc : clazz.interfaces()) { - if (foundMethod(doc, true, methodName, parameterCount)) { - return true; - } - } - clazz = clazz.superclass(); - return clazz != null - && foundMethod(clazz, true, methodName, parameterCount); - } - - private static String getFirstSentence(Tag[] tags) { - String firstSentence = null; - if (tags.length > 0) { - Tag first = tags[0]; - firstSentence = first.text(); - } - return firstSentence; - } - - private static String getTypeName(boolean isStatic, boolean isVarArgs, - Type type) { - if (type == null) { - return ""; - } - String s = type.typeName() + type.dimension(); - if (isVarArgs) { - // remove the last "[]" and add "..." instead - s = s.substring(0, s.length() - 2) + "..."; - } - if (isStatic) { - s = "static " + s; - } - return s; - } - - private static boolean isDeprecated(ExecutableMemberDoc method) { - for (Tag t : method.tags()) { - if (t.kind().equals("@deprecated")) { - return true; - } - } - return false; - } - - /** - * Get the language version this doclet supports. - * - * @return the language version - */ - public static LanguageVersion languageVersion() { - // otherwise, isVarArgs always returns false - // (which sounds like a bug but is a feature :-) - return LanguageVersion.JAVA_1_5; - } - -} diff --git a/src/tools/org/h2/build/doclet/ResourceDoclet.java b/src/tools/org/h2/build/doclet/ResourceDoclet.java deleted file mode 100644 index 3b3a996..0000000 --- a/src/tools/org/h2/build/doclet/ResourceDoclet.java +++ /dev/null @@ -1,132 +0,0 @@ -/* - * Copyright 2004-2019 H2 Group. Multiple-Licensed under the MPL 2.0, - * and the EPL 1.0 (http://h2database.com/html/license.html). - * Initial Developer: H2 Group - */ -package org.h2.build.doclet; - -import java.io.IOException; -import org.h2.build.doc.XMLParser; -import org.h2.build.indexer.HtmlConverter; -import org.h2.util.SortedProperties; -import com.sun.javadoc.ClassDoc; -import com.sun.javadoc.Doc; -import com.sun.javadoc.MethodDoc; -import com.sun.javadoc.RootDoc; -import com.sun.javadoc.Tag; - -/** - * This custom doclet generates resources from javadoc comments. - * Only comments that contain 'at resource' are included. - * Only class level and method level comments are supported. - */ -public class ResourceDoclet { - - private String destFile = System.getProperty("h2.javadocResourceFile", - "src/main/org/h2/res/javadoc.properties"); - - private final SortedProperties resources = new SortedProperties(); - - /** - * This method is called by the javadoc framework and is required for all - * doclets. - * - * @param root the root - * @return true if successful - */ - public static boolean start(RootDoc root) throws IOException { - return new ResourceDoclet().startDoc(root); - } - - private boolean startDoc(RootDoc root) throws IOException { - ClassDoc[] classes = root.classes(); - String[][] options = root.options(); - for (String[] op : options) { - if (op[0].equals("dest")) { - destFile = op[1]; - } - } - for (ClassDoc clazz : classes) { - processClass(clazz); - } - resources.store(destFile); - return true; - } - - private void processClass(ClassDoc clazz) { - String packageName = clazz.containingPackage().name(); - String className = clazz.name(); - addResource(packageName + "." + className, clazz); - - for (MethodDoc method : clazz.methods()) { - String name = method.name(); - addResource(packageName + "." + className + "." + name, method); - } - } - - - private void addResource(String key, Doc doc) { - if (!isResource(doc)) { - return; - } - String xhtml = doc.commentText(); - XMLParser p = new XMLParser(xhtml); - StringBuilder buff = new StringBuilder(); - int column = 0; - int firstColumnSize = 0; - boolean inColumn = false; - while (p.hasNext()) { - String s; - switch (p.next()) { - case XMLParser.END_ELEMENT: - s = p.getName(); - if ("p".equals(s) || "tr".equals(s) || "br".equals(s)) { - buff.append('\n'); - } - break; - case XMLParser.START_ELEMENT: - s = p.getName(); - if ("table".equals(s)) { - buff.append('\n'); - } else if ("tr".equals(s)) { - column = 0; - } else if ("td".equals(s)) { - inColumn = true; - column++; - if (column == 2) { - buff.append('\t'); - } - } - break; - case XMLParser.CHARACTERS: - s = HtmlConverter.convertHtmlToString(p.getText().trim()); - if (inColumn && column == 1) { - firstColumnSize = Math.max(s.length(), firstColumnSize); - } - buff.append(s); - break; - } - } - for (int i = 0; i < buff.length(); i++) { - if (buff.charAt(i) == '\t') { - buff.deleteCharAt(i); - int length = i - buff.lastIndexOf("\n", i - 1); - for (int k = length; k < firstColumnSize + 3; k++) { - buff.insert(i, ' '); - } - } - } - String text = buff.toString().trim(); - resources.setProperty(key, text); - } - - private static boolean isResource(Doc doc) { - for (Tag t : doc.tags()) { - if (t.kind().equals("@h2.resource")) { - return true; - } - } - return false; - } - -}