I'm slowly coming to realise just how much Sun seemed to like the "let" suffix. We have applets, servlets, midlets, Xlets - and just as I think I'm running out, I discover doclets and taglets!
It all started when, for our final year project, we decided to use the convention of an "@qa" annotation with a set format in the javadoc at the start of each class file to document who had QAed the file and when. It works well just as is (and this is how we were intending to leave it) but a part of me couldn't help but get slightly annoyed at the copious amounts of javadoc warnings this produced. I wondered if there was a way to not just shut javadoc up, but to sensibly extend it so it knew about this extra tag and could write out some meaningful information to the resulting HTML.
Although this is rather poorly documented, it turns out it can, and it's really quite nice to use. Initial searching led me here, which provides a brief overview about taglets (but enough to get started.) Essentially, you need to define a class that conforms to the com.sun.javadoc.Tag interface, create a static register method with a fixed definition, then inform Javadoc about the location of the taglet with the
I would publish code, but since what I've done forms part of our final year project it could potentially open up plagarism disputes which isn't a road I want to go down! If I revisit it after my degree then I'll post up another example, along with code.
In terms of integrating it with Netbeans, I had to override the Javadoc ant task to get it working properly (since it needs to compile the taglet and know the absolute path for the taglet path) but after that it worked very nicely indeed.
Should I see the need for extra Javadoc tags again, I'll definitely think of this - documentation is poor so there's a through hoops to jump through first, but once you know how it really is pretty easy to set up and use.
It all started when, for our final year project, we decided to use the convention of an "@qa" annotation with a set format in the javadoc at the start of each class file to document who had QAed the file and when. It works well just as is (and this is how we were intending to leave it) but a part of me couldn't help but get slightly annoyed at the copious amounts of javadoc warnings this produced. I wondered if there was a way to not just shut javadoc up, but to sensibly extend it so it knew about this extra tag and could write out some meaningful information to the resulting HTML.
Although this is rather poorly documented, it turns out it can, and it's really quite nice to use. Initial searching led me here, which provides a brief overview about taglets (but enough to get started.) Essentially, you need to define a class that conforms to the com.sun.javadoc.Tag interface, create a static register method with a fixed definition, then inform Javadoc about the location of the taglet with the
-taglet and -tagletpath parameters. The Java class you create is like any other and has access to the line, column and file that the tag is in as well as all its text. So you can easily integrate it with your main program if you wish!I would publish code, but since what I've done forms part of our final year project it could potentially open up plagarism disputes which isn't a road I want to go down! If I revisit it after my degree then I'll post up another example, along with code.
In terms of integrating it with Netbeans, I had to override the Javadoc ant task to get it working properly (since it needs to compile the taglet and know the absolute path for the taglet path) but after that it worked very nicely indeed.
Should I see the need for extra Javadoc tags again, I'll definitely think of this - documentation is poor so there's a through hoops to jump through first, but once you know how it really is pretty easy to set up and use.
Comments
Post a Comment