[CDRIVER-5916] Deprecate the Hedged-Reads APIs

[vector-of-bool]

Background

Refer: CDRIVER-5916

DRIVERS-2929 is be a spec update that deprecates Hedge Reads in driver APIs. This changeset adds such deprecation warnings, among other things.

Summary

This does not change any library behavior, it only adds deprecation warnings, and updates those that already exist. Per-commit review is recommended:

• c17b30f Adds new deprecation attribute macros that work on MSVC, to replace the BSON_GNUC_DEPRECATED macros. This macro always requires a deprecation message string, which will be included in the emitted attribute if it is supported by the compiler.
• ef8347b Updates all existing deprecation attributes to use the new macros:
  • This also applies a formatting change and repositions the attributes for MSVC compatibility.
  • We also add several macros to .clang-format's AttributeMacros to format them as declaration specifiers on functions.
  • Lots of headers have had whitespace inserted between function declarations, where it was becoming nigh unreadable.
  • Because deprecation warnings are now applied on MSVC, a new deprecation-warning-suppression had to be added to bson-atomic.h and bson-cmp.h
  • This commit is the largest change, and was largely a find-replace job.
• 0da23b0 Adds an internal declaration-like macro that emits the appropriate _Pragma to disable deprecation warnings.
• 4cc8a97 Adds deprecation annotations to "hedge" APIs, and updates the documentation to note the deprecation. Warning suppressions were added in internal locations where the hedged-read APIs are called.

Note on Attribute Placement:

MSVC attributes are declaration-specifiers (thus "__declspec"), and thus need to be positioned correctly. The following is ill-formed:

int*
BSON_DEPRECATED("oof")
foo();

because the __declspec is placed between the asterisk and the function name (not a valid position for declaration specifiers). GCC accepts this form, but we cannot use it for compatibility. One possible correct formatting for this declaration would be:

int
BSON_DEPRECATED("oof")
* foo();

but that is a extremely weird, so it's easier to just place the deprecation before the return type:

BSON_DEPRECATED("oof")
int* foo();

This has been applied throughout the codebase in ef8347b.

[kevinAlbs]

The MSVC deprecation warnings and additional deprecation warning strings are much appreciated. LGTM with comments addressed.

[kevinAlbs]

Add back deprecation warning:

BSON_DEPRECATED_FOR (bson_as_legacy_extended_json)
BSON_EXPORT (char *) bson_as_json (const bson_t *bson, size_t *length);