[Java SDO CTS] Ensuring and documenting spec coverage

[kelvin goodson <ke...@gmail.com>]

As we are reorganising the CTS right now, how about we begin put a small
javadoc comment on test classes and if appropriate on test cases with a link
to the page of the spec that the class/test case refers to.  For example
that can be done with the pdf that is on the OSOA website using the #page=XX
syntax

/**
* commentary text
* @see <a href="
http://osoa.org/download/attachments/36/Java-SDO-Spec-v2.1.0-FINAL.pdf?version=1#page=20
">3.1.10 Property Indexes</a>
*/

That way we could do a bit of searching on our java files to see whether
tests are already in pace to cover certain cases.  It's not ideal in that it
would be better to link to the sections themselves,  but I don't think the
PDF that's in place supports that.  I don't think that this would be a great
maintenance issue when we come to a new spec revision,  as we could just
update the things that change between revisions (like the JDK convention of
"since 1.4.2").

Perhaps we'd want to include the PDF in the CTS source hierarchy to avoid
the brittleness of relying upon the OSOA file staying exactly where it is.

If we did this then we would start to build up some nice javadoc
documentation that would be part of a CTS release.  Just adding a bit of
commentary into the existing package.html files would probably see us
covered for release documentation.

Thoughts?

Kelvin.