Javadocs – Custom Taglets & Stylesheets
There comes a point in every developers life when you’re asked:
“So, Mr. Smart Developer, what documentation can you provide for the application you’ve just written?”
which is more often than not, superseded by a minimum of 5 seconds of silence, which ultimately betrays you by effectively answering “Erm…None” without you having to even mutter a word!
Never fear, because the good thing is, you can now eliminate that 5 seconds of silence, regain your lost integrity and answer: “Yeah of course, we have Javadoc documentation”.
In this post, I’ll show you how to:
- Use the maven-javadoc-plugin to generate your API documentation
- Write your own annotations, and have them incorporated into the documentation
- Use a custom CSS stylesheet to inspire and awe your readers(Okay, maybe not inspire, but it will definitely look a lot better)
Before we set off, it might be a good idea for you to download the sample at the bottom of this post, and have it open, so that its easier to follow while reading.
As you know, from my previous post, I’m rather new to this Java realm, and one of the aspects, or more correctly, tools, I’ve really grown to love, is Maven. This framework, has made my life that much easier, and I have to say, I think the .NET world could really do with something like this!
So, with that in mind, its no surprise that I’m going to use the maven-javadoc-plugin plugin to generate my Javadoc documentation. This is a really easy tool to setup, but first, lets talk about taglets.
Lets say we have a sample class called GetCarModelsCommand. This class has some default Javadoc annotations, but there are two custom ones called @sap.dependency and @should. The purpose of the @sap.dependency is something we use in our API documentation to see what SAP Function Modules our code relies on, and makes it easy to search for that function module name, and at a quick glance you can see which other classes rely on this particular function module. As for the @should, we use this typically to document at the public API level, and describes how the service method should behave (i.e. in line with BDD). For an example, look at the GetCarModelsCommand class in the javadocs project.
To enable these taglets to be rendered correctly in the documentation, you need to create your own custom class, and implement the Taglet interface, which you’ll find inside the com.sun.tools.doclets package.
<pause>
Now, I guess this is a good place to mention that trying to find where or how to reference the necessary package so that you can implement the Taglet interface is about as easy as eating soup with a toothpick – it’s time consuming, and will just frustrate you. It’s not very apparent which package to import or which GAV to use, but if you take a look at the pom.xml under the taglets project, you notice a section under profiles. I learnt a new thing about profiles when I eventually stumbled across this gem. You can automatically include dependencies listed inside a profile, based on any properties declared in the activation section, whose property name equals the value stipulated in this section. So in this case, Maven (have I said I love Maven already?) will look up the java.vendor property, and will find it in the JVM, and it’s value will equal the value "Sun Microsystems Inc.", and will automatically download the dependencies listed! Very neat!
</pause>
Anyway, back to the Taglet. The main things to note when implementing this interface, is that you need to return true/false for wherever this tag is allowed to be used, and also a textual description of the name, as well as overriding the toString() method to provide the HTML to be rendered on screen. An example of the @should and @sap.dependency taglets can be found in the taglets project.
The next thing to consider is how to include these taglets, but in order to do that, you need to know how to configure the maven-javadoc-plugin in your POM file. The very basic configuration required can be found in the pom.xml in the builder project.
This plugin is typically declared in the <reporting/> section, however, we’re going to declare it in the <pluginManagement/> section for now. You’ll see more of my reasoning of this in my next post about including UML generated graphs in your javadocs.
In addition to also defining where maven-javadoc-plugin should get our new custom CSS stylesheet, you’ll also notice that we’ve declared the taglets, and a <tagletArtifact/>. The reason for this tagletArtifact is to demonstrate the ability to house these taglets in a central core library, which can be built and stored in a central repo, and by doing so you can be sure you’re always using the correct version of the library which has the relevant taglet classes, and the added advantage is, that you can use them in more than one project. Be sure to include the full package and class name when defining the taglet, as you can see in the <tagletClass/>.
All that’s left now is to configure the maven-javadoc-plugin in the <reporting/> section. Again, refer to the pom.xml in the builder project.
Declaring it like so, only works because we’ve already declared and configured it in the <pluginManagement/> section. The <reportSets> allows for the plugin to run at the “aggregate” goal only. <reportSets> can prove to be really useful if you need different configuration for different goals.
That about sums up all that you need to do in order to have your own custom Javadoc definitions, and a custom stylesheet. I know I didn’t really touch much on the stylesheet side of things, but all you really need to do is look at the default CSS stylesheet that was included with the default Javadoc generation, and modified it to include your own branding. You can see in the attached sample, how I’ve included a stylesheet into the document generation.
Once you have everything setup and configured, all you need to run is: mvn clean install javadoc:aggregate, and your documentation will be generated at the target folder under the builder project. This might be obvious, but the reason for the install goal is to compile the taglets project, and install it into your local repo, so that the builder project can correctly reference it.
Stay tuned for my next post which will demonstrate how to incorporate UML diagrams into your documentation. It can be a real help, especially if you have a big project, which requires this type of documentation, but it never really existed at the outset.
