CXX-3231 add v1 forward headers and component files

[eramongodb]

Resolves CXX-3231. Followup to #1336.

As initially attempted in #1336, this PR is a "lightweight" preview of the bsoncxx v1 interface, file structure, and corresponding API documentation. Relevant details from #1336 are copied here for locality and updated with latest changes.

---

• Relative Changelog (v_noabi -> v1):
  • Additional Features:
    • X macros over BSON types and subtypes: BSONCXX_V1_TYPES_XMACRO and BSONCXX_V1_BINARY_SUBTYPES_XMACRO.
    • bsoncxx::v1::error for user-facing error conditions. This will be elaborated in greater detail in the followup "interfaces" PR.
  • Changed Features:
    • Classes types::bson_value::view (v_noabi) and types::bson_value::value (v_noabi) are now types::view (v1) and types::value (v1).
    • Enumerators type (v_noabi) and binary_sub_type are now types::id (v1) and types::binary_subtype (v1). A type alias for both will be provided in the v_noabi namespace to assist with incremental upgrades.
    • Classes document::element (v_noabi) and array::element (v_noabi) are now represented by a single class element::view. Type aliases for all three will be provided in the v_noabi namespace to assist with incremental upgrades.
    • The exception class exception is now provided by exception.hpp (v1) rather than exception/exception.hpp (v_noabi) to be consistent with its namespace scope.
  • Removed Features:
    • enums/*.hpp: replaced by new X macros.
    • exception/error_code.hpp: folded into exception.hpp (v1) and replaced by component-specific error codes.
    • string::to_string: supported by the explicit conversion operator in stdx::string_view.
    • view_or_value: see CXX-1827.
  • Skipped Features (to be implemented after the initial stable ABI release):
    • BSON builders (basic, json, list, stream).
    • BSON binary vector API.
    • BSON validators.
• Absolute Changelog (v_noabi):
  • None.

---

Details and rationale:

• element::view (and element::value)
  • Motivated by feedback concerning the confusing terminology regarding "views", "values", and "elements".
  • Component structure is now completely symmetric:
    • array: view + value.
    • document: view + value.
    • element: view (+ value).
    • types: view + value.
  • The design space for element::value is left open as an owning equivalent to element::view and a possible successor to builder::basic::kvp (v_noabi) as part of the potential redesign of BSON builders.
• types::view and types::value:
  • mirrors the "non-owning, read-only" vs. "owning" relationship established by document and array class types.
  • all "BSON type"-related entities are now declared under the types (v1) namespace (avoiding the type vs. types confusion):
    • id: a "BSON type" or "BSON type id", formerly type.
    • binary_subtype: a "BSON binary subtype", formerly binary_sub_type.
    • b_*: "BSON type values" (the value of a BSON element without a key).
    • view: a non-owning, read-only union of BSON type values.
    • value: an owning union of BSON type values.
• error and exception:
  • The error namespace will contain declarations for error code enumerations and corresponding error categories which describe component-specific errors which may be thrown by the v1 interface.
  • The source and type error conditions are expected to be the primary means by which users programmatically inspect the cause of thrown errors. This will be elaborated in greater detail in the upcoming "interfaces" PR.
  • The error code enumerations for individual components are not forward-declared due to dubious value (it is unlikely that users will be handling component-specific error codes without already including the corresponding component interface header). These will be introduced in the upcoming "interfaces" PR.
  • Users are expected to eventually handle exceptions from both v_noabi and v1 namespaces by catching std::system_error instead of ABI-specific exception types. The v_noabi API will continue to throw v_noabi::exception even if the underlying implementation is refactored to use v1 API for backward compatibility.

[kevinAlbs]

LGTM with one typo fix. I very much support combining document::element and array::element into element::view.

[kevinAlbs]

Suggested change

	/// @copydoc bsoncxx::array
	/// @copydoc bsoncxx::document