readme.txt

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

		    Javadoc Inverted Index Doclet
			     Version 0.1
	    ==============================================

Overview 
--------

The reverseIndexDoclet is  Java 2 doclet to create an inverted index of
class descriptions.  It is written to work with the Java 2 Javadoc
generator (JDK 1.2.1 and later).

When you use the doclet, as described below, it will generate a set of
HTML files in the specified output directory: InvIndex.html, InvIndexHelp.html,
InvIndexConcord.html, and InvIndex-X.html for each letter X for which a word
appears in the inverted index.  These files will normally contain links to
full Javadoc documentation, which must be specified when you execute the
doclet.


Compiling the Doclet
--------------------

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

This doclet makes very heavy use of the JFC collections framework,
and thus requires JDK 1.2.0 or later to compile.


Using the Doclet
----------------

To generate an inverted index of some Javadoc documentation, you 
must have the source code with embedded Javadoc-style comments.
You cannot use this doclet, or any doclet, without the relevant
Java source code.

To invoke this doclet, run the Javadoc tool as described
below.  You can use any of the normal Javadoc options, as
described at this URL:

http://java.sun.com/products/jdk/1.2/docs/tooldocs/solaris/javadoc.html

You can also use the following options that this doclet
supports specially.

  -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, assuming your AWT source code is in the
directory d:\jdk1.2.2\src, do this:

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 

Note that you may also specify command-line arguments to Javadoc in
a command-line file.  Specify a command-line file using the prefix
@, as shown below.

        javadoc -doclet reverseIndexDoclet @options.txt



Known Bugs and Limitations
--------------------------

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.

Javadoc is prone to running out of memory when invoked on very large
amounts of source code (e.g. the entire JDK 1.3).  If you actually
have enough memory, you have to use Javadoc's -J option to tell the
underlying JVM that it can be an even worse memory hog than usual.


For more information on this applet, contact Neal
Ziring, [e-mail].