Friday, March 9, 2012

Vdldoc - The Facelets .taglib.xml generator

VDL documentation

For the new OmniFaces project we would of course also like to generate VDL documentation so that at least the developers have a good reference about all available tags and functions. The API javadocs were no problem, just the existing Java 7 javadoc tool was sufficient. It generated nice documentation in Java 7 javadoc look'n'feel.

But there was no documentation generator for Facelets .taglib.xml files.

I looked at how JSF guys did it. They just used old style JSP .tld files and have not yet migrated to .taglib.xml files. They used the old JSP TLDDoc generator which was previously available at http://taglibdoc.dev.java.net, but is now nowhere available anymore (the JARs are of course still available at online code repositories). I looked at how RichFaces guys did it. They have .taglib.xml files only, but managed to have TLDDoc-generated tag documentation. I think they were using modified XSL templates for TLDDoc. I looked at how PrimeFaces did it, but it has only a PDF file which is at its own very nice but pretty a lot of work.

As to existing projects, there seems to be only a facelet-doc project on java.net, but it was not obvious how to use it and the project seems to be still unfinished and have bleeded to death.

Vdldoc!

So I decided to fork TLDDoc and rewrite the source code and XSL templates to be able to parse Facelets .taglib.xml files and generate real VDL documentation in nice Java 7 look'n'feel. And Vdldoc was born!

Hopefully it was worth the effort. I have also tested it on PrimeFaces and RichFaces .taglib.xml files and it has generated very nice docs for them :)