Comments on API to remove

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Comments on API to remove

Jens Lideström
I'm in the process of marking some old databinding API for removal. I'm
not really sure how to write the Javadoc comment on the removed API.

Is the following a good comment?

/**
 * XXX
 * @deprecated This class will be removed in a future release. See
 *             https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820 for more
 *             information. Use XXX instead.
 */

The wiki [1] says the following on this subject:

"""
5. Annotate all APIs that are to be removed with @noreference, @noextend
and @noimplement where applicable, update deprecation comment and add an
entry in the porting guide. Do the same for API that depends on it. The
deprecation comment and porting guide entry must explain how to adapt the
client code and also include a link to the bug report to allow feedback
from API adopters.
"""

If my example above is a suitable comment I will update the wiki to
include it.

[1]: https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process

/Jens


_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Lars Vogel-2
Hi Jens,

I think that is a good comment. Thanks!

Best regards, Lars

On Sat, May 23, 2020 at 5:33 PM Jens Lideström <[hidden email]> wrote:

>
> I'm in the process of marking some old databinding API for removal. I'm
> not really sure how to write the Javadoc comment on the removed API.
>
> Is the following a good comment?
>
> /**
>  * XXX
>  * @deprecated This class will be removed in a future release. See
>  *             https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820 for more
>  *             information. Use XXX instead.
>  */
>
> The wiki [1] says the following on this subject:
>
> """
> 5. Annotate all APIs that are to be removed with @noreference, @noextend
> and @noimplement where applicable, update deprecation comment and add an
> entry in the porting guide. Do the same for API that depends on it. The
> deprecation comment and porting guide entry must explain how to adapt the
> client code and also include a link to the bug report to allow feedback
> from API adopters.
> """
>
> If my example above is a suitable comment I will update the wiki to
> include it.
>
> [1]: https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process
>
> /Jens
>
>
> _______________________________________________
> platform-dev mailing list
> [hidden email]
> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev



--
Eclipse Platform project co-lead
CEO vogella GmbH

Haindaalwisch 17a, 22395 Hamburg
Amtsgericht Hamburg: HRB 127058
Geschäftsführer: Lars Vogel, Jennifer Nerlich de Vogel
USt-IdNr.: DE284122352
Fax (040) 5247 6322, Email: [hidden email], Web: http://www.vogella.com
_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Jens Lideström

Is it a good idea to include the earliest deletion date in the comment?

Ex:
"This class will be removed in some future release after 2020-05-31."

/Jens

On 2020-05-23 19:02, Lars Vogel wrote:

> Hi Jens,
>
> I think that is a good comment. Thanks!
>
> Best regards, Lars
>
> On Sat, May 23, 2020 at 5:33 PM Jens Lideström <[hidden email]> wrote:
>> I'm in the process of marking some old databinding API for removal. I'm
>> not really sure how to write the Javadoc comment on the removed API.
>>
>> Is the following a good comment?
>>
>> /**
>>  * XXX
>>  * @deprecated This class will be removed in a future release. See
>>  *             https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820 for more
>>  *             information. Use XXX instead.
>>  */
>>
>> The wiki [1] says the following on this subject:
>>
>> """
>> 5. Annotate all APIs that are to be removed with @noreference, @noextend
>> and @noimplement where applicable, update deprecation comment and add an
>> entry in the porting guide. Do the same for API that depends on it. The
>> deprecation comment and porting guide entry must explain how to adapt the
>> client code and also include a link to the bug report to allow feedback
>> from API adopters.
>> """
>>
>> If my example above is a suitable comment I will update the wiki to
>> include it.
>>
>> [1]: https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process
>>
>> /Jens
>>
>>
>> _______________________________________________
>> platform-dev mailing list
>> [hidden email]
>> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
>
>

_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Lars Vogel-2
Hi Jens,

I think it is a good idea so that we document this for the users and
the committers directly in the source code but this is not mandatory.

Best regards, Lars

On Sun, May 24, 2020 at 11:25 AM Jens Lideström <[hidden email]> wrote:

