On 2/26/14, 6:26 AM, Mark Thomas wrote: > 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.
+1 Phil > > Mark > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
