CXX-2762 Ensure ABI namespace is included in API documentation

[eramongodb]

Resolves CXX-2762. Verified by this patch.

Description

Despite the diffs to source code, this PR is primarily focused on changes to generated documentation, not the source code itself. Most of the diff is due to replacing use of the inline namespace macros with inline namespace v_noabi. This is to allow Doxygen to understand the declaration scope of entities within the inline namespace, as it is incapable of reading into the expansion of the inline namespace macro, and Doxygen does not provide a means to manually open/close a namespace for documentation purposes. Explicitly substituting the macros appears to be the only method for ensuring namespace-awareness in documentation.

To elaborate, using the mongocxx::instance class as an example, the current API documentation generates the class list as follows:

mongocxx
├── instance
└── ...

And the class reference page has no awareness of its actual declaration within the v_noabi inline namespace:

mongocxx::instance Class Reference

This is an issue if we want to add documentation for upcoming v1 namespace entities in a manner that distinguishes v1 entities from v_noabi entities, in particular if we want to support a mix of vN entities in the root namespace. The result of the changes in this PR changes the class index to:

mongocxx
├── v_noabi
│   ├── instance
│   └── ...
├── instance (v_noabi/instance)
└── ...

And the class reference to:

mongocxx::v_noabi::instance Class Reference

The instance class appears twice in the class index to reflect inline namespace behavior (mongocxx::instance and mongocxx::v_noabi::instance). The duplication of entities in the lists under the root and v_noabi namespace may seem redundant, but this is correct behavior: the root namespace declaration may redirect to any vN namespace declaration instead (e.g. mongocxx::instance -> mongocxx::v1::instance) depending on the state of compatibility with prior ABI versions and/or the unstable ABI (i.e. eventual v_noabi -> v1 source-but-not-binary-breaking changes). The changes in this PR enables the generated API documentation to make this distinction rather than tying the root namespace declaration to the entity in the currently inlined namespace (there is no actual mongocxx::instance; it's actually mongocxx::v_noabi::instance).

Ensuring proper inclusion of the ABI namespace in Doxygen required a definitive Doxygen comment for the enclosing namespaces. This is currently done in ad-hoc locations (json.hpp for the bsoncxx namespace, client.hpp for the mongocxx namespace). This PR moves the namespace documentation comments into the prelude headers for each respective library for uniformity.

Drive-By Improvements

• Update the Doxyfile configuration to account for the directory restructure made in CXX-2753 Refactor directory structure to allow for multiple ABI namespaces #1026. Note: only non-generated, public header files are given as input to Doxygen. Implementation, private, and test files are ignored even if they still contain Doxygen comments (which can be useful for IDE-integration purposes even if they don't end up in generated documentation). This better reflects the intended input to Doxygen even prior to the directory restructure.
• Address various warnings currently generated by Doxygen, including:
  • Undocumented public classes (chunks_and_bytes_offset, rewrap_many_datakey).
  • Redundant/useless @relates in friend declarations.
  • Undocumented/misdocumented parameters.
  • Ambiguous/unclear friend declarations (missing class key and/or forward declaration).
  • Missing parameter documentation in grouped member functions in mongocxx::gridfs::bucket: used @copydoc instead to allow appending parameter documentation.
  • Missing @code/@endcode commands to wrap literal blocks (<> is incorrectly parsed as XML).

[kevinAlbs]

LGTM with removal of unused macros.

[eramongodb]

Resolved merge conflicts.

Also added some missing generated macros to the Doxyfile to address parsing issues for certain entities (i.e. misinterpreting typedefs as variable declarations).

[eramongodb]

To further account for changes in #1028, documentation for the bsoncxx::v_noabi::stdx namespace was added so that entities declared within (i.e. our own make_unique()) are included in generated documentation.

Additionally, exclusion filters for detail namespaces under bsoncxx:: and mongocxx:: were added to silence Doxygen warnings for undocumented symbols within (i.e. make_unique_impl).