It is currently not possible to build javadoc for all modules in a suite. This is a major limitation for those of us
who are building platforms derived from the NetBeans platform for application development.
Currently the netbeans.org nbbuild scripts have support for creating exactly what I'd like to build. They can produce a
complete cross-linked documentation set describing the API for the entire platform. Tim and I called Jesse Glick on the
evening of 10-17-2007 to discuss merging these into the default build harness somehow; Jesse agreed it would be nice,
but indicated that these scripts are fragile.
Tim worked on merging the javadoc tools from nbbuild into the build harness while working with me last week and seemed
to have gotten close to having this complete, but I failed to get a copy of this before he left.
As a side note, I have learned that Maven can merge multiple sets of Javadoc by using the 'aggregate' attribute:
I'm not suggesting using Maven instead of Ant; this is just a reminder to me to look at how they're doing it.
Would be pretty easy (I think) to add a target to suite.xml that just runs Javadoc over all source files in all modules.
This would include packages not marked as public. Whether that would be a feature or a bug, I don't know.
FWIW, it's pretty easy to write a sort-of foreach task to do all modules. The hard thing is excluding non-public packages Not horrifically hard, though. I
wrote an extremely crude version of the above in the platformx repository - just creates an index page with all the available APIs. It wouldn't be that hard to
write an improved doclet that embeds it in the top-level frameset - definitely what is currently done with XSLT for platform javadoc is vastly more complex
and messy than a custom doclet would be. And I think people building on the platform know they're in for something that requires some customization, so
the worries about custom tasks or doclets are acceptable - certainly preferable to the gangleon of gobbledygook that generates the current NB API docs.
On this same note, Javadoc for library modules is important for us, as we're building a derivative platform and the
library modules are part of our platform's public API.
I followed Jesse's advice to me from the dev@openide list about how to handle them by overriding the build-javadoc
target in the wrapper module's build.xml so that the Javadoc gets copied into the correct place for the build (I'm
using the nbbuild scripts rather than the harness build scripts). They get packaged up with the javadoc ZIP file, but
for some reason they are not merged or cross-linked with the rest of the Javadoc (as they are for my source modules).
I did not have a chance to track down why, but my workaround in the meantime was to add an Ant replace target to my
build that adds a list of library wrapper modules with links to javadoc for each.
Guys any news on this. I am trying to create a similar target my self. I am just after a target which will create
javadoc for my entire project based on the platform including all packages even those marked as private. This would be a
really useful feature.