I just found that we could put class diagrams in javadoc.
I tried this on a few package level diagrams, in branch class-diagrams-in-javadoc.
It involves putting the plantuml source files in a doc-files directory in the same structure as the source files, in a new src/main/plantuml tree. Perhaps we could just put these doc-files directories directly alongside sources in the src/main/java tree (the plugin will collect them using the .puml extension), but I guess the compilation would also copy the files when creating the binary, which would just clutter everything, so having just another parallel tree like we already have src/main and src/test is probably acceptable.
I changed the maven-plantuml-plugin to a new one that seems maintained (despite the version number is less than the one we used; same name, different maintainer, different numbers), with two configurations: one for the regular diagrams we have in the site for the global architecture, one for the javadoc. The configuration for javadoc runs automatically before compilation, as it is bound to the generate-sources phase (the other one is bound to the pre-site phase).
It seems to work. Unfortunately, I was not able to have my IDE use it when rendering the javadoc within the editor. Perhaps there is a way to do it, I may try again later on.
For my preliminary tests, I just copied existing class diagrams for attitudes, orbits and time packages (only at packages level, not for classes javadoc). You will have to run a mvn javadoc:javadoc command by yourself to see the result. If we merge this in develop, everyone will be able to see it in the javadoc of the development version (that would be great to point forum users there).
The pros are that it could be a nice addition to the library, helping users understand the global architecture (and perhaps developers too, especially if we can have our IDEs use these images as we code). The cons are that putting all class diagrams for all packages would be a very long and painful task, it clearly will add to the burden.
What to you think?
