Added a BOOST_DEPRECATED macro for deprecated symbol markup.

BOOST_DEPRECATED can be used to mark functions, types and objects as
deprecated, with a message with a recommendation of replacement. Using
such marked symbols in code will generate compiler warnings, with the
specified message, if possible.

The warnings can be suppressed if BOOST_ALLOW_DEPRECATED_SYMBOLS is defined.
Additionally, added support BOOST_ALLOW_DEPRECATED macro that not only
allows for deprecated symbols but also deprecated headers (i.e. defining
BOOST_ALLOW_DEPRECATED is equivalent to defining both
BOOST_ALLOW_DEPRECATED_SYMBOLS and BOOST_ALLOW_DEPRECATED_HEADERS).

doc/macro_reference.qbk

@@ -1423,6 +1423,27 @@ Usage example:
   typedef unsigned int BOOST_MAY_ALIAS aliasing_uint;
 ``
 ]]
+[[`BOOST_DEPRECATED(M)`][Expands to an attribute for a symbol that generates warnings when that
+symbol is used in code. The warnings may contain a message `M`, which must be a string literal.
+This attribute may be applied to types, functions or objects and is typically used to mark
+parts of the API as deprecated with a recommendation of replacement.
+
+Example:
+``
+BOOST_DEPRECATED("Use bar() instead.")
+void foo();
+
+template< typename T >
+class BOOST_DEPRECATED("Use std::unique_ptr instead.") auto_ptr
+{
+};
+
+BOOST_DEPRECATED("Use std::numeric_limits<int>::max() instead.")
+const int max_int = 0x7fffffff;
+``
+
+The warnings issued by `BOOST_DEPRECATED` can be suppressed by defining
+`BOOST_ALLOW_DEPRECATED_SYMBOLS` or `BOOST_ALLOW_DEPRECATED` macros.]]
 [[`BOOST_PRAGMA_MESSAGE(M)`][Defined in header `<boost/config/pragma_message.hpp>`,
 this macro expands to the equivalent of `#pragma message(M)`. `M` must be a string
 literal.
@@ -1438,8 +1459,8 @@ this macro issues the message "This header is deprecated. Use `A` instead." via
 
 Example: `BOOST_HEADER_DEPRECATED("<boost/config/workaround.hpp>")`
 
-The messages issued by `BOOST_HEADER_DEPRECATED` can be suppressed by defining the macro
+The messages issued by `BOOST_HEADER_DEPRECATED` can be suppressed by defining
-`BOOST_ALLOW_DEPRECATED_HEADERS`.]]
+`BOOST_ALLOW_DEPRECATED_HEADERS` or `BOOST_ALLOW_DEPRECATED` macros.]]
 ]
 
 [endsect]

include/boost/config/compiler/clang.hpp

@@ -325,11 +325,18 @@
 // All versions with __cplusplus above this value seem to support this:
 #  define BOOST_NO_CXX14_DIGIT_SEPARATORS
 #endif
-//
+
-// __builtin_unreachable:
+// Unreachable code markup
-#if defined(__has_builtin) && __has_builtin(__builtin_unreachable)
+#if defined(__has_builtin)
+#if __has_builtin(__builtin_unreachable)
 #define BOOST_UNREACHABLE_RETURN(x) __builtin_unreachable();
 #endif
+#endif
+
+// Deprecated symbol markup
+#if __has_attribute(deprecated)
+#define BOOST_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#endif
 
 #if (__clang_major__ == 3) && (__clang_minor__ == 0)
 // Apparently a clang bug:

include/boost/config/compiler/gcc.hpp

@@ -340,12 +340,18 @@
 // Type aliasing hint. Supported since gcc 3.3.
 #define BOOST_MAY_ALIAS __attribute__((__may_alias__))
 
-//
+// Unreachable code markup
-// __builtin_unreachable:
 #if BOOST_GCC_VERSION >= 40500
 #define BOOST_UNREACHABLE_RETURN(x) __builtin_unreachable();
 #endif
 
+// Deprecated symbol markup
+#if BOOST_GCC_VERSION >= 40500
+#define BOOST_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#else
+#define BOOST_DEPRECATED(msg) __attribute__((deprecated))
+#endif
+
 #ifndef BOOST_COMPILER
 #  define BOOST_COMPILER "GNU C++ version " __VERSION__
 #endif
@@ -359,7 +365,7 @@
 
 // versions check:
 // we don't know gcc prior to version 3.30:
-#if (BOOST_GCC_VERSION< 30300)
+#if (BOOST_GCC_VERSION < 30300)
 #  error "Compiler not configured - please reconfigure"
 #endif
 //

