1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/test/tools/javadoc/lib/Tester.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,337 @@
1.4 +/*
1.5 + * Copyright 2003-2004 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation.
1.11 + *
1.12 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.13 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.14 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.15 + * version 2 for more details (a copy is included in the LICENSE file that
1.16 + * accompanied this code).
1.17 + *
1.18 + * You should have received a copy of the GNU General Public License version
1.19 + * 2 along with this work; if not, write to the Free Software Foundation,
1.20 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.21 + *
1.22 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.23 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.24 + * have any questions.
1.25 + */
1.26 +
1.27 +/*
1.28 + * A utility used to invoke and test the javadoc tool.
1.29 + *
1.30 + * @author Scott Seligman
1.31 + */
1.32 +
1.33 +
1.34 +import java.io.*;
1.35 +import java.util.*;
1.36 +import com.sun.javadoc.*;
1.37 +
1.38 +
1.39 +public class Tester {
1.40 +
1.41 + protected final String TEST_SRC = System.getProperty("test.src", ".");
1.42 + protected final String TEST_CLASSES = System.getProperty("test.classes",
1.43 + ".");
1.44 + private final String DEFAULT_ARGS[] = {
1.45 + "-source", "1.5",
1.46 + "-sourcepath", TEST_SRC,
1.47 + };
1.48 +
1.49 + private final File outputFile = new File(TEST_CLASSES, "testrun.out");
1.50 + private final File expectedOutputFile = new File(TEST_SRC, "expected.out");
1.51 +// private final File bootstrapMarkerFile = new File("bootstrap");
1.52 +
1.53 + // True if we should "set expectations" by writing the expected output file
1.54 + // rather than reading it and comparing.
1.55 +// private final boolean bootstrap = bootstrapMarkerFile.isFile();
1.56 +
1.57 + private String docletName;
1.58 + private String[] args;
1.59 + private Writer out = null;
1.60 +
1.61 +
1.62 + /*
1.63 + * Individual tests can extend this to create generics-aware doclets.
1.64 + */
1.65 + public static abstract class Doclet extends com.sun.javadoc.Doclet {
1.66 + public static LanguageVersion languageVersion() {
1.67 + return LanguageVersion.JAVA_1_5;
1.68 + }
1.69 + }
1.70 +
1.71 +
1.72 + public Tester(String docletName) {
1.73 + this(docletName, new String[0]);
1.74 + }
1.75 +
1.76 + public Tester(String docletName, String... additionalArgs) {
1.77 + this.docletName = docletName;
1.78 +
1.79 + int len = DEFAULT_ARGS.length + additionalArgs.length;
1.80 + args = new String[len];
1.81 + System.arraycopy(DEFAULT_ARGS, 0, args, 0, DEFAULT_ARGS.length);
1.82 + System.arraycopy(additionalArgs, 0, args, DEFAULT_ARGS.length,
1.83 + additionalArgs.length);
1.84 +
1.85 + try {
1.86 + out = new BufferedWriter(new FileWriter(outputFile));
1.87 + } catch (IOException e) {
1.88 + throw new Error("Could not open output file " + outputFile);
1.89 + }
1.90 + }
1.91 +
1.92 + public void run() throws IOException {
1.93 + try {
1.94 + if (com.sun.tools.javadoc.Main.execute("javadoc",
1.95 + docletName, args) != 0) {
1.96 + throw new Error("Javadoc errors encountered.");
1.97 + }
1.98 + System.out.println("--> Output written to " + outputFile);
1.99 + } finally {
1.100 + out.close();
1.101 + }
1.102 + }
1.103 +
1.104 + /*
1.105 + * Compare output of test run to expected output.
1.106 + * Throw an Error if they don't match.
1.107 + */
1.108 + public void verify() throws IOException {
1.109 + BufferedReader thisRun =
1.110 + new BufferedReader(new FileReader(outputFile));
1.111 + BufferedReader expected =
1.112 + new BufferedReader(new FileReader(expectedOutputFile));
1.113 +
1.114 + for (int lineNum = 1; true; lineNum++) {
1.115 + String line1 = thisRun.readLine();
1.116 + String line2 = expected.readLine();
1.117 + if (line1 == null && line2 == null) {
1.118 + return; // EOF with all lines matching
1.119 + }
1.120 + if (line1 == null || !line1.equals(line2)) {
1.121 + throw new Error(outputFile + ":" + lineNum +
1.122 + ": output doesn't match");
1.123 + }
1.124 + }
1.125 + }
1.126 +
1.127 +
1.128 + public void println(Object o) throws IOException {
1.129 + prln(0, o);
1.130 + }
1.131 +
1.132 + public void println() throws IOException {
1.133 + prln();
1.134 + }
1.135 +
1.136 + public void printPackage(PackageDoc p) throws IOException {
1.137 + prPackage(0, p);
1.138 + }
1.139 +
1.140 + public void printClass(ClassDoc cd) throws IOException {
1.141 + if (cd.isAnnotationType())
1.142 + printAnnotationType((AnnotationTypeDoc)cd);
1.143 + else
1.144 + prClass(0, cd);
1.145 + }
1.146 +
1.147 + public void printAnnotationType(AnnotationTypeDoc at) throws IOException {
1.148 + prAnnotationType(0, at);
1.149 + }
1.150 +
1.151 + public void printField(FieldDoc f) throws IOException {
1.152 + prField(0, f);
1.153 + }
1.154 +
1.155 + public void printParameter(Parameter p) throws IOException {
1.156 + prParameter(0, p);
1.157 + }
1.158 +
1.159 + public void printMethod(MethodDoc m) throws IOException {
1.160 + prln(0, "method " + m);
1.161 + prMethod(0, m);
1.162 + }
1.163 +
1.164 + public void printAnnotationTypeElement(AnnotationTypeElementDoc e)
1.165 + throws IOException {
1.166 + prln(0, "element " + e);
1.167 + prMethod(0, e);
1.168 + }
1.169 +
1.170 + public void printConstructor(ConstructorDoc c) throws IOException {
1.171 + prln(0, "constructor " + c);
1.172 + prExecutable(0, c);
1.173 + }
1.174 +
1.175 +
1.176 + private void prPackage(int off, PackageDoc p) throws IOException {
1.177 + prln(off, "package " + p);
1.178 + prAnnotations(off + 2, p.annotations());
1.179 + }
1.180 +
1.181 + private void prClass(int off, ClassDoc cd) throws IOException {
1.182 + prln(off,
1.183 + (cd.isInterface() ? "interface" : cd.isEnum() ? "enum" : "class")
1.184 + + " " + cd);
1.185 + prln(off + 2, "name: " + cd.simpleTypeName() + " / " +
1.186 + cd.typeName() + " / " + cd.qualifiedTypeName());
1.187 + prAnnotations(off + 2, cd.annotations());
1.188 + prLabel(off + 2, "type parameters");
1.189 + for (Type t : cd.typeParameters())
1.190 + prln(off + 4, t);
1.191 + prParamTags(off + 2, cd.typeParamTags());
1.192 + prLabel(off + 2, "nested in");
1.193 + prln(off + 4, cd.containingClass());
1.194 + prLabel(off + 2, "superclass");
1.195 + prln(off + 4, cd.superclassType());
1.196 + prLabel(off + 2, "interfaces");
1.197 + Type[] ts = cd.interfaceTypes();
1.198 + Arrays.sort(ts);
1.199 + for (Type t : ts)
1.200 + prln(off + 4, t);
1.201 + prLabel(off + 2, "enum constants");
1.202 + for (FieldDoc f : cd.enumConstants())
1.203 + prln(off + 4, f.name());
1.204 + prLabel(off + 2, "fields");
1.205 + for (FieldDoc f : cd.fields())
1.206 + prln(off + 4, f.type() + " " + f.name());
1.207 + prLabel(off + 2, "constructors");
1.208 + for (ConstructorDoc c : cd.constructors())
1.209 + prln(off + 4, c.name() + c.flatSignature());
1.210 + prLabel(off + 2, "methods");
1.211 + for (MethodDoc m : cd.methods())
1.212 + prln(off + 4, typeUseString(m.returnType()) + " " +
1.213 + m.name() + m.flatSignature());
1.214 + }
1.215 +
1.216 + private void prAnnotationType(int off, AnnotationTypeDoc at)
1.217 + throws IOException {
1.218 + prln(off, "@interface " + at);
1.219 + prAnnotations(off + 2, at.annotations());
1.220 + prLabel(off + 2, "elements");
1.221 + for (AnnotationTypeElementDoc e : at.elements()) {
1.222 + String def = (e.defaultValue() == null)
1.223 + ? ""
1.224 + : " default " + e.defaultValue();
1.225 + prln(off + 4, typeUseString(e.returnType()) + " " + e.name() +
1.226 + e.flatSignature() + def);
1.227 + }
1.228 + }
1.229 +
1.230 + private void prField(int off, FieldDoc f) throws IOException {
1.231 + prln(off, "field " + typeUseString(f.type()) + " " + f.name());
1.232 + prAnnotations(off + 2, f.annotations());
1.233 + }
1.234 +
1.235 + private void prParameter(int off, Parameter p) throws IOException {
1.236 + prln(off, "parameter " + p);
1.237 + prAnnotations(off + 2, p.annotations());
1.238 + }
1.239 +
1.240 + private void prMethod(int off, MethodDoc m) throws IOException {
1.241 + prExecutable(off, m);
1.242 + prLabel(off + 2, "returns");
1.243 + prln(off + 4, typeUseString(m.returnType()));
1.244 + prLabel(off + 2, "overridden type");
1.245 + prln(off + 4, m.overriddenType());
1.246 + }
1.247 +
1.248 + private void prExecutable(int off, ExecutableMemberDoc m)
1.249 + throws IOException {
1.250 + if (!m.isAnnotationTypeElement()) {
1.251 + prln(off + 2, "signature: " + m.flatSignature());
1.252 + prln(off + 2, " " + m.signature());
1.253 + }
1.254 + prAnnotations(off + 2, m.annotations());
1.255 + prParamTags(off + 2, m.typeParamTags());
1.256 + prParamTags(off + 2, m.paramTags());
1.257 + prLabel(off + 2, "type parameters");
1.258 + for (Type t : m.typeParameters())
1.259 + prln(off + 4, t);
1.260 + prLabel(off + 2, "throws");
1.261 + Type[] ts = m.thrownExceptionTypes();
1.262 + Arrays.sort(ts);
1.263 + for (Type t : ts)
1.264 + prln(off + 4, t);
1.265 + }
1.266 +
1.267 + private void prAnnotations(int off, AnnotationDesc[] as)
1.268 + throws IOException {
1.269 + prLabel(off, "annotations");
1.270 + for (AnnotationDesc a : as)
1.271 + prln(off + 2, a.toString());
1.272 + }
1.273 +
1.274 + private void prParamTags(int off, ParamTag tags[]) throws IOException {
1.275 + for (ParamTag tag : tags)
1.276 + prParamTag(off, tag);
1.277 + }
1.278 +
1.279 + private void prParamTag(int off, ParamTag tag) throws IOException {
1.280 + String name = tag.parameterName();
1.281 + if (tag.isTypeParameter()) name = "<" + name + ">";
1.282 + prln(off, "@param " + name + " " + tag.parameterComment());
1.283 + }
1.284 +
1.285 +
1.286 + private String typeUseString(Type t) {
1.287 + return (t instanceof ClassDoc || t instanceof TypeVariable)
1.288 + ? t.typeName()
1.289 + : t.toString();
1.290 + }
1.291 +
1.292 +
1.293 + // Labels queued for possible printing. Innermost is first in list.
1.294 + List<Line> labels = new ArrayList<Line>();
1.295 +
1.296 + // Print label if its section is nonempty.
1.297 + void prLabel(int off, String s) {
1.298 + while (!labels.isEmpty() && labels.get(0).off >= off)
1.299 + labels.remove(0);
1.300 + labels.add(0, new Line(off, s));
1.301 + }
1.302 +
1.303 + // Print queued labels with offsets less than "off".
1.304 + void popLabels(int off) throws IOException {
1.305 + while (!labels.isEmpty()) {
1.306 + Line label = labels.remove(0);
1.307 + if (label.off < off)
1.308 + prln(label.off, label.o + ":");
1.309 + }
1.310 + }
1.311 +
1.312 + // Print "o" at given offset.
1.313 + void pr(int off, Object o) throws IOException {
1.314 + popLabels(off);
1.315 + for (int i = 0; i < off; i++)
1.316 + out.write(' ');
1.317 + if (o != null)
1.318 + out.write(o.toString());
1.319 + }
1.320 +
1.321 + // Print "o" (if non-null) at given offset, then newline.
1.322 + void prln(int off, Object o) throws IOException {
1.323 + if (o != null) {
1.324 + pr(off, o);
1.325 + prln();
1.326 + }
1.327 + }
1.328 +
1.329 + // Print newline.
1.330 + void prln() throws IOException {
1.331 + out.write('\n'); // don't want platform-dependent separator
1.332 + }
1.333 +
1.334 +
1.335 + static class Line {
1.336 + int off;
1.337 + Object o;
1.338 + Line(int off, Object o) { this.off = off; this.o = o; }
1.339 + }
1.340 +}
