[PROXY] @since markers

[sebb <se...@gmail.com>]

Whilst removing the @author tags I noticed that there are 39 @since
markers, all are @since 1.0.

I think we should remove these.

If not, then we need to add @since markers to identify what has been
added since.

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

Re: [PROXY] @since markers

[Paul Benedict <pb...@apache.org>]

I don't know if removing @since 1.0 should be pursued. Coming from a
research perspective, the lack of them either indicates (1) since 1.0 or
(2) an omission. There's no way to know how someone would interpret their
omission so I would recommend keeping them so it's clear which methods
existed since the beginning.


On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:

> Whilst removing the @author tags I noticed that there are 39 @since
> markers, all are @since 1.0.
>
> I think we should remove these.
>
> If not, then we need to add @since markers to identify what has been
> added since.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
Cheers,
Paul

Re: [PROXY] @since markers

[Paul Benedict <pb...@apache.org>]

I think starting the classes should be @since tagged; that's standard
procedure in the javadoc world, as far as i know. Regarding what's
forgotten, I never worried about that and fixing it is easy.


On Thu, Mar 27, 2014 at 11:18 AM, sebb <se...@gmail.com> wrote:

> On 27 March 2014 15:47, Paul Benedict <pb...@apache.org> wrote:
> > Sebb, maybe I missed the context of the proposal. If the @since 1.0 is on
> > the class, there's no need for it to be on methods unless the methods are
> > of another version. I think that's the standard javadoc way from Oracle
> > anyway.
>
> Yes.
>
> But the only way to identify subsequent additional methods on a class
> is to add an @since marker to them.
>
> What about all the other methods in the class?
> Do they then all have to have @since 1.0 added?
>
> Otherwise how can one tell if a missing @since marker on a method is
> deliberately omiited (because it's the same as the class) or
> accidentally omitted?
>
> That's not to say that @since markers aren't useful.
> But I don't buy the argument that the starting classes need to be tagged.
>
> >
> > On Thu, Mar 27, 2014 at 10:35 AM, sebb <se...@gmail.com> wrote:
> >
> >> Indeed.
> >>
> >> The point about not knowing where a missing annotation means it was
> >> forgotten or whether it means ab initio may perhaps work with classes.
> >>
> >> However once a class has an @since marker, there's no way of telling
> >> whether its method and field @since markers are deliberately or
> >> accidentally omitted.
> >>
> >> The only way to deal with that would be to insist on @since markers
> >> for every class, method and field.
> >>
> >>
> >> On 27 March 2014 15:27, Matt Benson <gu...@gmail.com> wrote:
> >> > +1. Due to the package change and fundamental shift from ProxyFactory
> >> > as abstract class to interface, arguably everything (or very nearly
> >> > so) is @since 2.0 anyway.
> >> >
> >> > Matt
> >> >
> >> > On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:
> >> >> Whilst removing the @author tags I noticed that there are 39 @since
> >> >> markers, all are @since 1.0.
> >> >>
> >> >> I think we should remove these.
> >> >>
> >> >> If not, then we need to add @since markers to identify what has been
> >> >> added since.
> >> >>
> >> >> ---------------------------------------------------------------------
> >> >> 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
> >> >
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >>
> >>
> >
> >
> > --
> > Cheers,
> > Paul
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
Cheers,
Paul

Re: [PROXY] @since markers

[sebb <se...@gmail.com>]

On 27 March 2014 15:47, Paul Benedict <pb...@apache.org> wrote:
> Sebb, maybe I missed the context of the proposal. If the @since 1.0 is on
> the class, there's no need for it to be on methods unless the methods are
> of another version. I think that's the standard javadoc way from Oracle
> anyway.

Yes.

But the only way to identify subsequent additional methods on a class
is to add an @since marker to them.

What about all the other methods in the class?
Do they then all have to have @since 1.0 added?

Otherwise how can one tell if a missing @since marker on a method is
deliberately omiited (because it's the same as the class) or
accidentally omitted?

That's not to say that @since markers aren't useful.
But I don't buy the argument that the starting classes need to be tagged.

>
> On Thu, Mar 27, 2014 at 10:35 AM, sebb <se...@gmail.com> wrote:
>
>> Indeed.
>>
>> The point about not knowing where a missing annotation means it was
>> forgotten or whether it means ab initio may perhaps work with classes.
>>
>> However once a class has an @since marker, there's no way of telling
>> whether its method and field @since markers are deliberately or
>> accidentally omitted.
>>
>> The only way to deal with that would be to insist on @since markers
>> for every class, method and field.
>>
>>
>> On 27 March 2014 15:27, Matt Benson <gu...@gmail.com> wrote:
>> > +1. Due to the package change and fundamental shift from ProxyFactory
>> > as abstract class to interface, arguably everything (or very nearly
>> > so) is @since 2.0 anyway.
>> >
>> > Matt
>> >
>> > On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:
>> >> Whilst removing the @author tags I noticed that there are 39 @since
>> >> markers, all are @since 1.0.
>> >>
>> >> I think we should remove these.
>> >>
>> >> If not, then we need to add @since markers to identify what has been
>> >> added since.
>> >>
>> >> ---------------------------------------------------------------------
>> >> 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
>> >
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
> --
> Cheers,
> Paul

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

Re: [PROXY] @since markers

[Paul Benedict <pb...@apache.org>]

Sebb, maybe I missed the context of the proposal. If the @since 1.0 is on
the class, there's no need for it to be on methods unless the methods are
of another version. I think that's the standard javadoc way from Oracle
anyway.


On Thu, Mar 27, 2014 at 10:35 AM, sebb <se...@gmail.com> wrote:

> Indeed.
>
> The point about not knowing where a missing annotation means it was
> forgotten or whether it means ab initio may perhaps work with classes.
>
> However once a class has an @since marker, there's no way of telling
> whether its method and field @since markers are deliberately or
> accidentally omitted.
>
> The only way to deal with that would be to insist on @since markers
> for every class, method and field.
>
>
> On 27 March 2014 15:27, Matt Benson <gu...@gmail.com> wrote:
> > +1. Due to the package change and fundamental shift from ProxyFactory
> > as abstract class to interface, arguably everything (or very nearly
> > so) is @since 2.0 anyway.
> >
> > Matt
> >
> > On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:
> >> Whilst removing the @author tags I noticed that there are 39 @since
> >> markers, all are @since 1.0.
> >>
> >> I think we should remove these.
> >>
> >> If not, then we need to add @since markers to identify what has been
> >> added since.
> >>
> >> ---------------------------------------------------------------------
> >> 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
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
Cheers,
Paul

Re: [PROXY] @since markers

[sebb <se...@gmail.com>]

Indeed.

The point about not knowing where a missing annotation means it was
forgotten or whether it means ab initio may perhaps work with classes.

However once a class has an @since marker, there's no way of telling
whether its method and field @since markers are deliberately or
accidentally omitted.

The only way to deal with that would be to insist on @since markers
for every class, method and field.


On 27 March 2014 15:27, Matt Benson <gu...@gmail.com> wrote:
> +1. Due to the package change and fundamental shift from ProxyFactory
> as abstract class to interface, arguably everything (or very nearly
> so) is @since 2.0 anyway.
>
> Matt
>
> On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:
>> Whilst removing the @author tags I noticed that there are 39 @since
>> markers, all are @since 1.0.
>>
>> I think we should remove these.
>>
>> If not, then we need to add @since markers to identify what has been
>> added since.
>>
>> ---------------------------------------------------------------------
>> 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
>

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

Re: [PROXY] @since markers

[Matt Benson <gu...@gmail.com>]

+1. Due to the package change and fundamental shift from ProxyFactory
as abstract class to interface, arguably everything (or very nearly
so) is @since 2.0 anyway.

Matt

On Thu, Mar 27, 2014 at 10:22 AM, sebb <se...@gmail.com> wrote:
> Whilst removing the @author tags I noticed that there are 39 @since
> markers, all are @since 1.0.
>
> I think we should remove these.
>
> If not, then we need to add @since markers to identify what has been
> added since.
>
> ---------------------------------------------------------------------
> 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