Added more well-defined garuntees on deprecation notices in mbed

From the discussion on issue ARMmbed#2068:
Functions marked deprecated in the mbed library should notate when
the deprecation was started to allow efficient removal once a set
amount of time has expired.

Added the following macro:
MBED_DEPRECATED_SINCE("version", "message string")

Example usage:

    MBED_DEPRECATED_SINCE("v5.1", "don't foo any more, bar instead")
    void foo(int arg);

Adopted in existing deprecations:
- FunctionPointer
- RtosTimer
- Thread

TESTS/mbedmicro-mbed/attributes/attributes.c

@@ -137,7 +137,17 @@ int testDeprecatedUsed() {
  return 0;
 }
 
+MBED_DEPRECATED_SINCE("v3.14", "this message should not be displayed")
+void testDeprecatedSinceUnused();
+void testDeprecatedSinceUnused() { }
+
+MBED_DEPRECATED_SINCE("v3.14", "this message should be displayed")
+int testDeprecatedSinceUsed();
+int testDeprecatedSinceUsed() {
+ return 0;
+}
+
 int testDeprecated() {
- return testDeprecatedUsed();
+ return testDeprecatedUsed() + testDeprecatedSinceUsed();
 }
 

hal/api/FunctionPointer.h

@@ -29,12 +29,14 @@ namespace mbed {
 template <typename R, typename A1>
 class FunctionPointerArg1 : public Callback<R(A1)> {
 public:
- MBED_DEPRECATED("FunctionPointerArg1<R, A> has been replaced by Callback<R(A)>")
+ MBED_DEPRECATED_SINCE("v5.1",
+ "FunctionPointerArg1<R, A> has been replaced by Callback<R(A)>")
  FunctionPointerArg1(R (*function)(A1) = 0)
  : Callback<R(A1)>(function) {}
 
  template<typename T>
- MBED_DEPRECATED("FunctionPointerArg1<R, A> has been replaced by Callback<R(A)>")
+ MBED_DEPRECATED_SINCE("v5.1",
+ "FunctionPointerArg1<R, A> has been replaced by Callback<R(A)>")
  FunctionPointerArg1(T *object, R (T::*member)(A1))
  : Callback<R(A1)>(object, member) {}
 
@@ -46,12 +48,14 @@ class FunctionPointerArg1 : public Callback<R(A1)> {
 template <typename R>
 class FunctionPointerArg1<R, void> : public Callback<R()> {
 public:
- MBED_DEPRECATED("FunctionPointer has been replaced by Callback<void()>")
+ MBED_DEPRECATED_SINCE("v5.1",
+ "FunctionPointer has been replaced by Callback<void()>")
  FunctionPointerArg1(R (*function)() = 0)
  : Callback<R()>(function) {}
 
  template<typename T>
- MBED_DEPRECATED("FunctionPointer has been replaced by Callback<void()>")
+ MBED_DEPRECATED_SINCE("v5.1",
+ "FunctionPointer has been replaced by Callback<void()>")
  FunctionPointerArg1(T *object, R (T::*member)())
  : Callback<R()>(object, member) {}
 

hal/api/toolchain.h

@@ -207,7 +207,7 @@
  * Mark a function declaration as deprecated, if it used then a warning will be
  * issued by the compiler possibly including the provided message. Note that not
  * all compilers are able to display the message.
- * 
+ *
  * @code
  * #include "toolchain.h"
  * 
@@ -225,6 +225,21 @@
 #endif
 #endif
 
+/** MBED_DEPRECATED_SINCE("version", "message string")
+ * Mark a function declaration as deprecated, noting that the declaration was
+ * deprecated on the specified version. If the function is used then a warning
+ * will be issued by the compiler possibly including the provided message.
+ * Note that not all compilers are able to display this message.
+ *
+ * @code
+ * #include "toolchain.h"
+ *
+ * MBED_DEPRECATED_SINCE("v5.1", "don't foo any more, bar instead")
+ * void foo(int arg);
+ * @endcode
+ */
+#define MBED_DEPRECATED_SINCE(D, M) MBED_DEPRECATED(M " [since " D "]")
+
 
 // FILEHANDLE declaration
 #if defined(TOOLCHAIN_ARM)

rtos/rtos/RtosTimer.h

@@ -44,7 +44,8 @@ class RtosTimer {
  @param argument argument to the timer call back function. (default: NULL)
  @deprecated Replaced with RtosTimer(Callback<void()>, os_timer_type)
  */
- MBED_DEPRECATED("Replaced with RtosTimer(Callback<void()>, os_timer_type)")
+ MBED_DEPRECATED_SINCE("v5.1",
+ "Replaced with RtosTimer(Callback<void()>, os_timer_type)")
  RtosTimer(void (*func)(void const *argument), os_timer_type type=osTimerPeriodic, void *argument=NULL) {
  constructor(mbed::Callback<void()>(argument, (void (*)(void *))func), type);
  }

rtos/rtos/Thread.h

@@ -58,7 +58,7 @@ class Thread {
  The explicit Thread::start member function should be used to spawn
  a thread.
  */
- MBED_DEPRECATED(
+ MBED_DEPRECATED_SINCE("v5.1",
  "Thread-spawning constructors hide errors and may lead to complex "
  "program state when a thread is declared")
  Thread(mbed::Callback<void()> task,
@@ -83,7 +83,7 @@ class Thread {
  a thread.
  */
  template <typename T>
- MBED_DEPRECATED(
+ MBED_DEPRECATED_SINCE("v5.1",
  "Thread-spawning constructors hide errors and may lead to complex "
  "program state when a thread is declared")
  Thread(T *obj, void (T::*method)(),
@@ -109,7 +109,7 @@ class Thread {
  a thread.
  */
  template <typename T>
- MBED_DEPRECATED(
+ MBED_DEPRECATED_SINCE("v5.1",
  "Thread-spawning constructors hide errors and may lead to complex "
  "program state when a thread is declared")
  Thread(T *obj, void (*method)(T *),
@@ -134,7 +134,7 @@ class Thread {
  The explicit Thread::start member function should be used to spawn
  a thread.
  */
- MBED_DEPRECATED(
+ MBED_DEPRECATED_SINCE("v5.1",
  "Thread-spawning constructors hide errors and may lead to complex "
  "program state when a thread is declared")
  Thread(void (*task)(void const *argument), void *argument=NULL,