commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: [DBCP] @since markers for 2.0 release
Date Wed, 26 Feb 2014 16:53:15 GMT
On 26 February 2014 14:26, Mark Thomas <markt@apache.org> wrote:
> On 26/02/2014 13:46, Matt Benson wrote:
>> On Feb 26, 2014 4:35 AM, "Gilles" <gilles@harfang.homelinux.org> wrote:
>>>
>>> On Wed, 26 Feb 2014 10:30:00 +0000, Mark Thomas wrote:
>>>>
>>>> I'm wondering what to do about @since markers. As DBCP2 is in a
>>>> completely new package, arguably everything is new for this release. The
>>>> existing @since markers don't make a lot of sense. Therefore, I am
>>>> currently considering removing all @since markers from the code base.
>>>> They would then be used from the next release to indicate what had
>> changed.
>>>>
>>>> Thoughts?
>>>
>>>
>>> In Commons Math, we kept the markers referring to the older major
>> versions,
>>> even though the packages have changed twice already.
>>>
>>
>> My inclination in general is to follow the example Gilles provides from CM
>> unless, for instance, the API has been completely rewritten.
>
> The API hasn't been completely re-written but there have been some
> extensive changes. I temporarily changed the package back to dbcp and
> ran clirr. It reported 242 errors (and 214 infos). That is a fair amount
> of breakage and it varies all the way from a package that has been
> entirely removed to a protected field being made final.
>
> And that doesn't include the fields whose meaning has changed between
> 1.x and 2.x.
>
> I'm still leaning towards removing the @since tags. My main reason for
> this is that, if they are left in, users are left with an incomplete
> impression of what changed from 1.x to 2.0. I'd much rather start afresh
> in 2.0 and use @since to document what has changed from 2.0 onwards.

The JDK uses @since JDK1.0 for original classes.

I agree with dropping @since 1.x markers, but think it would be
helpful to start with @since 2.0 in all classes.

> Mark
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message