Skip to main content

The Javadocs are coming - and that's good!

Posted by pelegri on March 6, 2005 at 9:06 PM PST

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.