build_tools/doctool/src/com/google/doctool/Booklet.java

/*
 * Copyright 2006 Google Inc.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.doctool;

import com.google.doctool.LinkResolver.ExtraClassResolver;

import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.Doc;
import com.sun.javadoc.DocErrorReporter;
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MemberDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.PackageDoc;
import com.sun.javadoc.ParamTag;
import com.sun.javadoc.Parameter;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.SeeTag;
import com.sun.javadoc.SourcePosition;
import com.sun.javadoc.Tag;
import com.sun.javadoc.Type;

import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.HashSet;
import java.util.Iterator;
import java.util.Stack;

/**
 * Generates XML from Javadoc source, with particular idioms to make it possible
 * to translate into either expository doc or API doc.
 */
public class Booklet {

  private static final String OPT_BKCODE = "-bkcode";
  private static final String OPT_BKDOCPKG = "-bkdocpkg";
  private static final String OPT_BKOUT = "-bkout";

  private static Booklet sBooklet;

  public static void main(String[] args) {
    // Strip off our arguments at the beginning.
    //
    com.sun.tools.javadoc.Main.execute(args);
  }

  public static int optionLength(String option) {
    if (option.equals(OPT_BKOUT)) {
      return 2;
    } else if (option.equals(OPT_BKDOCPKG)) {
      return 2;
    } else if (option.equals(OPT_BKCODE)) {
      return 1;
    }
    return 0;
  }

  public static String slurpSource(SourcePosition position) {
    BufferedReader br = null;
    try {
      br = new BufferedReader(new FileReader(position.file()));
      for (int i = 0, n = position.line() - 1; i < n; ++i) {
        br.readLine();
      }

      StringBuffer lines = new StringBuffer();
      String line = br.readLine();
      int braceDepth = 0;
      int indent = -1;
      boolean seenSemiColonOrBrace = false;
      while (line != null) {
        if (indent == -1) {
          for (indent = 0; Character.isWhitespace(line.charAt(indent)); ++indent) {
            // just accumulate
          }
        }

        if (line.length() >= indent) {
          line = line.substring(indent);
        }

        lines.append(line + "\n");
        for (int i = 0, n = line.length(); i < n; ++i) {
          char c = line.charAt(i);
          if (c == '{') {
            seenSemiColonOrBrace = true;
            ++braceDepth;
          } else if (c == '}') {
            --braceDepth;
          } else if (c == ';') {
            seenSemiColonOrBrace = true;
          }
        }

        if (braceDepth > 0 || !seenSemiColonOrBrace) {
          line = br.readLine();
        } else {
          break;
        }
      }

      String code = lines.toString();
      return code;
    } catch (Exception e) {
      e.printStackTrace();
    } finally {
      try {
        if (br != null) {
          br.close();
        }
      } catch (IOException e) {
        e.printStackTrace();
      }
    }
    return "";
  }

  public static boolean start(RootDoc rootDoc) {
    getBooklet().process(rootDoc);
    return true;
  }

  public static boolean validOptions(String[][] options,
      DocErrorReporter reporter) {
    return getBooklet().analyzeOptions(options, reporter);
  }

  private static Booklet getBooklet() {
    if (sBooklet == null) {
      sBooklet = new Booklet();
    }
    return sBooklet;
  }

  private String outputPath;

  private HashSet packagesToGenerate;

  private RootDoc initialRootDoc;

  private String rootDocId;

  private boolean showCode;

  private HashSet standardTagKinds = new HashSet();

  private Stack tagStack = new Stack();

  private PrintWriter pw;

  public Booklet() {
    // Set up standard tags (to ignore during tag processing)
    //
    standardTagKinds.add("@see");
    standardTagKinds.add("@serial");
    standardTagKinds.add("@throws");
    standardTagKinds.add("@param");
    standardTagKinds.add("@id");
  }

  private boolean analyzeOptions(String[][] options, DocErrorReporter reporter) {
    for (int i = 0, n = options.length; i < n; ++i) {
      if (options[i][0].equals(OPT_BKOUT)) {
        outputPath = options[i][1];
      } else if (options[i][0].equals(OPT_BKDOCPKG)) {
        String[] packages = options[i][1].split(";");
        packagesToGenerate = new HashSet();
        for (int packageIndex = 0; packageIndex < packages.length; ++packageIndex) {
          packagesToGenerate.add(packages[packageIndex]);
        }
      } else if (options[i][0].equals(OPT_BKCODE)) {
        showCode = true;
      }
    }

    if (outputPath == null) {
      reporter.printError("You must specify an output directory with "
          + OPT_BKOUT);
      return false;
    }

    return true;
  }

