Java web applications based on JSP are traditionally bound to a great amount of redundancy in the development process:

• Tag classes must be kept up-to-date with the TLD by hand. This means a big deal of duplicate effort.
• For any non-trivial tag library, inheritance is a fact. In order to avoid replication in the TLD your libraries are bound to use XML entities, which is cumbersome and prone to error.
• IDEs are extracting JSP coding hints from the TLD file, which implies that the developer should be introducing the tag documentation into the TLD by hand.
• Since this documentation is already available in the javadoc, it implies maintaining duplicate documentation: java(doc) and TLD.
• Make it triple, if you want online HTML documentation.
• There is no way to document deprecated behavior.

TLDGen is a java library and a command line tool that generates the TLD file and HTML documentation from Java annotations. An example of generated HTML can be checked out here.

It can be used to create TLD files from scratch or to upgrade your existing web application to remove the hassle of maintaining these files by hand. In both cases the procedure is the same:

Using tldgen annotations

First, add tldgen.jar to your project dependencies. You can get it from the project downloads or use maven (group org.extrema-sistemas, artifact tldgen).

Once the jar file is included, you can add the annotations to any existing JSP tag class:

package com.acme.tags;

import org.tldgen.annotations.Tag;
import org.tldgen.annotations.BodyContent;
import org.tldgen.annotations.Attribute;
import javax.servlet.jsp.tagext.SimpleTagSupport;

@Tag(
	bodyContent=BodyContent.SCRIPTLESS,
	example="<p:customer name=\"John Doe\"/>"
)
public class CustomerTag extends SimpleTagSupport {

	/** The name of this customer */
	@Attribute
	private String name;

	/** 
	 * The id of the customer. This is not used anymore.
	 * @deprecated use name instead
	 */
	@Attribute
	private int id;

}

You can also annotate JSP function methods:

package com.acme.tags;

import org.loom.tldgen.annotations.Function;

public class Functions {

	private static Random random = new Random();

	/**
	 * Return a random number between 0 (inclusive) and the provided value (exclusive)
	 */
	@Function(example="${l:random(10)}")
	public static int random(int maxValue) {
		return random.nextInt(maxValue);
	}

}

Launch the tldgen tool

Now you should download the tldgen.zip file, install it somewhere and execute the command-line tool indicating the library data and the HTML and TLD file locations. For example, with Linux (all on the same line):

tldgen 
	-classpath 'lib/*' 
	-sourcepath src/main/java 
	-subpackages com.acme.tags 
	-tldFile src/main/resources/META-INF/acme.tld 
	-name acme 
	-uri http://acme.com/acme.tld 
	-htmlFolder build/docs/tlddoc

That's it. The list of available command line options is explained in the CommmandLine page.