Our code style guide already says that you need to add @since tags to new public API methods. But maybe we should clarify some of the things you asked about - class vs. method, etc.
https://cwiki.apache.org/confluence/display/GEODE/Public+APIs -Dan On Wed, Apr 27, 2016 at 3:57 PM, Kirk Lund <[email protected]> wrote: > Do we know if the external user APIs are consistently marked with @since > tags? If only some of these APIs have @since tags then they don't have much > value. > > If we're going to keep these tags then we should keep them up-to-date and > have them consistently applied to all of our external user APIs. We should > then add it to our DOD and code style guidelines. If the DOD and guidelines > don't specify this then as developers add new classes and methods, we run > the risk of not consistently having them in place or in how they are used. > > For example, if I add a new class to the external user API, should I mark > all public methods with @since tags or just the class and what about > protected methods? > > -Kirk > > > On Tue, Apr 26, 2016 at 4:23 PM, Dan Smith <[email protected]> wrote: > > > I think they may be helpful in the public API - to be able to tell if you > > are using a feature that has been around for a while, or to realize what > > version you need to upgrade to in order to get a feature. > > > > -Dan > > > > On Tue, Apr 26, 2016 at 4:12 PM, Udo Kohlmeyer <[email protected]> > > wrote: > > > > > Just for my own curiosity... why do we need the @since tag? > > > What benefit does it provide the product/code? > > > > > > --Udo > > > > > > > > > On 27/04/2016 7:43 am, Dan Smith wrote: > > > > > >> It sounds like more people are in favor of Geode 1.0.0 and GemFire > > x.y.z, > > >> so I created bug GEODE-1316 to implement this change. > > >> > > >> -Dan > > >> > > >> On Mon, Apr 25, 2016 at 6:36 PM, Udo Kohlmeyer <[email protected] > > > > >> wrote: > > >> > > >> I must be honest that I've never been a supporter of the @since tag. > > Imo, > > >>> release notes and features should be the paper trail that we provide. > > >>> Also, > > >>> how would we handle a scenario where a class is denoted with @since > > 6.5.x > > >>> and all internals of that class are completely new and replaced with > > >>> 8.2.x > > >>> or even 9.0 (or 1.0 Geode) code? > > >>> > > >>> I think that @since tags become like comments, without somebody > > changing > > >>> things, they just become stale and stagnant. I cannot think of many > > open > > >>> source projects that use @since tags. > > >>> > > >>> But if we must have them in the code base then I prefer to have them > > as a > > >>> Geode x.y.z > > >>> > > >>> > > >>> On 26/04/2016 9:56 am, Darrel Schneider wrote: > > >>> > > >>> +1 for having on explicit GemFire and Geode > > >>>> > > >>>> > > >>>> On Mon, Apr 25, 2016 at 4:43 PM, Kenneth Howe <[email protected]> > > wrote: > > >>>> > > >>>> +1 to “gemFire x.y.z” > > >>>> > > >>>>> Adding the GemFire makes it obvious where the feature came from, no > > >>>>> inference > > >>>>> required as would happen if we left just a version number for old > > >>>>> @since > > >>>>> annotations. > > >>>>> > > >>>>> Ken > > >>>>> > > >>>>> On Apr 25, 2016, at 4:39 PM, Kirk Lund <[email protected]> wrote: > > >>>>> > > >>>>>> +1 for @since Geode 1.0.0 > > >>>>>> > > >>>>>> If we keep the pre-existing @since tags, then I'd prefer to add > > >>>>>> "GemFire" > > >>>>>> to them for better clarity. Thus, @since 4.0.0 would be changed to > > >>>>>> @since > > >>>>>> GemFire 4.0.0. Just my preference. > > >>>>>> > > >>>>>> -Kirk > > >>>>>> > > >>>>>> > > >>>>>> On Mon, Apr 25, 2016 at 4:32 PM, Sai Boorlagadda < > > >>>>>> > > >>>>>> [email protected]> > > >>>>> > > >>>>> wrote: > > >>>>>> > > >>>>>> +1 for Geode 1.0.0 > > >>>>>> > > >>>>>>> And we can leave current @since tags as-is with out "GemFire" to > > >>>>>>> denote > > >>>>>>> predate Geode. > > >>>>>>> So if you see "Geode x.y.z" => added in Geode > > >>>>>>> or "x.y.z" => Predate to Geode > > >>>>>>> (i.e.,) > > >>>>>>> GemFire. > > >>>>>>> > > >>>>>>> > > >>>>>>> On Fri, Apr 22, 2016 at 3:37 PM, John Blum <[email protected]> > > wrote: > > >>>>>>> > > >>>>>>> +1 for @since Geode 1.0.0. > > >>>>>>> > > >>>>>>>> @since GemFire x.y.z is probably not all that useful from a > Geode > > >>>>>>>> perspective, but maybe important in GemFire source, particularly > > for > > >>>>>>>> features that maybe specific to GemFire, or predate Geode. > > >>>>>>>> > > >>>>>>>> On Fri, Apr 22, 2016 at 3:11 PM, Dan Smith < > > >>>>>>>> [email protected] > > >>>>>>>> wrote: > > >>>>>>>> > > >>>>>>>> Hi, > > >>>>>>>> > > >>>>>>>>> We have a lot of @since tags in our javadocs with old gemfire > > >>>>>>>>> versions. I think we are going to keep them in there, we should > > >>>>>>>>> maybe > > >>>>>>>>> do a sweep and add gemfire to the version: > > >>>>>>>>> > > >>>>>>>>> Eg > > >>>>>>>>> @since GemFire 5.5 > > >>>>>>>>> > > >>>>>>>>> For geode @since tags, we can start from 1.0: > > >>>>>>>>> @since 1.0 > > >>>>>>>>> > > >>>>>>>>> Or maybe it would be better to be explicit? > > >>>>>>>>> @since Geode 1.0 > > >>>>>>>>> > > >>>>>>>>> What do you guys think? > > >>>>>>>>> -Dan > > >>>>>>>>> > > >>>>>>>>> > > >>>>>>>>> -- > > >>>>>>>> -John > > >>>>>>>> 503-504-8657 > > >>>>>>>> john.blum10101 (skype) > > >>>>>>>> > > >>>>>>>> > > >>>>>>>> -- > > >>>>>>> Sai Boorlagadda > > >>>>>>> > > >>>>>>> > > >>>>>>> > > > > > >