>
>
> Is it a good idea to include the earliest deletion date in the comment?
>
> Ex:
> "This class will be removed in some future release after 2020-05-31."
>
> /Jens
>
> On 2020-05-23 19:02, Lars Vogel wrote:
> > Hi Jens,
> >
> > I think that is a good comment. Thanks!
> >
> > Best regards, Lars
> >
> > On Sat, May 23, 2020 at 5:33 PM Jens Lideström <[hidden email]> wrote:
> >> I'm in the process of marking some old databinding API for removal. I'm
> >> not really sure how to write the Javadoc comment on the removed API.
> >>
> >> Is the following a good comment?
> >>
> >> /**
> >>  * XXX
> >>  * @deprecated This class will be removed in a future release. See
> >>  *             https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820 for more
> >>  *             information. Use XXX instead.
> >>  */
> >>
> >> The wiki [1] says the following on this subject:
> >>
> >> """
> >> 5. Annotate all APIs that are to be removed with @noreference, @noextend
> >> and @noimplement where applicable, update deprecation comment and add an
> >> entry in the porting guide. Do the same for API that depends on it. The
> >> deprecation comment and porting guide entry must explain how to adapt the
> >> client code and also include a link to the bug report to allow feedback
> >> from API adopters.
> >> """
> >>
> >> If my example above is a suitable comment I will update the wiki to
> >> include it.
> >>
> >> [1]: https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process
> >>
> >> /Jens
> >>
> >>
> >> _______________________________________________
> >> platform-dev mailing list
> >> [hidden email]
> >> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
> >
> >
>
> _______________________________________________
> platform-dev mailing list
> [hidden email]
> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev



--
Eclipse Platform project co-lead
CEO vogella GmbH

Haindaalwisch 17a, 22395 Hamburg
Amtsgericht Hamburg: HRB 127058
Geschäftsführer: Lars Vogel, Jennifer Nerlich de Vogel
USt-IdNr.: DE284122352
Fax (040) 5247 6322, Email: [hidden email], Web: http://www.vogella.com
_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Gayan Perera
How about introducing an annotation? We could add warnings in api analysis as well.

Br,
Gayan

On Sun, 24 May 2020 at 14:00, Lars Vogel <[hidden email]> wrote:
Hi Jens,

I think it is a good idea so that we document this for the users and
the committers directly in the source code but this is not mandatory.

Best regards, Lars

On Sun, May 24, 2020 at 11:25 AM Jens Lideström <[hidden email]> wrote:
>
>
> Is it a good idea to include the earliest deletion date in the comment?
>
> Ex:
> "This class will be removed in some future release after 2020-05-31."
>
> /Jens
>
> On 2020-05-23 19:02, Lars Vogel wrote:
> > Hi Jens,
> >
> > I think that is a good comment. Thanks!
> >
> > Best regards, Lars
> >
> > On Sat, May 23, 2020 at 5:33 PM Jens Lideström <[hidden email]> wrote:
> >> I'm in the process of marking some old databinding API for removal. I'm
> >> not really sure how to write the Javadoc comment on the removed API.
> >>
> >> Is the following a good comment?
> >>
> >> /**
> >>  * XXX
> >>  * @deprecated This class will be removed in a future release. See
> >>  *             https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820 for more
> >>  *             information. Use XXX instead.
> >>  */
> >>
> >> The wiki [1] says the following on this subject:
> >>
> >> """
> >> 5. Annotate all APIs that are to be removed with @noreference, @noextend
> >> and @noimplement where applicable, update deprecation comment and add an
> >> entry in the porting guide. Do the same for API that depends on it. The
> >> deprecation comment and porting guide entry must explain how to adapt the
> >> client code and also include a link to the bug report to allow feedback
> >> from API adopters.
> >> """
> >>
> >> If my example above is a suitable comment I will update the wiki to
> >> include it.
> >>
> >> [1]: https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process
> >>
> >> /Jens
> >>
> >>
> >> _______________________________________________
> >> platform-dev mailing list
> >> [hidden email]
> >> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
> >
> >
>
> _______________________________________________
> platform-dev mailing list
> [hidden email]
> To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev



--
Eclipse Platform project co-lead
CEO vogella GmbH

Haindaalwisch 17a, 22395 Hamburg
Amtsgericht Hamburg: HRB 127058
Geschäftsführer: Lars Vogel, Jennifer Nerlich de Vogel
USt-IdNr.: DE284122352
Fax (040) 5247 6322, Email: [hidden email], Web: http://www.vogella.com
_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev

_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Daniel Megert
That's what @noreference, @noextendand @noimplementdo.

