jars/icu4j-52_1/tools/build/src/com/ibm/icu/dev/tool/docs/GatherAPIData.java

   1 /**
   2  *******************************************************************************
   3  * Copyright (C) 2004-2012, International Business Machines Corporation and    *
   4  * others. All Rights Reserved.                                                *
   5  *******************************************************************************
   6  */
   7
   8 /**
   9  * Generate a list of ICU's public APIs, sorted by qualified name and signature
  10  * public APIs are all non-internal, non-package apis in com.ibm.icu.[lang|math|text|util].
  11  * For each API, list
  12  * - public, package, protected, or private (PB PK PT PR)
  13  * - static or non-static (STK NST)
  14  * - final or non-final (FN NF)
  15  * - synchronized or non-synchronized (SYN NSY)
  16  * - stable, draft, deprecated, obsolete (ST DR DP OB)
  17  * - abstract or non-abstract (AB NA)
  18  * - constructor, member, field (C M F)
  19  *
  20  * Requires JDK 1.5 or later
  21  *
  22  * Sample compilation:
  23  * c:/doug/java/jdk1.5/build/windows-i586/bin/javac *.java
  24  *
  25  * Sample execution
  26  * c:/j2sdk1.5/bin/javadoc
  27  *   -classpath c:/jd2sk1.5/lib/tools.jar
  28  *   -doclet com.ibm.icu.dev.tool.docs.GatherAPIData
  29  *   -docletpath c:/doug/icu4j/tools/build/out/lib/icu4j-build-tools.jar
  30  *   -sourcepath c:/doug/icu4j/main/classes/core/src
  31  *   -name "ICU4J 4.2"
  32  *   -output icu4j42.api2
  33  *   -gzip
  34  *   -source 1.5
  35  *   com.ibm.icu.lang com.ibm.icu.math com.ibm.icu.text com.ibm.icu.util
  36  *
  37  * todo: provide command-line control of filters of which subclasses/packages to process
  38  * todo: record full inheritance hierarchy, not just immediate inheritance
  39  * todo: allow for aliasing comparisons (force (pkg.)*class to be treated as though it
  40  *       were in a different pkg/class hierarchy (facilitates comparison of icu4j and java)
  41  */
  42
  43 package com.ibm.icu.dev.tool.docs;
  44
  45 // standard release sdk won't work, need internal build to get access to javadoc
  46 import java.io.BufferedWriter;
  47 import java.io.FileOutputStream;
  48 import java.io.IOException;
  49 import java.io.OutputStream;
  50 import java.io.OutputStreamWriter;
  51 import java.util.Collection;
  52 import java.util.Iterator;
  53 import java.util.TreeSet;
  54 import java.util.regex.Pattern;
  55 import java.util.zip.GZIPOutputStream;
  56 import java.util.zip.ZipEntry;
  57 import java.util.zip.ZipOutputStream;
  58
  59 import com.sun.javadoc.ClassDoc;
  60 import com.sun.javadoc.ConstructorDoc;
  61 import com.sun.javadoc.ExecutableMemberDoc;
  62 import com.sun.javadoc.FieldDoc;
  63 import com.sun.javadoc.LanguageVersion;
  64 import com.sun.javadoc.MemberDoc;
  65 import com.sun.javadoc.MethodDoc;
  66 import com.sun.javadoc.ProgramElementDoc;
  67 import com.sun.javadoc.RootDoc;
  68 import com.sun.javadoc.Tag;
  69
  70 public class GatherAPIData {
  71     RootDoc root;
  72     TreeSet results;
  73     String srcName = "Current"; // default source name
  74     String output; // name of output file to write
  75     String base; // strip this prefix
  76     Pattern pat;
  77     boolean zip;
  78     boolean gzip;
  79     boolean internal;
  80     boolean version;
  81
  82     public static int optionLength(String option) {
  83         if (option.equals("-name")) {
  84             return 2;
  85         } else if (option.equals("-output")) {
  86             return 2;
  87         } else if (option.equals("-base")) {
  88             return 2;
  89         } else if (option.equals("-filter")) {
  90             return 2;
  91         } else if (option.equals("-zip")) {
  92             return 1;
  93         } else if (option.equals("-gzip")) {
  94             return 1;
  95         } else if (option.equals("-internal")) {
  96             return 1;
  97         } else if (option.equals("-version")) {
  98             return 1;
  99         }
 100         return 0;
 101     }
 102
 103     public static boolean start(RootDoc root) {
 104         return new GatherAPIData(root).run();
 105     }
 106
 107     /**
 108      * If you don't do this, javadoc treats enums like regular classes!
 109      * doesn't matter if you pass -source 1.5 or not.
 110      */
 111     public static LanguageVersion languageVersion() {
 112         return LanguageVersion.JAVA_1_5;
 113     }
 114
 115     GatherAPIData(RootDoc root) {
 116         this.root = root;
 117
 118         String[][] options = root.options();
 119         for (int i = 0; i < options.length; ++i) {
 120             String opt = options[i][0];
 121             if (opt.equals("-name")) {
 122                 this.srcName = options[i][1];
 123             } else if (opt.equals("-output")) {
 124                 this.output = options[i][1];
 125             } else if (opt.equals("-base")) {
 126                 this.base = options[i][1]; // should not include '.'
 127             } else if (opt.equals("-filter")) {
 128                 this.pat = Pattern.compile(options[i][1], Pattern.CASE_INSENSITIVE);
 129             } else if (opt.equals("-zip")) {
 130                 this.zip = true;
 131             } else if (opt.equals("-gzip")) {
 132                 this.gzip = true;
 133             } else if (opt.equals("-internal")) {
 134                 this.internal = true;
 135             } else if (opt.equals("-version")) {
 136                 this.version = true;
 137             }
 138         }
 139
 140         results = new TreeSet(APIInfo.defaultComparator());
 141     }
 142
 143     private boolean run() {
 144         doDocs(root.classes());
 145
 146         OutputStream os = System.out;
 147         if (output != null) {
 148             ZipOutputStream zos = null;
 149             try {
 150                 if (zip) {
 151                     zos = new ZipOutputStream(new FileOutputStream(output + ".zip"));
 152                     zos.putNextEntry(new ZipEntry(output));
 153                     os = zos;
 154                 } else if (gzip) {
 155                     os = new GZIPOutputStream(new FileOutputStream(output + ".gz"));
 156                 } else {
 157                     os = new FileOutputStream(output);
 158                 }
 159             }
 160             catch (IOException e) {
 161                 RuntimeException re = new RuntimeException(e.getMessage());
 162                 re.initCause(e);
 163                 throw re;
 164             }
 165             finally {
 166                 if (zos != null) {
 167                     try {
 168                         zos.close();
 169                     } catch (Exception e) {
 170                         // ignore
 171                     }
 172                 }
 173             }
 174         }
 175
 176         BufferedWriter bw = null;
 177         try {
 178             OutputStreamWriter osw = new OutputStreamWriter(os, "UTF-8");
 179             bw = new BufferedWriter(osw);
 180
 181             // writing data file
 182             bw.write(String.valueOf(APIInfo.VERSION) + APIInfo.SEP); // header version
 183             bw.write(srcName + APIInfo.SEP); // source name
 184             bw.write((base == null ? "" : base) + APIInfo.SEP); // base
 185             bw.newLine();
 186             writeResults(results, bw);
 187             bw.close(); // should flush, close all, etc
 188         } catch (IOException e) {
 189             try { bw.close(); } catch (IOException e2) {}
 190             RuntimeException re = new RuntimeException("write error: " + e.getMessage());
 191             re.initCause(e);
 192             throw re;
 193         }
 194
 195         return false;
 196     }
 197
 198     private void doDocs(ProgramElementDoc[] docs) {
 199         if (docs != null && docs.length > 0) {
 200             for (int i = 0; i < docs.length; ++i) {
 201                 doDoc(docs[i]);
 202             }
 203         }
 204     }
 205
 206     private void doDoc(ProgramElementDoc doc) {
 207         if (ignore(doc)) return;
 208
 209         if (doc.isClass() || doc.isInterface()) {
 210             ClassDoc cdoc = (ClassDoc)doc;
 211             doDocs(cdoc.fields());
 212             doDocs(cdoc.constructors());
 213             doDocs(cdoc.methods());
 214             // don't call this to iterate over inner classes,
 215             // root.classes already includes them
 216             // doDocs(cdoc.innerClasses());
 217         }
 218
 219         APIInfo info = createInfo(doc);
 220         if (info != null) {
 221             results.add(info);
 222         }
 223     }
 224
 225     // Sigh. Javadoc doesn't indicate when the compiler generates
 226     // the values and valueOf enum methods.  The position of the
 227     // method for these is not always the same as the position of
 228     // the class, though it often is, so we can't use that.
 229
 230     private boolean isIgnoredEnumMethod(ProgramElementDoc doc) {
 231         if (doc.isMethod() && doc.containingClass().isEnum()) {
 232             // System.out.println("*** " + doc.qualifiedName() + " pos: " +
 233             //                    doc.position().line() +
 234             //                    " containined by: " +
 235             //                    doc.containingClass().name() +
 236             //                    " pos: " +
 237             //                    doc.containingClass().position().line());
 238             // return doc.position().line() == doc.containingClass().position().line();
 239
 240             String name = doc.name();
 241             // assume we don't have enums that overload these method names.
 242             return "values".equals(name) || "valueOf".equals(name);
 243         }
 244         return false;
 245     }
 246
 247     // isSynthesized also doesn't seem to work.  Let's do this, documenting
 248     // synthesized constructors for abstract classes is kind of weird.
 249     // We can't actually tell if the constructor was synthesized or is
 250     // actually in the docs, but this shouldn't matter.  We don't really
 251     // care if we didn't properly document the draft status of
 252     // default constructors for abstract classes.
 253
 254     private boolean isAbstractClassDefaultConstructor(ProgramElementDoc doc) {
 255         return doc.isConstructor()
 256             && doc.containingClass().isAbstract()
 257             && "()".equals(((ConstructorDoc) doc).signature());
 258     }
 259
 260     private boolean ignore(ProgramElementDoc doc) {
 261         if (doc == null) return true;
 262         if (doc.isPrivate() || doc.isPackagePrivate()) return true;
 263         if (doc instanceof MemberDoc && ((MemberDoc)doc).isSynthetic()) return true;
 264         if (doc.qualifiedName().indexOf(".misc") != -1) {
 265             System.out.println("misc: " + doc.qualifiedName()); return true;
 266         }
 267         if (isIgnoredEnumMethod(doc)) {
 268             return true;
 269         }
 270         if (isAbstractClassDefaultConstructor(doc)) {
 271             return true;
 272         }
 273
 274         if (false && doc.qualifiedName().indexOf("LocaleDisplayNames") != -1) {
 275           System.err.print("*** " + doc.qualifiedName() + ":");
 276           if (doc.isClass()) System.err.print(" class");
 277           if (doc.isConstructor()) System.err.print(" constructor");
 278           if (doc.isEnum()) System.err.print(" enum");
 279           if (doc.isEnumConstant()) System.err.print(" enum_constant");
 280           if (doc.isError()) System.err.print(" error");
 281           if (doc.isException()) System.err.print(" exception");
 282           if (doc.isField()) System.err.print(" field");
 283           if (doc.isInterface()) System.err.print(" interface");
 284           if (doc.isMethod()) System.err.print(" method");
 285           if (doc.isOrdinaryClass()) System.err.print(" ordinary_class");
 286           System.err.println();
 287         }
 288
 289         if (!internal) { // debug
 290             Tag[] tags = doc.tags();
 291             for (int i = 0; i < tags.length; ++i) {
 292                 if (tagKindIndex(tags[i].kind()) == INTERNAL) { return true; }
 293             }
 294         }
 295         if (pat != null && (doc.isClass() || doc.isInterface())) {
 296             if (!pat.matcher(doc.name()).matches()) {
 297                 return true;
 298             }
 299         }
 300         return false;
 301     }
 302
 303     private static void writeResults(Collection c, BufferedWriter w) {
 304         Iterator iter = c.iterator();
 305         while (iter.hasNext()) {
 306             APIInfo info = (APIInfo)iter.next();
 307             info.writeln(w);
 308         }
 309     }
 310
 311     private String trimBase(String arg) {
 312         if (base != null) {
 313             for (int n = arg.indexOf(base); n != -1; n = arg.indexOf(base, n)) {
 314                 arg = arg.substring(0, n) + arg.substring(n+base.length());
 315             }
 316         }
 317         return arg;
 318     }
 319
 320     public APIInfo createInfo(ProgramElementDoc doc) {
 321
 322         // Doc. name
 323         // Doc. isField, isMethod, isConstructor, isClass, isInterface
 324         // ProgramElementDoc. containingClass, containingPackage
 325         // ProgramElementDoc. isPublic, isProtected, isPrivate, isPackagePrivate
 326         // ProgramElementDoc. isStatic, isFinal
 327         // MemberDoc.isSynthetic
 328         // ExecutableMemberDoc isSynchronized, signature
 329         // Type.toString() // e.g. "String[][]"
 330         // ClassDoc.isAbstract, superClass, interfaces, fields, methods, constructors, innerClasses
 331         // FieldDoc type
 332         // ConstructorDoc qualifiedName
 333         // MethodDoc isAbstract, returnType
 334
 335         APIInfo info = new APIInfo();
 336         if (version) {
 337             info.includeStatusVersion(true);
 338         }
 339
 340         // status
 341         String[] version = new String[1];
 342         info.setType(APIInfo.STA, tagStatus(doc, version));
 343         info.setStatusVersion(version[0]);
 344
 345         // visibility
 346         if (doc.isPublic()) {
 347             info.setPublic();
 348         } else if (doc.isProtected()) {
 349             info.setProtected();
 350         } else if (doc.isPrivate()) {
 351             info.setPrivate();
 352         } else {
 353             // default is package
 354         }
 355
 356         // static
 357         if (doc.isStatic()) {
 358             info.setStatic();
 359         } else {
 360             // default is non-static
 361         }
 362
 363         // final
 364         if (doc.isFinal()) {
 365             info.setFinal();
 366         } else {
 367             // default is non-final
 368         }
 369
 370         // type
 371         if (doc.isField()) {
 372             info.setField();
 373         } else if (doc.isMethod()) {
 374             info.setMethod();
 375         } else if (doc.isConstructor()) {
 376             info.setConstructor();
 377         } else if (doc.isClass() || doc.isInterface()) {
 378             info.setClass();
 379         }
 380
 381         info.setPackage(trimBase(doc.containingPackage().name()));
 382         info.setClassName((doc.isClass() || doc.isInterface() || (doc.containingClass() == null))
 383                           ? ""
 384                           : trimBase(doc.containingClass().name()));
 385         info.setName(trimBase(doc.name()));
 386
 387         if (doc instanceof FieldDoc) {
 388             FieldDoc fdoc = (FieldDoc)doc;
 389             info.setSignature(trimBase(fdoc.type().toString()));
 390         } else if (doc instanceof ClassDoc) {
 391             ClassDoc cdoc = (ClassDoc)doc;
 392
 393             if (cdoc.isClass() && cdoc.isAbstract()) {
 394                 // interfaces are abstract by default, don't mark them as abstract
 395                 info.setAbstract();
 396             }
 397
 398             StringBuffer buf = new StringBuffer();
 399             if (cdoc.isClass()) {
 400                 buf.append("extends ");
 401                 buf.append(cdoc.superclass().qualifiedName());
 402             }
 403             ClassDoc[] imp = cdoc.interfaces();
 404             if (imp != null && imp.length > 0) {
 405                 if (buf.length() > 0) {
 406                     buf.append(" ");
 407                 }
 408                 buf.append("implements");
 409                 for (int i = 0; i < imp.length; ++i) {
 410                     if (i != 0) {
 411                         buf.append(",");
 412                     }
 413                     buf.append(" ");
 414                     buf.append(imp[i].qualifiedName());
 415                 }
 416             }
 417             info.setSignature(trimBase(buf.toString()));
 418         } else {
 419             ExecutableMemberDoc emdoc = (ExecutableMemberDoc)doc;
 420             if (emdoc.isSynchronized()) {
 421                 info.setSynchronized();
 422             }
 423
 424             if (doc instanceof MethodDoc) {
 425                 MethodDoc mdoc = (MethodDoc)doc;
 426                 if (mdoc.isAbstract()) {
 427                     info.setAbstract();
 428                 }
 429                 info.setSignature(trimBase(mdoc.returnType().toString() + emdoc.signature()));
 430             } else {
 431                 // constructor
 432                 info.setSignature(trimBase(emdoc.signature()));
 433             }
 434         }
 435
 436         return info;
 437     }
 438
 439     private int tagStatus(final ProgramElementDoc doc, String[] version) {
 440         class Result {
 441             int res = -1;
 442             void set(int val) {
 443                 if (res != -1) {
 444                     if (val == APIInfo.STA_DEPRECATED) {
 445                         // ok to have both a 'standard' tag and deprecated
 446                         return;
 447                     } else if (res != APIInfo.STA_DEPRECATED) {
 448                         // if already not deprecated, this is an error
 449                         System.err.println("bad doc: " + doc + " both: "
 450                                            + APIInfo.getTypeValName(APIInfo.STA, res) + " and: "
 451                                            + APIInfo.getTypeValName(APIInfo.STA, val));
 452                         return;
 453                     }
 454                 }
 455                 // ok to replace with new tag
 456                 res = val;
 457             }
 458             int get() {
 459                 if (res == -1) {
 460                     System.err.println("warning: no tag for " + doc);
 461                     return 0;
 462                 }
 463                 return res;
 464             }
 465         }
 466
 467         Tag[] tags = doc.tags();
 468         Result result = new Result();
 469         String statusVer = "";
 470         for (int i = 0; i < tags.length; ++i) {
 471             Tag tag = tags[i];
 472
 473             String kind = tag.kind();
 474             int ix = tagKindIndex(kind);
 475
 476             switch (ix) {
 477             case INTERNAL:
 478                 result.set(internal ? APIInfo.STA_INTERNAL : -2); // -2 for legacy compatibility
 479                 statusVer = getStatusVersion(tag);
 480                 break;
 481
 482             case DRAFT:
 483                 result.set(APIInfo.STA_DRAFT);
 484                 statusVer = getStatusVersion(tag);
 485                 break;
 486
 487             case STABLE:
 488                 result.set(APIInfo.STA_STABLE);
 489                 statusVer = getStatusVersion(tag);
 490                 break;
 491
 492             case DEPRECATED:
 493                 result.set(APIInfo.STA_DEPRECATED);
 494                 statusVer = getStatusVersion(tag);
 495                 break;
 496
 497             case OBSOLETE:
 498                 result.set(APIInfo.STA_OBSOLETE);
 499                 statusVer = getStatusVersion(tag);
 500                 break;
 501
 502             case SINCE:
 503             case EXCEPTION:
 504             case VERSION:
 505             case UNKNOWN:
 506             case AUTHOR:
 507             case SEE:
 508             case PARAM:
 509             case RETURN:
 510             case THROWS:
 511             case SERIAL:
 512                 break;
 513
 514             default:
 515                 throw new RuntimeException("unknown index " + ix + " for tag: " + kind);
 516             }
 517         }
 518
 519         if (version != null) {
 520             version[0] = statusVer;
 521         }
 522         return result.get();
 523     }
 524
 525     private String getStatusVersion(Tag tag) {
 526         String text = tag.text();
 527         if (text != null && text.length() > 0) {
 528             // Extract version string
 529             int start = -1;
 530             int i = 0;
 531             for (; i < text.length(); i++) {
 532                 char ch = text.charAt(i);
 533                 if (ch == '.' || (ch >= '0' && ch <= '9')) {
 534                     if (start == -1) {
 535                         start = i;
 536                     }
 537                 } else if (start != -1) {
 538                     break;
 539                 }
 540             }
 541             if (start != -1) {
 542                 return text.substring(start, i);
 543             }
 544         }
 545         return "";
 546     }
 547
 548     private static final int UNKNOWN = -1;
 549     private static final int INTERNAL = 0;
 550     private static final int DRAFT = 1;
 551     private static final int STABLE = 2;
 552     private static final int SINCE = 3;
 553     private static final int DEPRECATED = 4;
 554     private static final int AUTHOR = 5;
 555     private static final int SEE = 6;
 556     private static final int VERSION = 7;
 557     private static final int PARAM = 8;
 558     private static final int RETURN = 9;
 559     private static final int THROWS = 10;
 560     private static final int OBSOLETE = 11;
 561     private static final int EXCEPTION = 12;
 562     private static final int SERIAL = 13;
 563
 564     private static int tagKindIndex(String kind) {
 565         final String[] tagKinds = {
 566             "@internal", "@draft", "@stable", "@since", "@deprecated", "@author", "@see",
 567             "@version", "@param", "@return", "@throws", "@obsolete", "@exception", "@serial"
 568         };
 569
 570         for (int i = 0; i < tagKinds.length; ++i) {
 571             if (kind.equals(tagKinds[i])) {
 572                 return i;
 573             }
 574         }
 575         return UNKNOWN;
 576     }
 577 }