On 03.10.08 18:52, Daniel John Debrunner wrote:
Kristian Waagan wrote:
Hello,
In a patch I worked on, I came across JavaDoc where the first line of
the method documentation was "JDBC 3.0". This looks a bit odd in the
generated JavaDoc, so I decided to replace it with a @since tag.
When reviewing the patch, Knut Anders raised the issue of which value
to use for the tag.
I used "1.4" - for Java 1.4, which was the release vehicle for JDBC 3.0.
Knut Anders suggests using a Derby version, for instance "Derby
10.4.2.0".
There seems to be several artifacts we could version against:
- Derby
- JDBC specification
- Java specification
It would be nice if the community could discuss the general usage of
@since tags, and also which values/versions to use with it.
Note that the tag value is "free form" - any text can be used.
Since the tag is free form and generally more information is better, I
would think that whichever specifications and/or versions that make
sense can be added, e.g.
@since Derby 10.4, JDBC 4.0
Dan.
Thanks to Rick and Dan for sharing their opinions.
I think using the Derby version as the primary value makes sense. Adding
the JDBC specification version also makes sense to me, since the
(observed) capabilities of a given Derby version can change depending on
the JDBC specification used in the runtime environment.
I have created DERBY-3899 to align the usage of existing @since tags.
The plan is to create a patch within a few days, waiting a bit to allow
others to have their say.
thanks,
--
Kristian
