CXX-3069 document directories, namespaces, and generated headers (#1173)

Author: eramongodb

src/bsoncxx/include/bsoncxx/fwd.hpp

@@ -16,7 +16,83 @@
 #error "This file is for documentation purposes only. It should not be included."
 #endif  // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
 
+///
+/// @file
+/// For documentation purposes only.
+///
+/// This header is not intended to be includable.
+///
+/// @note This header is shadowed by @ref bsoncxx/v_noabi/bsoncxx/fwd.hpp per include directory
+/// search ordering.
+///
+
+///
+/// @dir bsoncxx/include/bsoncxx
+/// Provides headers declaring entities in @ref bsoncxx
+///
+
 ///
 /// @namespace bsoncxx
-/// The top-level namespace for bsoncxx library entities.
+/// The top-level namespace within which all bsoncxx library entities are declared.
+///
+/// In addition to declaring ABI namespaces (`v_noabi`, `v1`, etc.), this namespace also provides
+/// "redeclarations" of entities within ABI namespaces. These redeclarations are intended to be the
+/// preferred method for using bsoncxx library entities when ABI stability of the bsoncxx library is
+/// NOT a requirement by the user. See [Root Namespace
+/// Redeclarations](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/api-abi-versioning/abi-versioning/#std-label-cpp-abi-root-namespace-redec).
+///
+
+///
+/// @namespace bsoncxx::array
+/// Declares entities representing a BSON array.
+///
+
+///
+/// @namespace bsoncxx::builder
+/// Declares entities used to build BSON documents.
+///
+
+///
+/// @namespace bsoncxx::builder::basic
+/// Declares entities used with "basic" BSON builder syntax.
+///
+
+///
+/// @namespace bsoncxx::builder::stream
+/// Declares entities used with "streaming" BSON builder syntax.
+///
+
+///
+/// @namespace bsoncxx::document
+/// Declares entities representing a BSON document.
+///
+
+///
+/// @namespace bsoncxx::exception
+/// Declares entities related to bsoncxx exceptions and error codes.
+///
+
+///
+/// @namespace bsoncxx::stdx
+/// Declares C++17 standard library polyfills.
+///
+
+///
+/// @namespace bsoncxx::string
+/// Declares entities related to handling string types.
+///
+
+///
+/// @namespace bsoncxx::types
+/// Declares entities representing BSON value types.
+///
+
+///
+/// @namespace bsoncxx::types::bson_value
+/// Declares entities representing any BSON value type.
+///
+
+///
+/// @namespace std
+/// The top-level namespace reserved for the C++ standard library.
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/compiler.hpp

@@ -44,3 +44,10 @@ BSONCXX_DISABLE_WARNING(MSVC(5275));
 
 #define BSONCXX_INLINE inline BSONCXX_PRIVATE
 #define BSONCXX_CALL BSONCXX_IF_MSVC(__cdecl)
+
+///
+/// @file
+/// Provides macros for internal use.
+///
+/// @warning For internal use only!
+///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/postlude.hpp

@@ -101,3 +101,15 @@ static_assert(false, "BSONCXX_ENUM must be undef'ed");
 #pragma pop_macro("BSONCXX_IF_GNU_LIKE")
 
 #pragma pop_macro("BSONCXX_FWD")
+
+///
+/// @file
+/// The bsoncxx macro guard postlude header.
+///
+/// @warning For internal use only!
+///
+/// This header uses macro pragmas to guard macros defined by the bsoncxx library for internal use
+/// by "popping" their prior definition onto the stack after use by bsoncxx headers.
+///
+/// @see bsoncxx/v_noabi/bsoncxx/config/prelude.hpp
+///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/prelude.hpp

@@ -120,3 +120,23 @@
 // CXX-2769: out-of-place, but remains for backward compatibility.
 #pragma push_macro("BSONCXX_ENUM")
 #undef BSONCXX_ENUM
+
+///
+/// @file
+/// The bsoncxx macro guard prelude header.
+///
+/// @warning For internal use only!
+///
+/// @par "Includes" @parblock
+/// @li @ref bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
+/// @li @ref bsoncxx-v_noabi-bsoncxx-config-config-hpp
+/// @li @ref bsoncxx-v_noabi-bsoncxx-config-export-hpp
+/// @li @ref bsoncxx/v_noabi/bsoncxx/config/util.hpp
+/// @li @ref bsoncxx-v_noabi-bsoncxx-config-version-hpp
+/// @endparblock
+///
+/// This header uses macro pragmas to guard macros defined by the bsoncxx library for internal use
+/// by "pushing" their prior definition onto the stack before use by bsoncxx headers.
+///
+/// @see bsoncxx/v_noabi/bsoncxx/config/postlude.hpp
+///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/util.hpp

@@ -135,3 +135,9 @@
 
 #define BSONCXX_FWD(...) static_cast<decltype(__VA_ARGS__)&&>(__VA_ARGS__)
 
+///
+/// @file
+/// Provides macros for internal use.
+///
+/// @warning For internal use only!
+///