jLuger.de - Custom javadoc

In the current JavaMagazin is an article about SOPlets. There the mention the principle of Single Source of Truth (SSoT) where every information is only stored at one place. I liked the idea because it seems avoids redundancy which makes maintenance difficult. On the other side I've feared that it will be difficult to implement. Well, right a few days after reading the article I was confronted with SSoT in one of my projects. I had to create a documentation of our database schema for a privacy policy review. Of course we had done an extensive documentation but it was in the javadoc of our JPA POJOs.

My first approach was to make a copy&paste from the javadoc to a word file. While I was wondering whether I should take the javadoc from the source code or the generated HTML javadoc I remembered two things: SSoT and that you can format the output of the javadoc tool via custom Doclets.

With the help of the Doclet overview and the Doclet API I was able to extract all information about our database schema in format that I could easily paste into a word document without any extensive post formating. While it did the job I have to say that it wasn't the time save as I expected it. The fine tuning and output correction took a loot of time. So when you are sure that you need to extract information only once and/or your javadoc isn't very consistent you better do manual extraction (and pray that you don't need to maintain the document).

Lessons learned:

• I've tried to create ASCII output that could be pasted into an Office file but the javadoc in the source code was prepared to be embedded into HTML pages. Getting all the replacements and formatting right took a lot of time. I think I would have been faster when I've had focused on creating a HTML page that would have been correctly formatted.
• When you want to get all the private fields of a POJO you have to call the method fields(false) on ClassDoc.
• When you want to check if there is a certain annotation call annotations() (available for all elements that can have annotations) and then get for each AnnotationDesc the AnnotationTypeDoc via annotationType(). From the TypeDoc you can get the qualified name.
• When you need to get the name of a value in an annotation (e.g. the name in the JoinColumn) you need to call elementValues() in AnnotationDesc. For each pair you can get the name of the element and when you have the right pair just get the value.