Added more well-defined garuntees on deprecation notices in mbed

From the discussion on issue #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;
 }
 
-int testDeprecated() {
-    return testDeprecatedUsed();
+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() + 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 @@ public:
 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 @@ public:
       @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 @@ public:
         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 @@ public:
         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 @@ public:
         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 @@ public:
         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,