Dani



From:        Gayan Perera <[hidden email]>
To:        "Eclipse platform general developers list." <[hidden email]>
Date:        24.05.2020 15:53
Subject:        [EXTERNAL] Re: [platform-dev] Comments on API to remove
Sent by:        [hidden email]




How about introducing an annotation? We could add warnings in api analysis as well.

Br,
Gayan

On Sun, 24 May 2020 at 14:00, Lars Vogel <[hidden email]> wrote:

Hi Jens,

I think it is a good idea so that we document this for the users and
the committers directly in the source code but this is not mandatory.

Best regards, Lars

On Sun, May 24, 2020 at 11:25 AM Jens Lideström <
[hidden email]> wrote:


>
>
> Is it a good idea to include the earliest deletion date in the comment?
>
> Ex:
> "This class will be removed in some future release after 2020-05-31."
>
> /Jens
>
> On 2020-05-23 19:02, Lars Vogel wrote:
> > Hi Jens,
> >
> > I think that is a good comment. Thanks!
> >
> > Best regards, Lars
> >
> > On Sat, May 23, 2020 at 5:33 PM Jens Lideström <[hidden email]> wrote:
> >> I'm in the process of marking some old databinding API for removal. I'm
> >> not really sure how to write the Javadoc comment on the removed API.
> >>
> >> Is the following a good comment?
> >>
> >> /**
> >>  * XXX
> >>  * @deprecated This class will be removed in a future release. See
> >>  *             
https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820for more
> >>  *             information. Use XXX instead.
> >>  */
> >>
> >> The wiki [1] says the following on this subject:
> >>
> >> """
> >> 5. Annotate all APIs that are to be removed with @noreference, @noextend
> >> and @noimplement where applicable, update deprecation comment and add an
> >> entry in the porting guide. Do the same for API that depends on it. The
> >> deprecation comment and porting guide entry must explain how to adapt the
> >> client code and also include a link to the bug report to allow feedback
> >> from API adopters.
> >> """
> >>
> >> If my example above is a suitable comment I will update the wiki to
> >> include it.
> >>
> >> [1]:
https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process
> >>
> >> /Jens
> >>
> >>
> >> _______________________________________________
> >> platform-dev mailing list
> >>
[hidden email]
> >> To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev
> >
> >
>
> _______________________________________________
> platform-dev mailing list
>
[hidden email]
> To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev



--
Eclipse Platform project co-lead
CEO vogella GmbH

Haindaalwisch 17a, 22395 Hamburg
Amtsgericht Hamburg: HRB 127058
Geschäftsführer: Lars Vogel, Jennifer Nerlich de Vogel
USt-IdNr.: DE284122352
Fax (040) 5247 6322, Email: [hidden email], Web: http://www.vogella.com
_______________________________________________
platform-dev mailing list

[hidden email]
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev



_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev
Reply | Threaded
Open this post in threaded view
|

Re: Comments on API to remove

Daniel Megert
In reply to this post by Jens Lideström
More important than the Javadoc is to follow every step in https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process.

Dani



From:        "Jens Lideström" <[hidden email]>
To:        "Eclipse platform general developers list." <[hidden email]>
Date:        23.05.2020 17:33
Subject:        [EXTERNAL] [platform-dev] Comments on API to remove
Sent by:        [hidden email]




I'm in the process of marking some old databinding API for removal. I'm
not really sure how to write the Javadoc comment on the removed API.

Is the following a good comment?

/**
 * XXX
 * @deprecated This class will be removed in a future release. See
 *            
https://bugs.eclipse.org/bugs/show_bug.cgi?id=546820for more
 *             information. Use XXX instead.
 */

The wiki [1] says the following on this subject:

"""
5. Annotate all APIs that are to be removed with @noreference, @noextend
and @noimplement where applicable, update deprecation comment and add an
entry in the porting guide. Do the same for API that depends on it. The
deprecation comment and porting guide entry must explain how to adapt the
client code and also include a link to the bug report to allow feedback
from API adopters.
"""

If my example above is a suitable comment I will update the wiki to
include it.

[1]:
https://wiki.eclipse.org/Eclipse/API_Central/API_Removal_Process

/Jens


_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/platform-dev




_______________________________________________
platform-dev mailing list
[hidden email]
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/platform-dev