  private void begin(String tag) {
    pw.print("<" + tag + ">");
    tagStack.push(tag);
  }

  private void begin(String tag, String attr, String value) {
    pw.print("<" + tag + " " + attr + "='" + value + "'>");
    tagStack.push(tag);
  }

  private void beginCDATA() {
    pw.print("<![CDATA[");
  }

  private void beginEndln(String tag) {
    pw.println("<" + tag + "/>");
  }

  private void beginln(String tag) {
    pw.println();
    begin(tag);
  }

  private void beginln(String tag, String attr, String value) {
    pw.println();
    begin(tag, attr, value);
  }

  private void emitDescription(ClassDoc enclosing, Doc forWhat,
      Tag[] leadInline, Tag[] descInline) {
    emitJRELink(enclosing, forWhat);

    beginln("lead");
    processTags(leadInline);
    endln();

    beginln("description");
    processTags(descInline);
    endln();
  }

  private void emitIdentity(String id, String name) {
    beginln("id");
    text(id);
    endln();

    beginln("name");
    text(name);
    endln();
  }

  private void emitJRELink(ClassDoc enclosing, Doc doc) {
    String jreLink = "http://java.sun.com/j2se/1.5.0/docs/api/";
    if (doc instanceof ClassDoc) {
      ClassDoc classDoc = (ClassDoc) doc;
      String pkg = classDoc.containingPackage().name();
      if (!pkg.startsWith("java.")) {
        return;
      }
      String clazz = classDoc.name();

      jreLink += pkg.replace('.', '/') + "/";
      jreLink += clazz;
      jreLink += ".html";
    } else if (doc instanceof ExecutableMemberDoc) {
      ExecutableMemberDoc execMemberDoc = (ExecutableMemberDoc) doc;
      String pkg = enclosing.containingPackage().name();
      if (!pkg.startsWith("java.")) {
        return;
      }
      String clazz = enclosing.name();
      String method = execMemberDoc.name();
      String sig = execMemberDoc.signature();

      jreLink += pkg.replace('.', '/') + "/";
      jreLink += clazz;
      jreLink += ".html";
      jreLink += "#";
      jreLink += method;
      jreLink += sig;
    } else if (doc instanceof PackageDoc) {
      String pkg = doc.name();
      if (!pkg.startsWith("java.")) {
        return;
      }
      jreLink += pkg.replace('.', '/') + "/package-summary.html";
    } else if (doc instanceof FieldDoc) {
      FieldDoc fieldDoc = (FieldDoc) doc;
      String pkg = enclosing.containingPackage().name();
      if (!pkg.startsWith("java.")) {
        return;
      }
      String clazz = fieldDoc.containingClass().name();
      String field = fieldDoc.name();

      jreLink += pkg.replace('.', '/') + "/";
      jreLink += clazz;
      jreLink += ".html";
      jreLink += "#";
      jreLink += field;
    }

    // Add the link.
    //
    beginln("jre");
    text(jreLink);
    endln();
  }

  private void emitLocation(Doc doc) {
    Doc parent = getParentDoc(doc);
    if (parent != null) {
      beginln("location");
      emitLocationLink(parent);
      endln();
    }
  }

  private void emitLocationLink(Doc doc) {
    // Intentionally reverses the order.
    //
    String myId;
    String myTitle;
    if (doc instanceof MemberDoc) {
      MemberDoc memberDoc = (MemberDoc) doc;
      myId = getId(memberDoc);
      myTitle = memberDoc.name();
    } else if (doc instanceof ClassDoc) {
      ClassDoc classDoc = (ClassDoc) doc;
      myId = getId(classDoc);
      myTitle = classDoc.name();
    } else if (doc instanceof PackageDoc) {
      PackageDoc pkgDoc = (PackageDoc) doc;
      myId = getId(pkgDoc);
      myTitle = pkgDoc.name();
    } else if (doc instanceof RootDoc) {
      myId = rootDocId;
      myTitle = initialRootDoc.name();
    } else {
      throw new IllegalStateException(
          "Expected only a member, type, or package");
    }

    Doc parent = getParentDoc(doc);
    if (parent != null) {
      emitLocationLink(parent);
    }

    beginln("link", "ref", myId);

    Tag[] titleTag = doc.tags("@title");
    if (titleTag.length > 0) {
      myTitle = titleTag[0].text().trim();
    }

    if (myTitle == null || myTitle.length() == 0) {
      myTitle = "[NO TITLE]";
    }

    text(myTitle);

    endln();
  }

