reverseindexdoclet.java

This code sample shows how to write a simple Javadoc 1.2 Doclet. Used with Javadoc, it can generate

/**
 * <pre>
 * A Java 2 doclet to create an inverted index of
 * class descriptions.
 * 
 * To compile this doclet, use the following on Unix:
 * javac -classpath .:${JAVAHOME}/lib/tools.jar reverseIndexDoclet.java
 * 
 * or the following on Windows:
 * javac -classpath .;%JAVAHOME%\lib\tools.jar reverseIndexDoclet.java
 * 
 * To generate an inverted index of some documentation, use the
 * normal Javadoc options, plus the following:
 *   -base <url>       Base URL for real JDK 1.2 documentation to link
 *                     into (e.g. http://java.sun.com/jdk1.2/docs/api)
 *
 *   -title <ttl>      Use this string as a title for these docs
 * 
 *   -d <dir>          Output directory
 *
 * For example, to generate an inverted index of the AWT
 * documentation:
 * 
 * javadoc -doclet reverseIndexDoclet  -d awt
 *         -title AWT -sourcepath d:\jdk1.2.2\src
 *         -base http://java.sun.com/products/jdk/1.2/docs/api
 *         java.awt.color java.awt.datatransfer java.awt.dnd 
 *         java.awt.event java.awt.font java.awt.geom java.awt.im 
 *         java.awt.image java.awt.print 
 *
 * This doclet always creates two files InvIndex.html and 
 * InvIndexConcord.html.  It also creates one file per
 * letter of the alphabet that actually occurs in the 
 * input, of the form InvIndex-X.html.  
 *
 * This doclet has a number of fairly serious limitations.
 *   1. It works only for English
 *   2. The list of words to ignore is fixed in InvertedIndex.java
 *   3. The mapping from class names to real documentation is also
 *      fixed, set up for the Java 2 standard doclet output format.
 *   4. Handling of encoded HTML entities is somewhat incomplete
 *      and clumsy.
 *
 * For more information on this applet, contact Neal
 * Ziring, [e-mail].
 * </pre>
 */

import com.sun.javadoc.*;
import java.util.*;
import java.io.*;


public class reverseIndexDoclet {
    public static final String nameAndVersion = "Inverted Index Doclet 0.1";

    static String    realDocUrlBase = "/api";
    static String    titleString = "";
    static File      outputDir;
    static ArrayList docs;

    private static void readOptions(String[][] options) {
             String tagName = null;
	     System.out.println("Length of options is " + options.length);
             for (int i = 0; i < options.length; i++) {
                 String[] opt = options[i];
		 System.out.println("Got option " + opt[0]);
                 if (opt[0].equals("-base")) {
                     realDocUrlBase = opt[1];
		     System.out.println("Real docs base URL is: " +
					realDocUrlBase);
                 }
		 else if (opt[0].equals("-d")) {
		     outputDir = new File(opt[1]);
		     System.out.println("Output directory is: " + outputDir);
		 }
		 else if (opt[0].equals("-title")) {
		     if (titleString.length() == 0) {
			 titleString = opt[1];
		     } 
		     else {
			 titleString = titleString + " " + opt[1];
		     }
		 }
             }
	     return;
    }

    public static int optionLength(String option) {
             if(option.equals("-base")) {
                 return 2;
             }
             if(option.equals("-d")) {
                 return 2;
             }
             if(option.equals("-title")) {
                 return 2;
             }
             return 0;
    }

    public static boolean start(RootDoc root){
	// phase 0 - grab the options we need
	docs = new ArrayList(1000);
	outputDir = new File(".");
	readOptions(root.options());

	// phase 1 - extract the package and class descriptions
	int cnt = 0;
	cnt += extractDescriptions(root.classes(), root);
	// cnt += extractDescriptions(root.specifiedPackages(), root);

	// phase 2 - build the inverted index
	root.printNotice("All classes processed, about to build inverted index.");

	if (titleString.length() == 0) 
	    titleString = "Java";
	InvertedIndex ii = new InvertedIndex(titleString);
	ii.process(docs, root);
	
	// phase 3 - output the inverted index
	root.printNotice("Inverted index built, about to start output.");
	boolean wrote = ii.writeOutput(root, outputDir, realDocUrlBase, root);
	if (!wrote) {
	    root.printWarning("Unable to write output to " + outputDir);
	}

	// phase 4 - all done
	root.printNotice("All done.");
	return true;
    }

    private static int extractDescriptions(Doc [] items, DocErrorReporter rep)
    {
	int ret;
	RiEntry r;
	for(ret = 0; ret < items.length; ret++) {
	    if (items[ret] instanceof ClassDoc) {
		ClassDoc cd = (ClassDoc)(items[ret]);
		r = new RiEntry(cd.qualifiedName(), cd);
	    }
	    else {
		r = new RiEntry(items[ret].name(), items[ret]);
	    }
	    docs.add(r);
	}
	return ret;
    }

    static final String encodings[][] = {
        { "&", "&amp;" },
        { "\"", "&quot;" },
        { "<", "&lt;" },
        { ">", "&gt;" },
    };

    static String decode(String s) {
	int ix, p;
	for(ix = 0; ix < encodings.length; ix++) {
	    while((p = s.indexOf(encodings[ix][1])) >= 0) {
		s = s.substring(0,p) + 
		    encodings[ix][0] + 
		    s.substring(p + (encodings[ix][1]).length());
	    }
	}
	return s;
    }

    static String encode(String s) {
	int ix, sx, p;
	sx = 0;
	for(ix = 0; ix < encodings.length; ix++) {
	    while((p = s.indexOf(encodings[ix][0], sx)) >= 0) {
		sx = p + (encodings[ix][0]).length();
		s = s.substring(0,p) + encodings[ix][1] + s.substring(sx);
	    }
	}
	return s;
    }

    /*
    private static void writeContents(ClassDoc[] classes, String tagName) {
             for (int i=0; i < classes.length; i++) {
                 boolean classNamePrinted = false;
                 MethodDoc[] methods = classes[i].methods();
                 for (int j=0; j < methods.length; j++) {
                     Tag[] tags = methods[j].tags(tagName);
                     if (tags.length > 0) {
                         if (!classNamePrinted) {
                             System.out.println("\n" + classes[i].name() + "\n");
                             classNamePrinted = true;
                         }
                         System.out.println(methods[j].name());
                         for (int k=0; k < tags.length; k++) {
                             System.out.println("   " + tags[k].name() + ": " 
                                 + tags[k].text());
                         }
                     } 
                 }
             }
         }
    */
}