While aiming at blueMarine 1.0 for the end of the year, the effort is being put not only to stability and performance, but also on cleaning up the APIs in order to have a polished and stable version that others might use.

To that end, I'm finding an excellent tool in the book "Practical API Design: Confessions of a Java Framework Architect" by Jaroslav Tulach (I've not finished it yet, I'll post a review as soon as I complete reading it), but my concern is also to write the proper documentation for users. One of the problems is with the UML diagrams - so far I've used the UML editor in NetBeans, but keeping them up-to-date is really time expensive, especially after some heavy refactoring.

Meera Subbarao and Geertjan Wielenga have written about a better solution (start reading this article on DZone): using a custom Javadoc doclet (UmlGraphDoc) to automatically generate the UML diagrams and put there in the generated javadocs (of course, you can even take the diagrams alone and reuse them on other documents). They explained the process in details with some examples about customizing build.xml, here I'm adding how the customization looks for a NetBeans RCP module; you just need to add this target to your script:

    <target name="-javadoc-with-packages" depends="build-init,-javadoc-init,netbeans" if="module.javadoc.packages">
        <mkdir dir="${netbeans.javadoc.dir}/${code.name.base.dashes}"/>
        <javadoc destdir="${netbeans.javadoc.dir}/${code.name.base.dashes}"
                 packagenames="${module.javadoc.packages}"
                 source="${javac.source}"
                 windowtitle="${javadoc.title}"
                 failonerror="false"
                 encoding="UTF-8">
            <classpath refid="cp"/>
            <sourcepath location="${src.dir}"/>
            <doctitle>${javadoc.title}</doctitle>
            <header>${javadoc.header}</header>
                    <doclet name="org.umlgraph.doclet.UmlGraphDoc"
                       path="${tools.dir}/UmlGraph-5.1/UmlGraph.jar">
                         <param name="-attributes" />
                         <param name="-operations" />
                         <param name="-qualify" />
                         <param name="-types" />
                         <param name="-visibility" />
                         <param name="-inferdep" />
                         <param name="-inferrel" />
                         <param name="-inferdepinpackage" />
                     </doclet>
        </javadoc>
      <apply executable="dot" dest="." parallel="false">
            <arg value="-Tpng"/>
            <arg value="-o"/>
             <targetfile/>
             <srcfile/>
             <fileset dir="." includes="*.dot"/>
              <mapper type="glob" from="*.dot" to="*.png"/>
      </apply>
    </target>

at this point, launching ant javadoc as usual will do the job, as the described target will just replace the one in the NetBeans RCP harness.

You can find a diagram example in context in the blueMarine javadocs and an inline example below. I'm pretty pleased with it, I just need to understand how to improve the layout - my packages have just a few classes (as it should be) and usually a few methods, but some get large boxes because of the signature of some method; also in some cases UmlGraphDoc includes in my diagram the whole description of some common classes such as String, but this is just something I can work on later. Much better than doing it by hand. BTW, Geertjan said that he will talk also about how to automatically generate a dependency diagram of the various modules in a NetBeans RCP application; also because, as Meera explained, you can put this stuff into Hudson and have the documentation automatically generate and published. Always up to date!

 

 

From http://weblogs.java.net/blog/fabriziogiudici/