  private void emitModifiers(ProgramElementDoc doc) {
    if (doc.isPrivate()) {
      beginEndln("isPrivate");
    } else if (doc.isProtected()) {
      beginEndln("isProtected");
    } else if (doc.isPublic()) {
      beginEndln("isPublic");
    } else if (doc.isPackagePrivate()) {
      beginEndln("isPackagePrivate");
    }

    if (doc.isStatic()) {
      beginEndln("isStatic");
    }

    if (doc.isFinal()) {
      beginEndln("isFinal");
    }

    if (doc instanceof MethodDoc) {
      MethodDoc methodDoc = (MethodDoc) doc;

      if (methodDoc.isAbstract()) {
        beginEndln("isAbstract");
      }

      if (methodDoc.isSynchronized()) {
        beginEndln("isSynchronized");
      }
    }
  }

  private void emitOutOfLineTags(Tag[] tags) {
    beginln("tags");
    processTags(tags);
    endln();
  }

  private void emitType(Type type) {
    ClassDoc typeAsClass = type.asClassDoc();

    if (typeAsClass != null) {
      begin("type", "ref", getId(typeAsClass));
    } else {
      begin("type");
    }

    String typeName = type.typeName();
    String dims = type.dimension();

    text(typeName + dims);

    end();
  }

  private void end() {
    pw.print("</" + tagStack.pop() + ">");
  }

  private void endCDATA() {
    pw.print("]]>");
  }

  private void endln() {
    end();
    pw.println();
  }

  private MethodDoc findMatchingInterfaceMethodDoc(ClassDoc[] interfaces,
      MethodDoc methodDoc) {
    if (interfaces != null) {
      // Look through the methods on superInterface for a matching methodDoc.
      //
      for (int intfIndex = 0; intfIndex < interfaces.length; ++intfIndex) {
        ClassDoc currentIntfDoc = interfaces[intfIndex];
        MethodDoc[] intfMethodDocs = currentIntfDoc.methods();
        for (int methodIndex = 0; methodIndex < intfMethodDocs.length; ++methodIndex) {
          MethodDoc intfMethodDoc = intfMethodDocs[methodIndex];
          String methodDocName = methodDoc.name();
          String intfMethodDocName = intfMethodDoc.name();
          if (methodDocName.equals(intfMethodDocName)) {
            if (methodDoc.signature().equals(intfMethodDoc.signature())) {
              // It's a match!
              //
              return intfMethodDoc;
            }
          }
        }

        // Try the superinterfaces of this interface.
        //
        MethodDoc foundMethodDoc = findMatchingInterfaceMethodDoc(
            currentIntfDoc.interfaces(), methodDoc);
        if (foundMethodDoc != null) {
          return foundMethodDoc;
        }
      }
    }

    // Just didn't find it anywhere. Must not be based on an implemented
    // interface.
    //
    return null;
  }

  private ExtraClassResolver getExtraClassResolver(Tag tag) {

    if (tag.holder() instanceof PackageDoc) {
      return new ExtraClassResolver() {
        public ClassDoc findClass(String className) {
          return initialRootDoc.classNamed(className);
        }
      };
    }

    return null;
  }

  private String getId(ClassDoc classDoc) {
    return classDoc.qualifiedName();
  }

  private String getId(ExecutableMemberDoc memberDoc) {
    // Use the mangled name to look up a unique id (based on its hashCode).
    //
    String clazz = memberDoc.containingClass().qualifiedName();
    String id = clazz + "#" + memberDoc.name() + memberDoc.signature();
    return id;
  }

  private String getId(FieldDoc fieldDoc) {
    String clazz = fieldDoc.containingClass().qualifiedName();
    String id = clazz + "#" + fieldDoc.name();
    return id;
  }

  private String getId(MemberDoc memberDoc) {
    if (memberDoc.isMethod()) {
      return getId((MethodDoc) memberDoc);
    } else if (memberDoc.isConstructor()) {
      return getId((ConstructorDoc) memberDoc);
    } else if (memberDoc.isField()) {
      return getId((FieldDoc) memberDoc);
    } else {
      throw new RuntimeException("Unknown member type");
    }
  }

  private String getId(PackageDoc packageDoc) {
    return packageDoc.name();
  }