include/boost/config/compiler/sunpro_cc.hpp

@@ -86,6 +86,12 @@
 #  define BOOST_SYMBOL_VISIBLE __global
 #endif
 
+// Deprecated symbol markup
+// Oracle Studio 12.4 supports deprecated attribute with a message; this is the first release that supports the attribute.
+#if (__SUNPRO_CC >= 0x5130)
+#define BOOST_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#endif
+
 #if (__SUNPRO_CC < 0x5130)
 // C++03 features in 12.4:
 #define BOOST_NO_TWO_PHASE_NAME_LOOKUP

include/boost/config/compiler/visualc.hpp

@@ -107,6 +107,14 @@
 #  define BOOST_NO_RTTI
 #endif
 
+// Deprecated symbol markup
+#if (_MSC_VER >= 1400)
+#define BOOST_DEPRECATED(msg) __declspec(deprecated(msg))
+#else
+// MSVC 7.1 only supports the attribute without a message
+#define BOOST_DEPRECATED(msg) __declspec(deprecated)
+#endif
+
 //
 // TR1 features:
 //

include/boost/config/compiler/xlcpp.hpp

@@ -270,6 +270,10 @@
 #  define BOOST_NO_CXX14_DIGIT_SEPARATORS
 #endif
 
+// Deprecated symbol markup
+#if __has_attribute(deprecated)
+#define BOOST_DEPRECATED(msg) __attribute__((deprecated(msg)))
+#endif
 
 // Unused attribute:
 #if defined(__GNUC__) && (__GNUC__ >= 4)

include/boost/config/detail/suffix.hpp

@@ -668,6 +668,23 @@ namespace std{ using ::type_info; }
 #  define BOOST_NORETURN
 #endif
 
+// BOOST_DEPRECATED -------------------------------------------//
+// The macro can be used to mark deprecated symbols, such as functions, objects and types.
+// Any code that uses these symbols will produce warnings, possibly with a message specified
+// as an argument. The warnings can be suppressed by defining BOOST_ALLOW_DEPRECATED_SYMBOLS
+// or BOOST_ALLOW_DEPRECATED.
+#if !defined(BOOST_DEPRECATED) && __cplusplus >= 201402
+#define BOOST_DEPRECATED(msg) [[deprecated(msg)]]
+#endif
+
+#if defined(BOOST_ALLOW_DEPRECATED_SYMBOLS) || defined(BOOST_ALLOW_DEPRECATED)
+#undef BOOST_DEPRECATED
+#endif
+
+#if !defined(BOOST_DEPRECATED)
+#define BOOST_DEPRECATED(msg)
+#endif
+
 // Branch prediction hints
 // These macros are intended to wrap conditional expressions that yield true or false
 //

include/boost/config/header_deprecated.hpp

@@ -17,7 +17,7 @@
 
 #include <boost/config/pragma_message.hpp>
 
-#if defined(BOOST_ALLOW_DEPRECATED_HEADERS)
+#if defined(BOOST_ALLOW_DEPRECATED_HEADERS) || defined(BOOST_ALLOW_DEPRECATED)
 # define BOOST_HEADER_DEPRECATED(a)
 #else
 # define BOOST_HEADER_DEPRECATED(a) BOOST_PRAGMA_MESSAGE("This header is deprecated. Use " a " instead.")

test/Jamfile.v2

@@ -113,6 +113,7 @@ test-suite config
     [ run helper_macros_test.cpp ]
     [ compile pragma_message_test.cpp ]
     [ compile header_deprecated_test.cpp ]
+    [ compile symbol_deprecated_test.cpp ]
     [ compile boost_override_test.cpp ]
   ;
 
@@ -147,4 +148,3 @@ explicit print_math_info ;
 exe config_info_travis : config_info.cpp ;
 install config_info_travis_install : config_info_travis : <location>. ;
 explicit config_info_travis_install ;
-

test/symbol_deprecated_test.cpp

@@ -0,0 +1,19 @@
+//  Copyright 2022 Andrey Semashev.
+//
+//  Distributed under the Boost Software License, Version 1.0.
+//
+//  See accompanying file LICENSE_1_0.txt or copy at
+//  http://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/config.hpp>
+
+BOOST_DEPRECATED("Use bar() instead.")
+void foo();
+
+template< typename T >
+class BOOST_DEPRECATED("Use std::unique_ptr instead.") my_auto_ptr
+{
+};
+
+BOOST_DEPRECATED("Use std::numeric_limits<int>::max() instead.")
+const int max_int = 0x7fffffff;