CXX-2745 add v1 forward headers and component files (bsoncxx)

[eramongodb]

Summary

An intermediate PR related to CXX-2745 following #1318 and #1323.

This PR is focused on adding (non-internal) component files, implementing forward declarations, and adding API documentation stubs for bsoncxx v1 interfaces to be implemented in upcoming PRs. This PR is a "lightweight" preview of the bsoncxx v1 interface, file structure, and corresponding API documentation. The v1 interfaces themselves (data members, member functions, and non-member functions) will be implemented in a followup PR.

Relative Changelog (v1 <- v_noabi)

Additional Features

• X-macros over BSON types and subtypes: BSONCXX_V1_TYPES_XMACRO and BSONCXX_V1_BINARY_SUBTYPES_XMACRO.
  • Replaces the X-macro header #include pattern.
  • Much friendlier pattern for IDEs and compiler diagnostics.
  • Renamed binary_sub_type to binary_subtype for terminology consistency (e.g. Drivers Specifications, MongoDB Manual, and BSON Spec).
• bsoncxx::v1::error for user-facing error conditions. (CXX-834)
  • The "better" approach to mongoc_error_domain_t.
    • "Domains" are component-specific error codes (enumerations).
    • Avoids global error value enumerations (i.e. mongoc_error_domain_t, bsoncxx::v_noabi::error_code, etc.).
  • Most users likely do not programmatically require an expansive and detailed set of error values.
    • Most users likely only handle errors by read-inspect the corresponding error messages.
    • Provide only bare minimum set of error conditions which users are most likely to programmatically care about:
      • source: library or application from which the error comes from.
      • type: invalid argument (due to user error), runtime error (not due to user error).
  • To be explored in further detail in upcoming PRs.

Changed Features

• Headers under types/bson_value/ (v_noabi) are moved up into types/ (v1).
  • types/value.hpp (v_noabi) was removed in CXX-3158.
  • types/view.hpp (v1) <- types/bson_value/view.hpp (v_noabi)
  • types/value.hpp (v1) <- types/bson_value/value.hpp (v_noabi)
  • bson_value is removed to avoid confusion with highly overloaded "value" terminology.
• BSON type "elements" are moved into types/element.hpp.
  • Enumerations remain in types.hpp.
  • Symmetry with array/ and document/ components.
  • Avoid pulling in large number of transitive dependencies required to represent BSON types when only the enumerations are required.
  • Avoid messy circular dependency issues between types.hpp (v_noabi) and types/*.hpp (v_noabi) headers.
• Grouped exception/exception.hpp (v_noabi) and exception/error_code.hpp (v_noabi) into a single exception.hpp (v1) header.

Removed Features

• enums/*.hpp.
  • Replaced by new X-macros provided by types-fwd.hpp.
• view_or_value.hpp. (CXX-1827)
  • Adopt C++ convention established by std::string and std::string_view.
  • To be explored in further detail in upcoming PRs.
• string/to_string.hpp.
  • Already superceded by the explicit conversion operator in stdx::string_view emulating explicit std::string::string(std::string_view).

Skipped/Deferred Features

• BSON builders (basic, stream, and JSON).
  • Defer exploration of BSON builder redesign which requires dedicated effort beyond the scope of v1 migration (CXX-997, CXX-1634, CXX-2115, etc.)
  • Interim workaround: use v_noabi builders to create v_noabi documents, then convert v_noabi documents to v1 documents using to_v1() (to be explored in further detail in upcoming PRs; see this comment for a preview of the expected pattern).

Absolute Changelog (v_noabi)

• None.

API Documentation

Stubs

Deliberately kept minimal at the moment.

All forward-declared v1 interfaces are currently labeled with the following message:

Attention This feature is experimental! It is not ready for use!

This message will be updated as their interfaces are filled and implemented going forward.

Embedded API Examples

• X-Macros: first instance of an embedded example using \par "Example" and Markdown codeblocks when a dedicated API Examples page is not necessary.

Component File Structure

A component's headers are always included before any other header to mitigate against dependency resolution via transitive inclusion.

• A "forward" header (foo-fwd.hpp) is at the top of the component header hierarchy.
• A "normal" header (foo.hpp) includes the forward header first.
• An "internal" header (foo.hh) includes the normal header first.
• An "implementation" (aka source) file (foo.cpp) includes the internal or normal header first.

This is enforced by inserting a blank // comment between the component header and other dependency headers, including macro guard headers.

The source file contains out-of-line definitions for interfaces provided by both the normal and internal header. Non-trivial function definitions or those which introduce additional header dependencies should preferably be moved into implementation files to minimize cost of (re)compilation when such headers are updated (keep the include dependency graph "wide" rather than "tall").

[kevinAlbs]

Consider moving binary_subtype into the types namespace to colocate with b_binary. I expect it is mainly used to create a b_binary.

[kevinAlbs]

Suggest making the X-macros private. I expect the binary subtype macro will expand in the future (e.g. CXX-3077 adds subtype 9). I expect adding a value could be considered an API break.

[eramongodb]

I believe there is still value to providing these X-macros as part of the public API.

Added documentation clarifying the compatibility guidelines for using X-macros with the following admonition:

Important

The addition of new expansions to this X-macro ARE NOT considered an API breaking change.
The modification or removal of existing expansions to this X-macro ARE considered an API breaking change.
This X-macro MUST be used in a manner that is compatible with these API compatibility guidelines!

In short, users are expected to use these X-macros in a manner that accounts for the possibility of extension.

[kevinAlbs]

I interpret "element" to mean "key/value pair" from https://bsonspec.org/spec.html. But the b_* structs only represent the "value" part of the pair.

Consider renaming element.hpp to types.hpp.

[eramongodb]

Closing due to significant refactors required to accomodate proposed refactors for element and types interfaces + pending additions to the bsoncxx API. A successor PR with renewed changes will be posted instead when ready.