What about other big projects? (Qt, boost, ...) Has someone any experience with those?
I just watched the source code of Qt, and they use 1. and 2. for methods, and simple a note for things like enum values (they use 3. only(?) for invalid arguments).
#ifdef QT_DEPRECATED
#define QT_DEPRECATED_SINCE(major, minor) (QT_VERSION_CHECK(major, minor, 0) > QT_DISABLE_DEPRECATED_BEFORE)
#else
#define QT_DEPRECATED_SINCE(major, minor) 0
#endif
// ...
#if QT_DEPRECATED_SINCE(5, 0)
QT_DEPRECATED char toAscii() const { return QChar(*this).toLatin1(); }
#endif
// QT_DEPRECATED expands to __attribute__ ((__deprecated__)) or __declspec(deprecated) or etc.
I needed this functionality for the multi monitor support (http://en.sfml-dev.org/forums/index.php?topic=18950.0) and I didn't know this had been discussed or that this thread existed.
So i just went ahead and implemented it myself. Here is what the code looks like:
////////////////////////////////////////////////////////////
// Cross-platform deprecation warning
////////////////////////////////////////////////////////////
#ifdef __GNUC__
// clang also has this defined. deprecated(message) is only for gcc >= 4.5
#if (__GNUC__ >= 4) && (__GNUC_MINOR__ >= 5)
#define SFML_DEPRECATED(message, func) func __attribute__ ((deprecated(message)))
#else
#define SFML_DEPRECATED(message, func) func __attribute__ ((deprecated))
#endif
#elif defined(_MSC_VER)
#define SFML_DEPRECATED(message, func) __declspec(deprecated(message)) func
#else
#warning WARNING: This compiler does not support SFML_DEPRECATED
#define SFML_DEPRECATED(message, func) func
#endif
(Github for better highlighting) (https://github.com/Foaly/SFML/blob/ee27023318d223de9dc91ef4e149aa31d0a19f5f/include/SFML/Config.hpp#L160)
It is basically a simplified version of the openFrameworks deprecation macro (https://github.com/openframeworks/openFrameworks/blob/master/libs/openFrameworks/utils/ofConstants.h#L35). I have been using it in the past and it worked very good. What I liked especially about it is that it not only emits a warning, but also prints a message. Of course the message has to be set to something helpful that tells the user what to use instead. Example what it could look like:
/home/WAGE06/playground/Foaly_SFML/Source/src/SFML/Window/Unix/WindowImplX11.cpp|1134|warning: ‘static sf::VideoMode sf::VideoMode::getDesktopMode()’ is deprecated (declared at /home/playground/Foaly_SFML/Source/include/SFML/Window/VideoMode.hpp:70): sf::VideoMode::getDesktopMode() is deprected, use sf::Screen::get(0).getDesktopMode() instead. [-Wdeprecated-declarations]
I have used it with variables, types and functions on gcc and experienced no problems. According to this (https://gcc.gnu.org/onlinedocs/gcc/Enumerator-Attributes.html) it should also work with enums but I haven't tested it.
#if (__GNUC__ >= 4) && (__GNUC_MINOR__ >= 5)
#define SFML_DEPRECATED(message, func) func __attribute__ ((deprecated(message)))
This condition check has to be changed. Otherwise this won't apply to versions like 5.0 (since minor is no longer bigger than or equal to 5).