db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kristian Waagan <Kristian.Waa...@Sun.COM>
Subject Re: @since tags in Derby code
Date Mon, 06 Oct 2008 08:53:39 GMT
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

Mime
View raw message