On 26/02/2014 13:46, Matt Benson wrote: > On Feb 26, 2014 4:35 AM, "Gilles" <gil...@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. Mark --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
