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"; }
newMethod
public java.lang.String newMethod()
- Returns:
- value
- Table(s):
employee firstname lastname address city country
/* * 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.