Annotate deprecated C++ APIs with [[deprecated(msg)]]

[bdash]

What is the feature you'd like to have?
C++ APIs that have been deprecated are currently only marked as deprecated in their documentation comments. Only the most diligent API users are aware of these as they require closely read the API header or documentation to identify which methods are deprecated, and then searching their codebase to identify whether they're used.

C++14 introduced the [[deprecated(msg)]] attribute that can be added to symbols. Compilers will emit warnings when deprecated symbols are used. This makes it immediately obvious to API users when they are still using a deprecated API.

If a user builds with -Werror, meaning deprecation warnings would break their build, and they're unable to immediately update the usage of the deprecated API, they can either:

1. Add -Wno-error=deprecated-declarations to disable warnings as errors only for deprecation warnings. I'm not sure if there's an MSVC equivalent for this.

2. Wrap usage of the deprecated API in:

   #pragma GCC diganostic push
   #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
   // Use of deprecated API here
   #pragma GCC diagnostic pop
   

   The MSVC equivalent involves #pragma warning(push) and #pragma warning(disable: 4996).

Both options are temporary measures, intended only to quiet noise while the API user works towards updating the code. Deprecated APIs will be eventually be removed and code using them will need to be updated or it will inevitably break.