You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gary Gregory <GG...@seagullsoftware.com> on 2010/03/07 02:13:27 UTC

[lang] v3.0 @since

Looking at trunk I see that the @since tags are still there. Since the package o.a.c.lang3 is new, does it make sense to have @since tags OTHER than 3.0 if any?

Gary Gregory
Senior Software Engineer
Seagull Software
email: ggregory@seagullsoftware.com
email: ggregory@apache.org
www.seagullsoftware.com 


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

Re: [lang] v3.0 @since

Posted by Paul Benedict <pb...@apache.org>.
Even if the package names are different and thus binary compatibility
is not preserved, the @since tags are still important to delineate new
functionality before 3.0. It can help people with migrating.

On Mon, Apr 5, 2010 at 12:26 PM, Gary Gregory
<GG...@seagullsoftware.com> wrote:
>> -----Original Message-----
>> From: sebb [mailto:sebbaz@gmail.com]
>> Sent: Saturday, March 27, 2010 16:19
>> To: Commons Developers List
>> Subject: Re: [lang] v3.0 @since
>>
>> On 27/03/2010, Gary Gregory <GG...@seagullsoftware.com> wrote:
>> > Since multiple @since tags are allowed and are treated like multiple @author
>> tags, what about making use of that? For example:
>> >
>> >  ...
>> >      * @since 2.0
>> >      * @since 3.0
>>
>> -1, very confusing - what does it mean?
>>
>> >      */
>> >     public static String capitalize(CharSequence cs) {
>> >  ...
>> >
>> >  Or maybe:
>> >
>> >      * @since 2.0
>> >      * @since 3.0 changed from capitalize(String) to
>> capitalize(CharSequence)
>>
>> +1
>
> I added @since 3.0 tag in this format for StringUtils.
>
> Gary
>
>
> ---------------------------------------------------------------------
> 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: [lang] v3.0 @since

Posted by Gary Gregory <GG...@seagullsoftware.com>.
> -----Original Message-----
> From: sebb [mailto:sebbaz@gmail.com]
> Sent: Saturday, March 27, 2010 16:19
> To: Commons Developers List
> Subject: Re: [lang] v3.0 @since
> 
> On 27/03/2010, Gary Gregory <GG...@seagullsoftware.com> wrote:
> > Since multiple @since tags are allowed and are treated like multiple @author
> tags, what about making use of that? For example:
> >
> >  ...
> >      * @since 2.0
> >      * @since 3.0
> 
> -1, very confusing - what does it mean?
> 
> >      */
> >     public static String capitalize(CharSequence cs) {
> >  ...
> >
> >  Or maybe:
> >
> >      * @since 2.0
> >      * @since 3.0 changed from capitalize(String) to
> capitalize(CharSequence)
> 
> +1

I added @since 3.0 tag in this format for StringUtils.

Gary


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

Re: [lang] v3.0 @since

Posted by sebb <se...@gmail.com>.
On 27/03/2010, Gary Gregory <GG...@seagullsoftware.com> wrote:
> Since multiple @since tags are allowed and are treated like multiple @author tags, what about making use of that? For example:
>
>  ...
>      * @since 2.0
>      * @since 3.0

-1, very confusing - what does it mean?

>      */
>     public static String capitalize(CharSequence cs) {
>  ...
>
>  Or maybe:
>
>      * @since 2.0
>      * @since 3.0 changed from capitalize(String) to capitalize(CharSequence)

+1

>  Or something like that, since the @since text is free form.
>
>
>  Gary Gregory
>  Senior Software Engineer
>  Seagull Software
>  email: ggregory@seagullsoftware.com
>  email: ggregory@apache.org
>  www.seagullsoftware.com
>
>
>
>
> > -----Original Message-----
>  > From: Henri Yandell [mailto:flamefew@gmail.com]
>
> > Sent: Saturday, March 27, 2010 14:49
>  > To: Commons Developers List
>  > Subject: Re: [lang] v3.0 @since
>  >
>  > I think so. If a recompile would make it work, then no need to update
>  > the @since. It would be lovely to say @improved 3.0; but at the end of
>  > the day I think we'll have to rely on separate documentation to handle
>  > that.
>  >
>  > On Sun, Mar 7, 2010 at 12:22 AM, Gary Gregory
>  > <GG...@seagullsoftware.com> wrote:
>  > > Fair enough.
>  > >
>  > > What about APIs that change from, for example, String to
>  > CharSequence, should these stay with the same @since tags, even if the
>  > Java version for the project of the @since version did not include the
>  > class CharSequence.
>  > >
>  > > Gary
>  > >
>  > >> -----Original Message-----
>  > >> From: Henri Yandell [mailto:flamefew@gmail.com]
>  > >> Sent: Saturday, March 06, 2010 19:23
>  > >> To: Commons Developers List
>  > >> Subject: Re: [lang] v3.0 @since
>  > >>
>  > >> I think it does.
>  > >>
>  > >> The choice of a new package name was a workaround rather than a
>  > >> declaration of a different package, so the @since's still have
>  > value.
>  > >>
>  > >> Hen
>  > >>
>  > >> On Sat, Mar 6, 2010 at 5:13 PM, Gary Gregory
>  > >> <GG...@seagullsoftware.com> wrote:
>  > >> > Looking at trunk I see that the @since tags are still there. Since
>  > the
>  > >> package o.a.c.lang3 is new, does it make sense to have @since tags
>  > OTHER than
>  > >> 3.0 if any?
>  > >> >
>  > >> > Gary Gregory
>  > >> > Senior Software Engineer
>  > >> > Seagull Software
>  > >> > email: ggregory@seagullsoftware.com
>  > >> > email: ggregory@apache.org
>  > >> > www.seagullsoftware.com
>  > >> >
>  > >> >
>  > >> > ------------------------------------------------------------------
>  > ---
>  > >> > 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
>  > >
>  > >
>  >
>  > ---------------------------------------------------------------------
>  > 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: [lang] v3.0 @since

Posted by Gary Gregory <GG...@seagullsoftware.com>.
Since multiple @since tags are allowed and are treated like multiple @author tags, what about making use of that? For example:

...
     * @since 2.0
     * @since 3.0 
     */
    public static String capitalize(CharSequence cs) {
...

Or maybe:

     * @since 2.0
     * @since 3.0 changed from capitalize(String) to capitalize(CharSequence)

Or something like that, since the @since text is free form.

Gary Gregory
Senior Software Engineer
Seagull Software
email: ggregory@seagullsoftware.com
email: ggregory@apache.org
www.seagullsoftware.com 



> -----Original Message-----
> From: Henri Yandell [mailto:flamefew@gmail.com]
> Sent: Saturday, March 27, 2010 14:49
> To: Commons Developers List
> Subject: Re: [lang] v3.0 @since
> 
> I think so. If a recompile would make it work, then no need to update
> the @since. It would be lovely to say @improved 3.0; but at the end of
> the day I think we'll have to rely on separate documentation to handle
> that.
> 
> On Sun, Mar 7, 2010 at 12:22 AM, Gary Gregory
> <GG...@seagullsoftware.com> wrote:
> > Fair enough.
> >
> > What about APIs that change from, for example, String to
> CharSequence, should these stay with the same @since tags, even if the
> Java version for the project of the @since version did not include the
> class CharSequence.
> >
> > Gary
> >
> >> -----Original Message-----
> >> From: Henri Yandell [mailto:flamefew@gmail.com]
> >> Sent: Saturday, March 06, 2010 19:23
> >> To: Commons Developers List
> >> Subject: Re: [lang] v3.0 @since
> >>
> >> I think it does.
> >>
> >> The choice of a new package name was a workaround rather than a
> >> declaration of a different package, so the @since's still have
> value.
> >>
> >> Hen
> >>
> >> On Sat, Mar 6, 2010 at 5:13 PM, Gary Gregory
> >> <GG...@seagullsoftware.com> wrote:
> >> > Looking at trunk I see that the @since tags are still there. Since
> the
> >> package o.a.c.lang3 is new, does it make sense to have @since tags
> OTHER than
> >> 3.0 if any?
> >> >
> >> > Gary Gregory
> >> > Senior Software Engineer
> >> > Seagull Software
> >> > email: ggregory@seagullsoftware.com
> >> > email: ggregory@apache.org
> >> > www.seagullsoftware.com
> >> >
> >> >
> >> > ------------------------------------------------------------------
> ---
> >> > 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
> >
> >
> 
> ---------------------------------------------------------------------
> 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: [lang] v3.0 @since

Posted by Henri Yandell <fl...@gmail.com>.
I think so. If a recompile would make it work, then no need to update
the @since. It would be lovely to say @improved 3.0; but at the end of
the day I think we'll have to rely on separate documentation to handle
that.

On Sun, Mar 7, 2010 at 12:22 AM, Gary Gregory
<GG...@seagullsoftware.com> wrote:
> Fair enough.
>
> What about APIs that change from, for example, String to CharSequence, should these stay with the same @since tags, even if the Java version for the project of the @since version did not include the class CharSequence.
>
> Gary
>
>> -----Original Message-----
>> From: Henri Yandell [mailto:flamefew@gmail.com]
>> Sent: Saturday, March 06, 2010 19:23
>> To: Commons Developers List
>> Subject: Re: [lang] v3.0 @since
>>
>> I think it does.
>>
>> The choice of a new package name was a workaround rather than a
>> declaration of a different package, so the @since's still have value.
>>
>> Hen
>>
>> On Sat, Mar 6, 2010 at 5:13 PM, Gary Gregory
>> <GG...@seagullsoftware.com> wrote:
>> > Looking at trunk I see that the @since tags are still there. Since the
>> package o.a.c.lang3 is new, does it make sense to have @since tags OTHER than
>> 3.0 if any?
>> >
>> > Gary Gregory
>> > Senior Software Engineer
>> > Seagull Software
>> > email: ggregory@seagullsoftware.com
>> > email: ggregory@apache.org
>> > www.seagullsoftware.com
>> >
>> >
>> > ---------------------------------------------------------------------
>> > 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
>
>

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

RE: [lang] v3.0 @since

Posted by Gary Gregory <GG...@seagullsoftware.com>.
Fair enough. 

What about APIs that change from, for example, String to CharSequence, should these stay with the same @since tags, even if the Java version for the project of the @since version did not include the class CharSequence.

Gary 

> -----Original Message-----
> From: Henri Yandell [mailto:flamefew@gmail.com]
> Sent: Saturday, March 06, 2010 19:23
> To: Commons Developers List
> Subject: Re: [lang] v3.0 @since
> 
> I think it does.
> 
> The choice of a new package name was a workaround rather than a
> declaration of a different package, so the @since's still have value.
> 
> Hen
> 
> On Sat, Mar 6, 2010 at 5:13 PM, Gary Gregory
> <GG...@seagullsoftware.com> wrote:
> > Looking at trunk I see that the @since tags are still there. Since the
> package o.a.c.lang3 is new, does it make sense to have @since tags OTHER than
> 3.0 if any?
> >
> > Gary Gregory
> > Senior Software Engineer
> > Seagull Software
> > email: ggregory@seagullsoftware.com
> > email: ggregory@apache.org
> > www.seagullsoftware.com
> >
> >
> > ---------------------------------------------------------------------
> > 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: [lang] v3.0 @since

Posted by Henri Yandell <fl...@gmail.com>.
I think it does.

The choice of a new package name was a workaround rather than a
declaration of a different package, so the @since's still have value.

Hen

On Sat, Mar 6, 2010 at 5:13 PM, Gary Gregory
<GG...@seagullsoftware.com> wrote:
> Looking at trunk I see that the @since tags are still there. Since the package o.a.c.lang3 is new, does it make sense to have @since tags OTHER than 3.0 if any?
>
> Gary Gregory
> Senior Software Engineer
> Seagull Software
> email: ggregory@seagullsoftware.com
> email: ggregory@apache.org
> www.seagullsoftware.com
>
>
> ---------------------------------------------------------------------
> 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