Create a Taglet to document database access (Javadoc)Tag(s): Environment


Since JDK1.4, it is possible to create a taglet to be used with javadoc to customized the generated documentation.

This example implements a new javadoc tag to document which tables a class is dealing with. If a method interact with 2 tables, employee and address, then the javadoc tag

 /**
  *@table employee:firstname,lastname;address:city,country
  * @return value
  */
  public String newMethod() {
    return "yo";
    }
will be documented as

newMethod
public java.lang.String newMethod()
Returns:
value
Table(s):
employee
firstname
lastname
address
city
country
The "table" taglet source
/*
 * Table.java
 */

package com.rgagnon.taglet;
import com.sun.tools.doclets.Taglet;
import com.sun.javadoc.*;
import java.util.Map;
/**
 * This is a taglet to document tables and fields used by a classes
 * example : @table employee:lastname,firstname;address:city,country
 *
 * @author  Réal Gagnon
 */
public class Table implements Taglet{

    private static final String NAME = "table";
    private static final String HEADER = "Table(s):";

    /**
     * Return the name of this custom tag.
     */
    public String getName() {
        return NAME;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in field documentation.
     * @return true since <code>@todo</code>
     * can be used in field documentation and false
     * otherwise.
     */
    public boolean inField() {
        return false;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in constructor documentation.
     * @return true since <code>@todo</code>
     * can be used in constructor documentation and false
     * otherwise.
     */
    public boolean inConstructor() {
        return true;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in method documentation.
     * @return true since <code>@todo</code>
     * can be used in method documentation and false
     * otherwise.
     */
    public boolean inMethod() {
        return true;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in method documentation.
     * @return true since <code>@todo</code>
     * can be used in overview documentation and false
     * otherwise.
     */
    public boolean inOverview() {
        return true;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in package documentation.
     * @return true since <code>@todo</code>
     * can be used in package documentation and false
     * otherwise.
     */
    public boolean inPackage() {
        return true;
    }

    /**
     * Will return true since <code>@todo</code>
     * can be used in type documentation (classes or interfaces).
     * @return true since <code>@todo</code>
     * can be used in type documentation and false
     * otherwise.
     */
    public boolean inType() {
        return true;
    }

    /**
     * Will return false since <code>@todo</code>
     * is not an inline tag.
     * @return false since <code>@todo</code>
     * is not an inline tag.
     */

    public boolean isInlineTag() {
        return false;
    }

    /**
     * Register this Taglet.
     * @param tagletMap  the map to register this tag to.
     */
    public static void register(Map tagletMap) {
       Table tag = new Table();
       Taglet t = (Taglet) tagletMap.get(tag.getName());
       if (t != null) {
           tagletMap.remove(tag.getName());
       }
       tagletMap.put(tag.getName(), tag);
    }

    /**
     * Given the <code>Tag</code> representation of this custom
     * tag, return its string representation.
     * @param tag   the <code>Tag</code> representation of this custom tag.
     */
    public String toString(Tag tag) {
        String output = "";
        String tables [] = tag.text().split(";");
        int j = tables.length;
        if (j > 0) {
            output = "<DT><B>" + HEADER
               + "</B><DD><TABLE><TR>";
            for (int i=0; i < j ; i++){
                // deals with the current table and its fields
                String current[] = tables[i].split(":");
                output +=
                  "<TD><TABLE style=\"border-style:solid;"
                  + " border-width:thin\">";
                output +=
                  "<TH ALIGN=\"center\" STYLE=\"border-style:solid;"
                  + " border-width:thin\">"
                  + current[0] + "</TH>";
                if (current.length > 1) {
                    String fields[] = current[1].split(",");
                    int k = fields.length;
                    for (int n=0; n < k ; n++) {
                        output += "<TR><TD ALIGN=\"center\">"
                          + fields[n] + "</TD></TR>";
                    }
                }
                output += "</TABLE>";
            }
            output += "</TR></TABLE>";
        }
        return output;
    }

    /**
     * Given an array of Tags representing this custom
     * tag, return its string representation.
     * @param tags  the array of Tags representing of this custom tag.
     */
    public String toString(Tag[] tags) {
        if (tags.length == 0) {
            return null;
        }
        String result = "";
        for (int i = 0; i < tags.length; i++) {
            result += toString(tags[i]);
        }
        return result ;
    }
}

Compile your taglet. Use javac compiler version 1.4.0 (or later) in the Java 2 SDK. The required class files are in the lib\tools.jar file in the SDK. Assuming the SDK is installed at C:\Program Files\j2sdk1.4.1 :

javac -classpath "C:\Program Files\j2sdk1.4.1\lib\tools.jar"
     com\rgagnon\taglet\Table.java

Run the javadoc tool using the -taglet and -tagletpath options. For example, if your taglet class file is defined to be in package com.rgagnon.taglet and is stored in C:\taglets\com\rgagnon\taglet\Table.class, then you should set tagletpath to C:\taglets. This example calls javadoc on package com.package1, including Table taglet tags:

C:\dev\Work\java\taglet>javadoc -taglet com.rgagnon.taglet.Table
     -tagletpath c:\dev\work\java\taglet com.package1

Download this taglet here.


blog comments powered by Disqus