CXX-3069 document headers and root namespace redeclarations (mongocxx) (#1184)

* Add missing documentation for mongocxx::stdx

* CXX-3069 document headers and redeclarations (mongocxx)

Author: eramongodb

src/mongocxx/include/mongocxx/fwd.hpp

@@ -76,3 +76,14 @@
 /// @namespace mongocxx::result::gridfs
 /// Declares entities representing the result of GridFS commands.
 ///
+
+///
+/// @namespace mongocxx::stdx
+/// Redeclares @ref bsoncxx C++17 standard library polyfills in the @ref mongocxx library namespace
+/// for internal use.
+///
+/// @deprecated Use @ref bsoncxx::stdx instead.
+///
+/// @warning These redeclarations are for internal use only! Users should reference entities
+/// declared in @ref bsoncxx directly, not through @ref mongocxx.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/bulk_write-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::bulk_write;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::bulk_write.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::bulk_write
+class bulk_write {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/bulk_write.hpp

@@ -117,3 +117,8 @@ class bulk_write {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::bulk_write.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/change_stream-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::change_stream;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::change_stream.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::change_stream
+class change_stream {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/change_stream.hpp

@@ -221,3 +221,8 @@ class change_stream::iterator {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::change_stream.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::client;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::client.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::client
+class client {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client.hpp

@@ -463,3 +463,8 @@ MONGOCXX_INLINE mongocxx::v_noabi::database client::operator[](
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::client.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_encryption-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::client_encryption;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::client_encryption.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::client_encryption
+class client_encryption {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_encryption.hpp

@@ -284,3 +284,8 @@ class client_encryption {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::client_encryption.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_session-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::client_session;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::client_session.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::client_session
+class client_session {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_session.hpp

@@ -219,3 +219,8 @@ class client_session {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::client_session.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/collection-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::collection;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::collection.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::collection
+class collection {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/collection.hpp

@@ -1972,3 +1972,8 @@ MONGOCXX_INLINE stdx::optional<result::insert_many> collection::insert_many(
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::collection.
+///

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

@@ -32,3 +32,10 @@
 #define MONGOCXX_CALL
 
 #endif
+
+///
+/// @file
+/// Provides macros for internal use.
+///
+/// @warning For internal use only!
+///

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

@@ -60,3 +60,15 @@
 // prelude.hpp
 #undef MONGOCXX_UNREACHABLE
 #pragma pop_macro("MONGOCXX_UNREACHABLE")
+
+///
+/// @file
+/// The mongocxx macro guard postlude header.
+///
+/// @warning For internal use only!
+///
+/// This header uses macro pragmas to guard macros defined by the mongocxx library for internal use
+/// by "popping" their prior definition onto the stack after use by mongocxx headers.
+///
+/// @see mongocxx/v_noabi/mongocxx/config/prelude.hpp
+///

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

@@ -63,3 +63,22 @@
 #pragma push_macro("MONGOCXX_UNREACHABLE")
 #undef MONGOCXX_UNREACHABLE
 #define MONGOCXX_UNREACHABLE std::abort()
+
+///
+/// @file
+/// The mongocxx macro guard prelude header.
+///
+/// @warning For internal use only!
+///
+/// @par "Includes" @parblock
+/// @li @ref mongocxx/v_noabi/mongocxx/config/compiler.hpp
+/// @li @ref mongocxx-v_noabi-mongocxx-config-config-hpp
+/// @li @ref mongocxx-v_noabi-mongocxx-config-export-hpp
+/// @li @ref mongocxx-v_noabi-mongocxx-config-version-hpp
+/// @endparblock
+///
+/// This header uses macro pragmas to guard macros defined by the mongocxx library for internal use
+/// by "pushing" their prior definition onto the stack before use by mongocxx headers.
+///
+/// @see mongocxx/v_noabi/mongocxx/config/postlude.hpp
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/cursor-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::cursor;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::cursor.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::cursor
+class cursor {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/cursor.hpp

@@ -185,3 +185,8 @@ class cursor::iterator {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::cursor.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/database-fwd.hpp

@@ -31,3 +31,19 @@ using ::mongocxx::v_noabi::database;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::database.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+
+/// @ref mongocxx::v_noabi::database
+class database {};
+
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/database.hpp

@@ -657,3 +657,8 @@ MONGOCXX_INLINE mongocxx::v_noabi::collection database::operator[](
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::database.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_failed_event-fwd.hpp

@@ -35,3 +35,21 @@ using ::mongocxx::v_noabi::events::command_failed_event;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::events::command_failed_event.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+namespace events {
+
+/// @ref mongocxx::v_noabi::events::command_failed_event
+class command_failed_event {};
+
+}  // namespace events
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_failed_event.hpp

@@ -114,3 +114,8 @@ class command_failed_event {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::events::command_failed_event.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_started_event-fwd.hpp

@@ -35,3 +35,21 @@ using ::mongocxx::v_noabi::events::command_started_event;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::events::command_started_event.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+namespace events {
+
+/// @ref mongocxx::v_noabi::events::command_started_event
+class command_started_event {};
+
+}  // namespace events
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_started_event.hpp

@@ -114,3 +114,8 @@ class command_started_event {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::events::command_started_event.
+///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_succeeded_event-fwd.hpp

@@ -35,3 +35,21 @@ using ::mongocxx::v_noabi::events::command_succeeded_event;
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Declares @ref mongocxx::v_noabi::events::command_succeeded_event.
+///
+
+#if defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace mongocxx {
+namespace events {
+
+/// @ref mongocxx::v_noabi::events::command_succeeded_event
+class command_succeeded_event {};
+
+}  // namespace events
+}  // namespace mongocxx
+
+#endif  // defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/mongocxx/include/mongocxx/v_noabi/mongocxx/events/command_succeeded_event.hpp

@@ -37,7 +37,6 @@ namespace events {
 class command_succeeded_event {
    public:
     MONGOCXX_PRIVATE explicit command_succeeded_event(const void* event);
-
     ///
     /// Destroys a command_succeeded_event.
     ///
@@ -114,3 +113,8 @@ class command_succeeded_event {
 }  // namespace mongocxx
 
 #include <mongocxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref mongocxx::v_noabi::events::command_succeeded_event.
+///