CXX-2978 deprecate functor.hpp

[kevinAlbs]

Summary

Remove undocumented entities in Deprecate use of functor.hpp.

Background & Motivation

I expect the entities in functor.hpp are not intended for public use.

The API policy notes:

The public API is the set of documented entities that are declared or defined in a public header file

The functor.hpp public header is kept to make this change in a minor release. A compile-time warning is added to warn of future removal. If this seems over cautious, the functor.hpp header can be removed in this PR.

Here is a patch build (with a temporary commit to include functor.hpp) to test the #pragma warning: https://spruce.mongodb.com/version/66156de826a8050007e0f117

[eramongodb]

Although the quoted API policy (hopefully) encodes prior intent, I do not think it is entirely safe to apply it to existing noabi interfaces which were implemented and used prior to the explicitly encoded API policy w.r.t. documentation of public interfaces. I believe it is safer to include this in a API major version release. If we want to risk this API breaking change in a minor release with the assumption that no users should be affected by this removal, we should acknowledge so in the release notes and be prepared for a patch release to restore the feature if necessary. Recommend including a CHANGELOG entry in this PR for this reason.

[kevinAlbs]

If we want to risk this API breaking change in a minor release

I would rather err on caution and remove in a major release. Even if there is little risk of
impact, IMO there is little cost to keeping the header and entities until a major release.

The entities have been added back. Updated CXX-2978 to note this is deprecation only. Filed CXX-3003 with fixVersion 4.0.0 for future removal.