 |
|
 |
 |
|
|
 
Kohsuke Kawaguchi's BlogPumping up javadoc: JAXB RI architecture documentPosted by kohsuke on August 03, 2005 at 09:56 PM | Comments (6)Good commenting always make it easier to understand the source code (although people have different opinions about what exactly is good comments.) As such, one of the things we've been doing is to make sure that the JAXB RI source code is well commented. This is mostly done by javadoc, which is good for describing lower-level details of the code. It's also nice for a project to have a higher-level documentation. It's like a map of the source code, which helps you understand the big picture and which part of the code you need to dive in to fix the problem at hand. This has been somewhat lacking in the JAXB RI for quite some time. We wanted to have such a high-level map of the JAXB RI source code. When we were working with 1.0.x, we tried a few StarOffice documents and a few HTML pages, but the problem is that it quickly gets out of sync. StarOffice documents have an additional problem of being binary files, which means if two people happen to be editing the same file, you are out of luck. HTML files are better in this respect, but it's hard to do pictures, which is very important for a high-level document. so I've been thinking about how to do it. Javadoc is nice in the sense that it's harder to get out of sync with the source code; thanks to modern IDEs, whenever you change the source code, references in javadoc are automatically updated. I liked this very much, so I decided to write high-level documents in terms of javadoc. The next problem was pictures. Because of those IDE support, it's nice if we can do pictures declaratively by writing text, instead of using a GUI tool (like Microsoft Visio.) In this way, class names in pictures will be updated, pictures can be diffed/merged, etc. GraphViz and UMLGraph are exactly such tools. So I wrote a little taglets which lets me write:
{@DotDiagram
digraph G {
"JAX-WS" [label="JAX-WS RI"];
// libraries
node [style=filled,color=lightblue];
XSOM; RNGOM; TXW; "DTD parser";
// modules
node [style=filled,color=lightpink];
XJC; CodeModel; runtime; schemagen; "XJC API"; "runtime API";
"JAX-WS" -> "XJC API" -> CodeModel;
"JAX-WS" -> "runtime API";
XJC -> XSOM;
XJC -> "DTD parser";
XJC -> RNGOM;
XJC -> "XJC API";
XJC -> CodeModel;
XJC -> runtime -> schemagen -> TXW;
runtime -> "runtime API";
}
}
... and have the following picture generated automatically: 
The similar javadoc tag allows me to write a sequence diagram declaratively, thanks to UMLGraph. Another customization I did to javadoc was to tweak the HTML generation. Normally, a package javadoc lists classes in it first, followed by a package description. A class javadoc lists some signature information first, then a class description. When I'm using a package or a class for a high-level documentation, I didn't like this order. It should just show my javadoc at the very top. Doing this turns out to be tricky, and eventually I was customizing the standard doclet. But in the end, I was able to get the desired layout. I defined @ArchitectureDocument tag to enable this custom layout So, with all that said, I hope you like our JAXB architecture document! Bookmark blog post:  del.icio.us  Digg  DZone  Furl  Reddit
CommentsComments are listed in date ascending order (oldest first) | Post Comment
| |
 java.net RSS Feeds
|