  private Doc getParentDoc(Doc doc) {
    if (doc instanceof MemberDoc) {
      MemberDoc memberDoc = (MemberDoc) doc;
      return memberDoc.containingClass();
    } else if (doc instanceof ClassDoc) {
      ClassDoc classDoc = (ClassDoc) doc;
      Doc enclosingClass = classDoc.containingClass();
      if (enclosingClass != null) {
        return enclosingClass;
      } else {
        return classDoc.containingPackage();
      }
    } else if (doc instanceof PackageDoc) {
      return initialRootDoc;
    } else if (doc instanceof RootDoc) {
      return null;
    } else {
      throw new IllegalStateException(
          "Expected only a member, type, or package");
    }
  }

  private boolean looksSynthesized(ExecutableMemberDoc memberDoc) {
    SourcePosition memberPos = memberDoc.position();
    int memberLine = memberPos.line();

    SourcePosition classPos = memberDoc.containingClass().position();
    int classLine = classPos.line();

    if (memberLine == classLine) {
      return true;
    } else {
      return false;
    }
  }

  private void process(ClassDoc enclosing, ClassDoc classDoc) {
    // Make sure it isn't a @skip-ped topic.
    //
    if (classDoc.tags("@skip").length > 0) {
      // This one is explicitly skipped right now.
      //
      return;
    }

    if (classDoc.isInterface()) {
      beginln("interface");
    } else {
      beginln("class");
    }

    emitIdentity(getId(classDoc), classDoc.name());
    emitLocation(classDoc);
    emitDescription(enclosing, classDoc, classDoc.firstSentenceTags(),
        classDoc.inlineTags());
    emitOutOfLineTags(classDoc.tags());
    emitModifiers(classDoc);

    ClassDoc superclassDoc = classDoc.superclass();
    if (superclassDoc != null) {
      beginln("superclass", "ref", getId(superclassDoc));
      text(superclassDoc.name());
      endln();
    }

    ClassDoc[] superinterfacesDoc = classDoc.interfaces();
    for (int i = 0; i < superinterfacesDoc.length; i++) {
      ClassDoc superinterfaceDoc = superinterfacesDoc[i];
      beginln("superinterface", "ref", getId(superinterfaceDoc));
      text(superinterfaceDoc.name());
      endln();
    }

    ClassDoc[] cda = classDoc.innerClasses();
    for (int i = 0; i < cda.length; i++) {
      process(classDoc, cda[i]);
    }

    FieldDoc[] fda = classDoc.fields();
    for (int i = 0; i < fda.length; i++) {
      process(classDoc, fda[i]);
    }

    ConstructorDoc[] ctorDocs = classDoc.constructors();
    for (int i = 0; i < ctorDocs.length; i++) {
      process(classDoc, ctorDocs[i]);
    }

    MethodDoc[] methods = classDoc.methods();
    for (int i = 0; i < methods.length; i++) {
      process(classDoc, methods[i]);
    }

    endln();
  }

  private void process(ClassDoc enclosing, ExecutableMemberDoc memberDoc) {
    if (looksSynthesized(memberDoc)) {
      // Skip it.
      //
      return;
    }

    // Make sure it isn't a @skip-ped member.
    //
    if (memberDoc.tags("@skip").length > 0) {
      // This one is explicitly skipped right now.
      //
      return;
    }

    if (memberDoc instanceof MethodDoc) {
      beginln("method");
      emitIdentity(getId(memberDoc), memberDoc.name());
      emitLocation(memberDoc);

      // If this method is not explicitly documented, use the best inherited
      // one.
      //
      String rawComment = memberDoc.getRawCommentText();
      if (rawComment.length() == 0) {
        // Switch out the member doc being used.
        //
        MethodDoc methodDoc = (MethodDoc) memberDoc;
        MethodDoc superMethodDoc = methodDoc.overriddenMethod();

        if (superMethodDoc == null) {

          ClassDoc classDocToTry = methodDoc.containingClass();
          while (classDocToTry != null) {
            // See if this is a method from an interface.
            // If so, borrow its description.
            //
            superMethodDoc = findMatchingInterfaceMethodDoc(
                classDocToTry.interfaces(), methodDoc);

            if (superMethodDoc != null) {
              break;
            }

            classDocToTry = classDocToTry.superclass();
          }
        }

        if (superMethodDoc != null) {
          // Borrow the description from the superclass/superinterface.
          //
          memberDoc = superMethodDoc;
        }
      }
    } else if (memberDoc instanceof ConstructorDoc) {
      beginln("constructor");
      emitIdentity(getId(memberDoc), memberDoc.containingClass().name());
      emitLocation(memberDoc);
    } else {
      throw new IllegalStateException("What kind of executable member is this?");
    }

    emitDescription(enclosing, memberDoc, memberDoc.firstSentenceTags(),
        memberDoc.inlineTags());
    emitOutOfLineTags(memberDoc.tags());
    emitModifiers(memberDoc);

    begin("flatSignature");
    text(memberDoc.flatSignature());
    end();

    // Return type if it's a method
    //
    if (memberDoc instanceof MethodDoc) {
      emitType(((MethodDoc) memberDoc).returnType());
    }

    // Parameters
    //
    beginln("params");
    Parameter[] pda = memberDoc.parameters();
    for (int i = 0; i < pda.length; i++) {
      Parameter pd = pda[i];

      begin("param");
      emitType(pd.type());
      begin("name");
      text(pd.name());
      end();
      end();
    }
    endln();

    // Exceptions thrown
    //
    ClassDoc[] tea = memberDoc.thrownExceptions();
    if (tea.length > 0) {
      beginln("throws");
      for (int i = 0; i < tea.length; ++i) {
        ClassDoc te = tea[i];
        beginln("throw", "ref", getId(te));
        text(te.name());
        endln();
      }
      endln();
    }

    // Maybe show code
    //
    if (showCode) {
      SourcePosition pos = memberDoc.position();
      if (pos != null) {
        beginln("code");
        String source = slurpSource(pos);
        begin("pre", "class", "code");
        beginCDATA();
        text(source);
        endCDATA();
        endln();
        endln();
      }
    }

    endln();
  }

