db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <Richard.Hille...@Sun.COM>
Subject Re: @since tags in Derby code
Date Fri, 03 Oct 2008 14:25:34 GMT
Hi Kristian,

I would vote for binding @since tags to Derby release vehicles, e.g., 
"". 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 

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.


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 
> 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,

View raw message