What are Taglets? You may recognise Taglets in JavaDoc as the text denoted by the @ symbol, and they come in two flavours, standalone Taglets such as the @param and @return tags, and inline Taglets such as {@link mylink} denoted by the curly braces.
When writing javadocs you may come across the need to implement your own customised Taglets, for our documentation specifically we required a Taglet to display snippets of example code directly from source files.
Our motivation for this Taglet stemmed from the way code snippets are usually included in Javadocs (i.e copied into the html of Javadocs), as a consequence coders often forget to update the examples presently in documentation when they update their code, or sometimes simply write examples that don’t compile. By having the Taglet copy the code examples as text from source, we stop the example code from stagnating and improve documentation by providing up to date, working examples.
Our first bet was that someone had already written this, but surprisingly there wasn’t any code tailored to our needs, so we went ahead and wrote one ourselves.
The Taglet interface
The first step in building one’s own custom Taglet is to understand the Taglet interface. The API documentation does a decent job of running you through both standalone and inline tag implementations. Essentially the interface is a glorified toString method; it expects tag text, does something with it and spews it back out again.
The rest of the Taglet interface is a series of methods that return Boolean values denoting where the Taglet can appear, e.g in the method, the overview e.t.c
For our implementation we wanted to pass a relative path to the inline tag “snippet” as such:
{@snippet com/caplin/datasource/example/Example.java}
Our Taglet parses the text of the inline tag and turns the relative path to an absolute path, this is a simple concatenation of a static root folder path + the relative path (more on this later). The source file is then read in, formatted for html and sent back to javadocs to handle.
Generating javadocs with your custom Taglet
Your custom class requires the use of the java tools library from within your JDK. This makes it somewhat awkward to add to a project, especially if you are running a build that generates JavaDocs and you don’t particularly fancy adding in a dependency to tools.
The quick and easy way would be to compile your custom Taglet as in the above link, and then generate JavaDocs from cmd line with the location of the custom Taglet class file as a parameter. Since we generate JavaDocs ala Maven however, we set about configuring the JavaDoc plugin for that.
Initially we published a jar of the custom Taglet to artifactory with a dependency to the java home of the user compiling the code (see How do I include tools.jar in my dependencies?). That solved the awkward dependency on tools.
Next we had maven pick up the jar during build time and use our custom Taglet class. There are examples of how to do this on Maven’s documentation, none of which worked for us sadly. After much searching we came across a JIRA from 2008 with a code example that did work.
Constraints
Our current Taglet requires you to add your snippet code to a package inside the javadoc/examplesnippets folder of your project, otherwise it will not be able to parse the snippet source files. This is due to a static reference to that folder. We initially intended to pass the root folder of the snippet code as a system property, however Maven proved to be difficult in that respect and after much deliberation we are going to let this one simmer gently on the back-burner until a cleaner solution emerges.