  private void process(ClassDoc enclosing, FieldDoc fieldDoc) {
    // Make sure it isn't @skip-ped.
    //
    if (fieldDoc.tags("@skip").length > 0) {
      // This one is explicitly skipped right now.
      //
      return;
    }

    String commentText = fieldDoc.commentText();
    if (fieldDoc.isPrivate()
        && (commentText == null || commentText.length() == 0)) {
      return;
    }

    beginln("field");
    emitIdentity(fieldDoc.qualifiedName(), fieldDoc.name());
    emitLocation(fieldDoc);
    emitDescription(enclosing, fieldDoc, fieldDoc.firstSentenceTags(),
        fieldDoc.inlineTags());
    emitOutOfLineTags(fieldDoc.tags());
    emitModifiers(fieldDoc);
    emitType(fieldDoc.type());
    endln();
  }

  private void process(PackageDoc packageDoc) {
    beginln("package");

    emitIdentity(packageDoc.name(), packageDoc.name());
    emitLocation(packageDoc);
    emitDescription(null, packageDoc, packageDoc.firstSentenceTags(),
        packageDoc.inlineTags());
    emitOutOfLineTags(packageDoc.tags());

    // Top-level classes
    //
    ClassDoc[] cda = packageDoc.allClasses();
    for (int i = 0; i < cda.length; i++) {
      ClassDoc cd = cda[i];

      // Make sure we have source.
      //
      SourcePosition p = cd.position();
      if (p == null || p.line() == 0) {
        // Skip this since it isn't ours (otherwise we would have source).
        //
        continue;
      }

      if (cd.containingClass() == null) {
        process(cd, cda[i]);
      } else {
        // Not a top-level class.
        //
        cd = cda[i];
      }
    }

    endln();
  }

  private void process(RootDoc rootDoc) {
    try {
      initialRootDoc = rootDoc;
      File outputFile = new File(outputPath);
      // Ignore result since the next line will fail if the directory doesn't
      // exist.
      outputFile.getParentFile().mkdirs();
      FileWriter fw = new FileWriter(outputFile);
      pw = new PrintWriter(fw, true);

      beginln("booklet");

      rootDocId = "";
      String title = "";
      Tag[] idTags = rootDoc.tags("@id");
      if (idTags.length > 0) {
        rootDocId = idTags[0].text();
      } else {
        initialRootDoc.printWarning("Expecting @id in an overview html doc; see -overview");
      }

      Tag[] titleTags = rootDoc.tags("@title");
      if (titleTags.length > 0) {
        title = titleTags[0].text();
      } else {
        initialRootDoc.printWarning("Expecting @title in an overview html doc; see -overview");
      }

      emitIdentity(rootDocId, title);
      emitLocation(rootDoc);
      emitDescription(null, rootDoc, rootDoc.firstSentenceTags(),
          rootDoc.inlineTags());
      emitOutOfLineTags(rootDoc.tags());

      // Create a list of the packages to iterate over.
      //
      HashSet packageNames = new HashSet();
      ClassDoc[] cda = initialRootDoc.classes();
      for (int i = 0; i < cda.length; i++) {
        ClassDoc cd = cda[i];
        // Only top-level classes matter.
        //
        if (cd.containingClass() == null) {
          packageNames.add(cd.containingPackage().name());
        }
      }

      // Packages
      //
      for (Iterator iter = packageNames.iterator(); iter.hasNext();) {
        String packageName = (String) iter.next();

        // Only process this package if either no "docpkg" is set, or it is
        // included.
        //
        if (packagesToGenerate == null
            || packagesToGenerate.contains(packageName)) {
          PackageDoc pd = initialRootDoc.packageNamed(packageName);
          process(pd);
        }
      }

      endln();
    } catch (Exception e) {
      e.printStackTrace();
      initialRootDoc.printError("Caught exception: " + e.toString());
    }
  }

