You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sebb <se...@gmail.com> on 2010/11/15 04:55:56 UTC
[VFS] @since markers missing - ctd
Starting a new thread because the original one drifted into @author tags.
I've been using clirr to report which classes and methods are new.
This works fine for classes, however Clirr does not seem to notice
when a private method becomes public - it just says the method has
been added, [even if one tells clirr to process all access modifiers.]
In a sense, this is a method addition - should the @since tag be added?
If so, should we say that the access has changed?
For example: @since 2.0 (was private)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [VFS] @since markers missing - ctd
Posted by Gary Gregory <GG...@seagullsoftware.com>.
On Nov 14, 2010, at 20:23, "sebb" <se...@gmail.com> wrote:
> On 15 November 2010 04:16, Gary Gregory <GG...@seagullsoftware.com> wrote:
>> On Nov 14, 2010, at 20:04, "sebb" <se...@gmail.com> wrote:
>>
>>> On 15 November 2010 03:59, Gary Gregory <GG...@seagullsoftware.com> wrote:
>>>> On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
>>>>
>>>>> Starting a new thread because the original one drifted into @author tags.
>>>>>
>>>>> I've been using clirr to report which classes and methods are new.
>>>>>
>>>>> This works fine for classes, however Clirr does not seem to notice
>>>>> when a private method becomes public - it just says the method has
>>>>> been added, [even if one tells clirr to process all access modifiers.]
>>>>>
>>>>> In a sense, this is a method addition - should the @since tag be added?
>>>>
>>>> +1
>>>>
>>>>> If so, should we say that the access has changed?
>>>>> For example: @since 2.0 (was private)
>>>>
>>>> -1
>>>
>>> What about changes from protected to public?
>>>
>>> How should these be documented?
>>
>> Great question. Should it be @since 1.0 or 2.0? The API will look new to com.foo client code, so that argues for a plain since 2.0. If I was already a call site of the API, seeing since 2.0 might look strange but since the scope changed it is understandable. So I would just argue for since 2.0.
>
> The reason I suggested adding a comment about the previous
> accessibility was to avoid the possible confusion.
>
> The Clirr report should show such changes; if not they probably ought
> to go into the release notes.
>
> However, it might still be useful to mention the change in the
Sure. Some historical note in the javadoc sounds good.
GG
>
>> GG
>>
>>>
>>>> GG
>>>>>
>>>>> ---------------------------------------------------------------------
>>>>> 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: [VFS] @since markers missing - ctd
Posted by sebb <se...@gmail.com>.
On 15 November 2010 04:16, Gary Gregory <GG...@seagullsoftware.com> wrote:
> On Nov 14, 2010, at 20:04, "sebb" <se...@gmail.com> wrote:
>
>> On 15 November 2010 03:59, Gary Gregory <GG...@seagullsoftware.com> wrote:
>>> On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
>>>
>>>> Starting a new thread because the original one drifted into @author tags.
>>>>
>>>> I've been using clirr to report which classes and methods are new.
>>>>
>>>> This works fine for classes, however Clirr does not seem to notice
>>>> when a private method becomes public - it just says the method has
>>>> been added, [even if one tells clirr to process all access modifiers.]
>>>>
>>>> In a sense, this is a method addition - should the @since tag be added?
>>>
>>> +1
>>>
>>>> If so, should we say that the access has changed?
>>>> For example: @since 2.0 (was private)
>>>
>>> -1
>>
>> What about changes from protected to public?
>>
>> How should these be documented?
>
> Great question. Should it be @since 1.0 or 2.0? The API will look new to com.foo client code, so that argues for a plain since 2.0. If I was already a call site of the API, seeing since 2.0 might look strange but since the scope changed it is understandable. So I would just argue for since 2.0.
The reason I suggested adding a comment about the previous
accessibility was to avoid the possible confusion.
The Clirr report should show such changes; if not they probably ought
to go into the release notes.
However, it might still be useful to mention the change in the Javadoc.
> GG
>
>>
>>> GG
>>>>
>>>> ---------------------------------------------------------------------
>>>> 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: [VFS] @since markers missing - ctd
Posted by Gary Gregory <GG...@seagullsoftware.com>.
On Nov 14, 2010, at 20:04, "sebb" <se...@gmail.com> wrote:
> On 15 November 2010 03:59, Gary Gregory <GG...@seagullsoftware.com> wrote:
>> On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
>>
>>> Starting a new thread because the original one drifted into @author tags.
>>>
>>> I've been using clirr to report which classes and methods are new.
>>>
>>> This works fine for classes, however Clirr does not seem to notice
>>> when a private method becomes public - it just says the method has
>>> been added, [even if one tells clirr to process all access modifiers.]
>>>
>>> In a sense, this is a method addition - should the @since tag be added?
>>
>> +1
>>
>>> If so, should we say that the access has changed?
>>> For example: @since 2.0 (was private)
>>
>> -1
>
> What about changes from protected to public?
>
> How should these be documented?
Great question. Should it be @since 1.0 or 2.0? The API will look new to com.foo client code, so that argues for a plain since 2.0. If I was already a call site of the API, seeing since 2.0 might look strange but since the scope changed it is understandable. So I would just argue for since 2.0.
GG
>
>> GG
>>>
>>> ---------------------------------------------------------------------
>>> 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: [VFS] @since markers missing - ctd
Posted by Ralph Goers <ra...@dslextreme.com>.
On Nov 14, 2010, at 8:04 PM, sebb wrote:
> On 15 November 2010 03:59, Gary Gregory <GG...@seagullsoftware.com> wrote:
>> On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
>>
>>> Starting a new thread because the original one drifted into @author tags.
>>>
>>> I've been using clirr to report which classes and methods are new.
>>>
>>> This works fine for classes, however Clirr does not seem to notice
>>> when a private method becomes public - it just says the method has
>>> been added, [even if one tells clirr to process all access modifiers.]
>>>
>>> In a sense, this is a method addition - should the @since tag be added?
>>
>> +1
>>
>>> If so, should we say that the access has changed?
>>> For example: @since 2.0 (was private)
>>
>> -1
>
> What about changes from protected to public?
>
> How should these be documented?
Same thing. A protected method was not available to arbitrary classes and now is, so in essence it is like adding a new method. OTOH, going from public to protected or private is API breakage if the class is meant to be public. Unfortunately, it isn't obvious which subpackages are for internal use only and which are part of the API.
Ralph
Re: [VFS] @since markers missing - ctd
Posted by sebb <se...@gmail.com>.
On 15 November 2010 03:59, Gary Gregory <GG...@seagullsoftware.com> wrote:
> On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
>
>> Starting a new thread because the original one drifted into @author tags.
>>
>> I've been using clirr to report which classes and methods are new.
>>
>> This works fine for classes, however Clirr does not seem to notice
>> when a private method becomes public - it just says the method has
>> been added, [even if one tells clirr to process all access modifiers.]
>>
>> In a sense, this is a method addition - should the @since tag be added?
>
> +1
>
>> If so, should we say that the access has changed?
>> For example: @since 2.0 (was private)
>
> -1
What about changes from protected to public?
How should these be documented?
> GG
>>
>> ---------------------------------------------------------------------
>> 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: [VFS] @since markers missing - ctd
Posted by Gary Gregory <GG...@seagullsoftware.com>.
On Nov 14, 2010, at 19:56, "sebb" <se...@gmail.com> wrote:
> Starting a new thread because the original one drifted into @author tags.
>
> I've been using clirr to report which classes and methods are new.
>
> This works fine for classes, however Clirr does not seem to notice
> when a private method becomes public - it just says the method has
> been added, [even if one tells clirr to process all access modifiers.]
>
> In a sense, this is a method addition - should the @since tag be added?
+1
> If so, should we say that the access has changed?
> For example: @since 2.0 (was private)
-1
GG
>
> ---------------------------------------------------------------------
> 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