Deprecate attribute - documentation

[0xc0170]

@pan- asked a good question - the deprecate attribute documentation

This should be stated in the documentation, what's the intention with MBED_DEPRECATED.

Shall we state a lifetime of deprecated attribute ? The idea there would be to keep the track of them, automated removal for the releases, and provide time estimation for users to update their programs, or stay within their current used release.

@pan- @geky @mjs-arm @sg-

[geky]

+1 I have no strong feelings. We should retain the general purpose MBED_DEPRECATED attribute for user libraries to repurpose, but it is easy to add a MBED_DEPRECATED_UNTIL(221, "message").

@BlackstoneEngineering has previously noted that in order to keep an impression of stability, we should have a hard minimum of 6 months between marking as deprecated and removing, which should be appropriately documented.

[BlackstoneEngineering]

Yeah, 2 quarters is usually a good amount of time, during which we upgrade the warning progressively so it goes from working to emitting a warning to emitting an error. This is how @rgrover did it in the BLE API libs and it worked pretty damn well to get people to move where we wanted them to.

[ciarmcom]

ARM Internal Ref: IOTMORF-148

[sg-]

Seems to be resolved.