  private void processSeeTag(SeeTag seeTag) {
    String ref = null;
    ClassDoc cd = null;
    PackageDoc pd = null;
    MemberDoc md = null;
    String title = null;

    // Check for HTML links
    if (seeTag.text().startsWith("<")) {
      // TODO: ignore for now
      return;
    }
    // Ordered: most-specific to least-specific
    if (null != (md = seeTag.referencedMember())) {
      ref = getId(md);
    } else if (null != (cd = seeTag.referencedClass())) {
      ref = getId(cd);

      // See if the target has a title.
      //
      Tag[] titleTag = cd.tags("@title");
      if (titleTag.length > 0) {
        title = titleTag[0].text().trim();
        if (title.length() == 0) {
          title = null;
        }
      }
    } else if (null != (pd = seeTag.referencedPackage())) {
      ref = getId(pd);
    }

    String label = seeTag.label();

    // If there is a label, use it.
    if (label == null || label.trim().length() == 0) {

      // If there isn't a label, see if the @see target has a @title.
      //
      if (title != null) {
        label = title;
      } else {
        label = seeTag.text();

        if (label.endsWith(".")) {
          label = label.substring(0, label.length() - 1);
        }

        // Rip off all but the last interesting part to prevent fully-qualified
        // names everywhere.
        //
        int last1 = label.lastIndexOf('.');
        int last2 = label.lastIndexOf('#');

        if (last2 > last1) {
          // Use the class name plus the member name.
          //
          label = label.substring(last1 + 1).replace('#', '.');
        } else if (last1 != -1) {
          label = label.substring(last1 + 1);
        }

        if (label.charAt(0) == '.') {
          // Started with "#" so remove the dot.
          //
          label = label.substring(1);
        }
      }
    }

    if (ref != null) {
      begin("link", "ref", ref);
      text(label != null ? label.trim() : "");
      end();
    } else {
      initialRootDoc.printWarning(seeTag.position(),
          "Unverifiable cross-reference to '" + seeTag.text() + "'");
      // The link probably won't work, but emit it anyway.
      begin("link");
      text(label != null ? label.trim() : "");
      end();
    }
  }

  private void processTags(Tag[] tags) {
    for (int i = 0; i < tags.length; i++) {
      Tag tag = tags[i];
      String tagKind = tag.kind();
      if (tagKind.equals("Text")) {
        text(tag.text());
      } else if (tagKind.equals("@see")) {
        processSeeTag((SeeTag) tag);
      } else if (tagKind.equals("@param")) {
        ParamTag paramTag = (ParamTag) tag;
        beginln("param");
        begin("name");
        text(paramTag.parameterName());
        end();
        begin("description");
        processTags(paramTag.inlineTags());
        end();
        endln();
      } else if (tagKind.equals("@example")) {
        ExtraClassResolver extraClassResolver = getExtraClassResolver(tag);
        SourcePosition pos = LinkResolver.resolveLink(tag, extraClassResolver);
        String source = slurpSource(pos);
        begin("pre", "class", "code");
        beginCDATA();
        text(source);
        endCDATA();
        endln();
      } else if (tagKind.equals("@gwt.include")) {
        String contents = ResourceIncluder.getResourceFromClasspathScrubbedForHTML(tag);
        begin("pre", "class", "code");
        text(contents);
        endln();
      } else if (!standardTagKinds.contains(tag.name())) {
        // Custom tag; pass it along other tag.
        //
        String tagName = tag.name().substring(1);
        begin(tagName);
        processTags(tag.inlineTags());
        end();
      }
    }
  }

  private void text(String s) {
    pw.print(s);
  }
}