The Javadocs are coming - and that's good!

One of the things that made Java popular is javadocs: a relatively simple way to combine documentation about the code in the code, together with a tool that generates web pages from there. Ideas like this had been around for a while - I tend to think of them as being under the literate programming umbrella, but I'm no expert in the field - but javadocs simplicity and generation of HTML pages was very succesful.

Javadocs are part of the specifications. In some cases the specs are written so they refer to the javadocs; in some other cases the specs include the javadocs directly. The latter was the approach we took with the JSP specs, where we directly generate the (framemaker) API chapters from the javadoc comments in the API files.

Because the javadocs are part of the spec, they are developed by the EG through the same JCP process as the specs. Which is why it is so important that we are seing more cases where the Expert Groups are deciding to release the javadocs in an ongoing manner, to keep the developer community informed of the evolution of the spec, and to encourage them to provide feedback.

This last week has seen two important javadocs released. The first are the javadocs for Mustang; the next version of J2SE. The javadocs can be browsed online and are companions to the binary snapshots and the source snapshots (I notice that the binary and source URLs have a "jdk6" in their URL; I think the javadoc should have one too).

The other set of javadocs are those for JAXB 2.0. Like for Mustang, we have the javadocs and a regular drops that include the javadocs, binaries and sources. We expect the JAX-RPC 2.0 project to do the same in the near future; a version of the binary was included in the technology release for the combined JAXB 2.0 and JAX-RPC 2.0 but the regular, ongoing drops for that technology have not yet started.

We are doing our part: we are going to be releasing to you regular drops of the implementations and the specs. We need you to download these, use them, and give us your feedback through the different feedback forums. For the case of JAXB 2.0 and JAX-RPC 2.0, use this forum. Mustang is asking for feedback through two forums; one for the snapshots, the other for Mustang itself.