Re: [boost] Deprecation guidelines?

Subject: Re: [boost] Deprecation guidelines?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-03-18 10:30:17

> -----Original Message-----
> From: boost-bounces_at_[hidden] [mailto:boost-bounces_at_[hidden]]
> On Behalf Of Stewart, Robert
> Sent: Friday, March 18, 2011 10:56 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] Deprecation guidelines?
> 
> Paul A. Bristow wrote:
> > > On Behalf Of John Maddock
> > >
> > > >> Where can one find guidelines on how to deprecate things in
> > > >> Boost?  What is the proper way to check that code using Boost is
> > > >> clean?
> > > >
> > > > There is no standard for doing this. Right now, it's whatever each
> > > > library author decides to do.
> > >
> > > If someone would like to volunteer to document best practice on the
> > > Wiki though that would be great ;-)
> >
> > OK - I hope this might be within my skill set?
> >
> > Shall I start with a new thread asking for views?
> >
> > Or shall I dream up and post up a 'strawman' proposal for others to
> > shoot at?
> 
> When it comes to marking functions as deprecated, here's what I know:
> 
> GCC: __attribute__((__deprecated__))
> MSVC: __declspec(deprecated)
> 
> GCC allows the attribute to precede the return type or after the argument
list.
> MSVC requires the declspec to precede the return type.
> 
> Therefore, I use a macro that is defined to one of the forgoing
decorators,
> depending upon the compiler, and document that it must precede the return
> type for portability.  It would be reasonable for the macro to take one
> parameter: the return type.  It would then produce the decorator followed
by
> the return type and force its use in the portable location.  I haven't
done that,
> but it is worth considering.
> 
> Therefore:
> 
> #if defined __GNUC__
> #  define BOOST_DEPRECATED(_return_type) \
>    __attribute__((__deprecated__)) _return_type #elif defined _MSC_VER #
> define BOOST_DEPRECATED(_return_type) \
>    __declspace(deprecated) _return_type
> #endif
> 
> or just:
> 
> #if defined __GNUC__
> #  define BOOST_DEPRECATED __attribute__((__deprecated__)) #elif defined
> _MSC_VER #  define BOOST_DEPRECATED __declspace(deprecated) #endif

Perhaps this is not within my skill set after all? ;-)

You clearly know much more that I do about the mechanics of this.

So perhaps you'd like to take on the task?

(I note the link to the
https://svn.boost.org/trac/boost/wiki/Guidelines/MaintenanceGuidelines#delet
e_files  examples is broken).

Without the examples, I'm not sure it makes much sense (typos aside).

But are there also the procedures for deprecating to consider?

Should one or two Boost releases notice be given warning of future
deprecation?

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]