This documents describes a proposal for providing authors of C++ libraries with a standard facility to mark code entities as deprecated.
Libraries change with time. Sometimes features are replaced by more powerful ones, or are found to be inherently flawed. A common way for library writers to deal with this problem is to recommend against such old features, i.e., to mark them as deprecated.
Right now there is no standard means of doing that. Library writers are thus forced to either simply document them as deprecated, or to use the preprocessor to decide upon one of the various compiler extensions that exist to support this feature.
At least three major compilers support this feature as an extension: MSVC uses __declspec(deprecated), GCC and Clang use __attribute__((deprecated)). Both clang and MSVC let the user provide an optional string literal argument that is included in the warning messages generated.
This proposal is intended to standardize the various attributes provided by compilers for feature deprecation.
This proposal has little impact on the current standard, as it consists solely of the addition of an attribute, which does not change program semantics.
This feature may be used within the standard library itself, by marking deprecated standard library features like auto_ptr with this attribute.
The design for this feature was chosen to match the existing compiler extensions, but adapted to the C++ generalized attribute syntax.
This feature consists of a simple attribute named deprecated that can be applied to most code entities that an attribute can be applied to. It cannot be applied to function arguments nor inside function bodies.
Optionally, the user may provide a string literal argument that implementations can use in diagnostic messages.
Implementations can ignore this attribute without any change in program semantics, because it is merely informative. They are however, encouraged to emit warnings whenever an entity marked deprecated is used in a program, if the entities that use them are not marked deprecated as well.
#include <memory>
[[deprecated("This function breaks things. Use fixed_function() instead.")]]
void broken_function();
int main() {
std::auto_ptr<int> p; // generates warning similar to:
// The class template auto_ptr is deprecated. The class template unique_ptr provides a better solution.
broken_function(); // generates warning similar to:
// The function broken_function is deprecated. This function breaks things. Use fixed_function() instead.
}