Hi Kristian,
I would vote for binding @since tags to Derby release vehicles, e.g.,
"10.4.2.0". I'm hoping that we will not have to tie time in a knot again
the way that we did when we released 10.2. This means that the JDBC
expert group will need to uncouple their future JSRs from the master
JSRs of the JDK. That, in turn, will result in the following sequence of
events:
1) The JDBC expert group publishes the final spec for its next JDBC version.
2) Apache produces a Derby distribution which supports the new JDBC version.
3) Later on, a new JDK is released which incorporates the new JDBC version.
In this situation it does not make sense to me that @since should refer
to either the JDBC version or the JDK version. That is because the Derby
changes turn up some time after the JDBC spec is finalized and some time
before the JDK is released.
That, at least, is what makes sense to me.
Regards,
-Rick
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.
There are only a few existing @since tags in the code base, so we have
the opportunity to correct the course early on.
regards,
