v1::read_preference (CXX-3237, CXX-3238)

[eramongodb]

Resolves CXX-3237 and CXX-3238 for the v1::read_preference component.

The deprecated v_noabi ctors and the .hedge() accessors are left as-is, to be removed in an upcoming major release. Note that this PR proposes v1 includes .hedge() in the definition of operator==(), as "hedge" is still "a supported field" despite its deprecation. This can be removed in favor of v_noabi's behavior which excludes "hedge" if that is preferable.

[kevinAlbs]

I expect inlining the previously ABI exported methods is an ABI breaking change to the (unstable) v_noabi. I think that is OK. Consider noting ABI removals in the changelog (if not already planned) as done with previous ABI removal notes.

A generic note may be appropriate:

v_noabi ABI exports have been made inline. Consumers must recompile`

I expect many v_noabi classes will be re-implemented in terms of v1. And this may just be a useful heads up that a recompile is needed.

[eramongodb]

Rather than enumerating all of the individual exported symbols removed in the 4.2.0 release, added an "Important" admonition at the top of the 4.2.0 release section indicating to users that recompilation is required to link against the new library release. Users should be recompiling against every release given the lack of a stable ABI guarantee, but nevertheless, this release deserves a reminder.

[kevinAlbs]

Not introduced in this PR, but suggested drive-by fix of incorrect comment:

Suggested change

	/// Sets or updates the tag set list for this read_preference.
	/// Gets the tag set list for this read_preference.

[kevinAlbs]

Prior to this PR, using a value outside of the enum hits a BSON_UNREACHABLE:

// Prior to this PR:
TEST_CASE("Bad read mode", "[read_preference]") {
    read_preference rp;
    rp.mode(static_cast<mongocxx::v_noabi::read_preference::read_mode>(-1)); // Abort!
}

Suggest restoring this behavior (or throwing an exception?). That may help add a future read_mode enumerator without concern for breaking consumers. E.g. if consumers are relying on 5 meaning primary, adding a new read mode might later break that assumption.

[eramongodb]

Fixed/updated the read preference setter documentation for consistency with other enum field setters: users should not be passing any inputs which are not explicitly permitted in the list (precondition violation). Rather than termination or exceptions, the intent is to have undocumented well-defined behavior as permitted by precondition violation. Changing the behavior of e.g. the value of 5 in a subsequent release does not constitute an API breaking change, as a user using said value prior to that release is violating the function contract.