[boost] Request: boost deprecated tag

Subject: [boost] Request: boost deprecated tag
From: Chard (boost_at_[hidden])
Date: 2009-06-16 17:32:44

Given that there is a current move to rationalize the bind placeholders, and 
potentially introduce deprecated definitions, would it worth introducing a 
boost deprecated marker that makes use of compiler support to notify the 
user that they are using such definitions?

I recently recompiled a project with BOOST_FILESYSTEM_NO_DEPRECATED (for no 
particular reason, except perhaps for tr1 readiness) and I was surprised how 
many uses of the old native_file_string and boost::native tags were buried 
in the code-base.  Personally, I think it would be useful to be notified (or 
nagged :-)) if I was using deprecated functionality; I don't examine every 
comment of every function, and after successful compilation/unit-test they 
are easily forgotten.

I don't know the best, generic, way of achieving this, but a simple approach 
that should work with MSVC and gcc would be to have:

#ifndef BOOST_NO_DEPRECATED_WARNINGS  // Don't nag me, compiler
#  if [BUILDING_WITH_MSVC]
#    define BOOST_DEPRECATED __declspec(deprecated)
#  else if [BUILDING_WITH_GCC]
#    define BOOST_DEPRECATED __attribute__ ((deprecated))
#  else if [BUILDING_WITH_acme]
#    define BOOST_DEPRECATED ...
#  end if
#endif

#ifndef BOOST_DEPRECATED
// No compiler support, just a tag
#  define BOOST_DEPRECATED
#end if

Then usage is:
BOOST_DEPRECATED void TheFunction(...);

The intent here is clear, and uncluttered, but may not be flexible enough. 
For example, a compiler may use syntax that declares its deprecated tag 
after the definition (which gcc supports, and it is usually shown that way 
in the guidelines).  In which case, I expect the whole definition would have 
to be wrapped up in the macro.

Also, there may be a case for separating the deprecated tags for functions, 
variables, types, etc..

As an (untested) illustration:

#ifndef BOOST_NO_DEPRECATED_WARNINGS
#  if [BUILDING_WITH_MSVC]
#    define BOOST_DEPRECATED_FUNCTION(_F_) __declspec(deprecated) _F_
#  else if [BUILDING_WITH_GCC]
#    define BOOST_DEPRECATED_FUNCTION(_F_) _F_ __attribute__ ((deprecated))
#  else if [BUILDING_WITH_acme]
#    define BOOST_DEPRECATED_FUNCTION(_F_) ...
#    define BOOST_DEPRECATED_VARIABLE(_V_) ...
#    define BOOST_DEPRECATED_TYPE(_T_) ...
#  end if
#endif

#ifndef BOOST_DEPRECATED_FUNCTION
#  define BOOST_DEPRECATED_FUNCTION(_F_) _F_
#end if

#ifndef BOOST_DEPRECATED_VARIABLE
// Some compilers may use different syntax for variables, if not,
// use same as deprecated function tag
#  define BOOST_DEPRECATED_VARIABLE(_V_) BOOST_DEPRECATED_FUNCTION(_V_)
#endif

#ifndef BOOST_DEPRECATED_TYPE
// As for variables..
#  define BOOST_DEPRECATED_TYPE(_T_) BOOST_DEPRECATED_FUNCTION(_T_)
#endif

Usage example:

class path
{
   ...
   BOOST_DEPRECATED_FUNCTION(string_type native_file_string() const) { 
return file_string(); }
   ...
};

This is noisier, and may be worse if parentheses/comma expansion 
work-arounds are required, but it's an example.

Personally, I prefer the simple BOOST_DEPRECATED, but I don't have 
experience with other compilers to know if that would suffice.  Even if no 
support is available, having a benign tag in the definition provides 
information at the least.

Regards...