From 3b599accff2885e62e415c1317c3533a94c9938e Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 8 Jan 2025 14:24:09 -0600 Subject: [PATCH 1/4] Move doc.hpp headers into into docs subdirectory --- src/bsoncxx/include/CMakeLists.txt | 3 ++- src/bsoncxx/include/bsoncxx/{doc.hpp => docs/top.hpp} | 0 src/bsoncxx/test/CMakeLists.txt | 2 +- src/mongocxx/include/CMakeLists.txt | 3 ++- src/mongocxx/include/mongocxx/{doc.hpp => docs/top.hpp} | 0 src/mongocxx/test/CMakeLists.txt | 2 +- 6 files changed, 6 insertions(+), 4 deletions(-) rename src/bsoncxx/include/bsoncxx/{doc.hpp => docs/top.hpp} (100%) rename src/mongocxx/include/mongocxx/{doc.hpp => docs/top.hpp} (100%) diff --git a/src/bsoncxx/include/CMakeLists.txt b/src/bsoncxx/include/CMakeLists.txt index 8fd7b2142f..106170a6c9 100644 --- a/src/bsoncxx/include/CMakeLists.txt +++ b/src/bsoncxx/include/CMakeLists.txt @@ -17,7 +17,8 @@ install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/ COMPONENT dev FILES_MATCHING PATTERN "*.hpp" - PATTERN "bsoncxx/doc.hpp" EXCLUDE + PATTERN "bsoncxx/docs/*" EXCLUDE + PATTERN "bsoncxx/docs" EXCLUDE ) file(GLOB_RECURSE bsoncxx_include_headers diff --git a/src/bsoncxx/include/bsoncxx/doc.hpp b/src/bsoncxx/include/bsoncxx/docs/top.hpp similarity index 100% rename from src/bsoncxx/include/bsoncxx/doc.hpp rename to src/bsoncxx/include/bsoncxx/docs/top.hpp diff --git a/src/bsoncxx/test/CMakeLists.txt b/src/bsoncxx/test/CMakeLists.txt index 06794c29de..4bf4586851 100644 --- a/src/bsoncxx/test/CMakeLists.txt +++ b/src/bsoncxx/test/CMakeLists.txt @@ -132,7 +132,7 @@ if(ENABLE_MACRO_GUARD_TESTS) INCLUDE_PATTERNS "include/*.hpp" # Public headers. EXCLUDE_REGEXES - "include/bsoncxx/doc\.hpp" # Doc header. + "include/bsoncxx/docs/.*\.hpp" # Doc header. "include/.*/(prelude|postlude)\.hpp" # Macro guard headers. "include/bsoncxx/v_noabi/bsoncxx/config/.*\.hpp" # v_noabi config headers. "include/bsoncxx/v_noabi/bsoncxx/enums/.*\.hpp" # v_noabi X-macro headers. diff --git a/src/mongocxx/include/CMakeLists.txt b/src/mongocxx/include/CMakeLists.txt index 874757b404..63f501a039 100644 --- a/src/mongocxx/include/CMakeLists.txt +++ b/src/mongocxx/include/CMakeLists.txt @@ -17,7 +17,8 @@ install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/ COMPONENT dev FILES_MATCHING PATTERN "*.hpp" - PATTERN "mongocxx/doc.hpp" EXCLUDE + PATTERN "mongocxx/docs/*" EXCLUDE + PATTERN "mongocxx/docs" EXCLUDE ) file(GLOB_RECURSE mongocxx_include_headers diff --git a/src/mongocxx/include/mongocxx/doc.hpp b/src/mongocxx/include/mongocxx/docs/top.hpp similarity index 100% rename from src/mongocxx/include/mongocxx/doc.hpp rename to src/mongocxx/include/mongocxx/docs/top.hpp diff --git a/src/mongocxx/test/CMakeLists.txt b/src/mongocxx/test/CMakeLists.txt index 33b369af60..92b7d5e37a 100644 --- a/src/mongocxx/test/CMakeLists.txt +++ b/src/mongocxx/test/CMakeLists.txt @@ -318,7 +318,7 @@ if(ENABLE_MACRO_GUARD_TESTS) INCLUDE_PATTERNS "include/*.hpp" # Public headers. EXCLUDE_REGEXES - "include/mongocxx/doc\.hpp" # Doc header. + "include/mongocxx/docs/.*\.hpp" # Doc header. "include/.*/(prelude|postlude)\.hpp" # Macro guard headers. "include/mongocxx/v_noabi/mongocxx/config/.*\.hpp" # v_noabi config headers. ) From 845802b8bbcb166597340e1cfa62d6d16f5b48cc Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 8 Jan 2025 14:24:10 -0600 Subject: [PATCH 2/4] Move v_noabi documentation into docs/v_noabi.hpp --- src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp | 151 ++++++++++++++++++ .../include/bsoncxx/v_noabi/bsoncxx/fwd.hpp | 127 --------------- .../include/mongocxx/docs/v_noabi.hpp | 126 +++++++++++++++ .../include/mongocxx/v_noabi/mongocxx/fwd.hpp | 102 ------------ 4 files changed, 277 insertions(+), 229 deletions(-) create mode 100644 src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp create mode 100644 src/mongocxx/include/mongocxx/docs/v_noabi.hpp diff --git a/src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp b/src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp new file mode 100644 index 0000000000..551092636d --- /dev/null +++ b/src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp @@ -0,0 +1,151 @@ +// Copyright 2009-present MongoDB, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#if !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) +#error "This file is for documentation purposes only. It should not be included." +#endif // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) + +/// +/// @file +/// For documentation purposes only. +/// +/// @note This header is not includable! +/// + +/// +/// @dir bsoncxx/v_noabi +/// The directory relative to which headers declaring entities in @ref bsoncxx::v_noabi are +/// typically included. +/// +/// For backward compatibility, unstable ABI headers may be included using the syntax +/// ``, which is equivalent to ``. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx +/// Provides headers declaring entities in @ref bsoncxx::v_noabi. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/array +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::array. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/builder +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/builder/basic +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder::basic. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/builder/stream +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder::stream. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/config +/// Provides headers related to bsoncxx library configuration. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/document +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::document. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/enums +/// Provides X macro headers over BSON types and binary subtypes. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/exception +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::exception. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/stdx +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::stdx. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/string +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::string. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/types +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::types. +/// + +/// +/// @dir bsoncxx/v_noabi/bsoncxx/types/bson_value +/// Provides headers declaring entities in @ref bsoncxx::v_noabi::types::bson_value. +/// + +/// +/// @namespace bsoncxx::v_noabi +/// Declares entities whose ABI stability is NOT guaranteed. +/// + +/// +/// @namespace bsoncxx::v_noabi::array +/// @copydoc bsoncxx::array +/// + +/// +/// @namespace bsoncxx::v_noabi::builder +/// @copydoc bsoncxx::builder +/// + +/// +/// @namespace bsoncxx::v_noabi::builder::basic +/// @copydoc bsoncxx::builder::basic +/// + +/// +/// @namespace bsoncxx::v_noabi::builder::stream +/// @copydoc bsoncxx::builder::stream +/// + +/// +/// @namespace bsoncxx::v_noabi::document +/// @copydoc bsoncxx::document +/// + +/// +/// @namespace bsoncxx::v_noabi::stdx +/// @copydoc bsoncxx::stdx +/// + +/// +/// @namespace bsoncxx::v_noabi::string +/// @copydoc bsoncxx::string +/// + +/// +/// @namespace bsoncxx::v_noabi::types +/// @copydoc bsoncxx::types +/// +/// @see +/// - @ref bsoncxx::v_noabi::types::bson_value +/// + +/// +/// @namespace bsoncxx::v_noabi::types::bson_value +/// Declares entities representing any BSON value type. +/// diff --git a/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/fwd.hpp b/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/fwd.hpp index 820086c027..03e9a53f6a 100644 --- a/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/fwd.hpp +++ b/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/fwd.hpp @@ -54,130 +54,3 @@ /// @par Includes /// - All header files under `bsoncxx/v_noabi/bsoncxx` whose filename ends with `-fwd.hpp`. /// - -/// -/// @dir bsoncxx/v_noabi -/// The directory relative to which headers declaring entities in @ref bsoncxx::v_noabi are -/// typically included. -/// -/// For backward compatibility, unstable ABI headers may be included using the syntax -/// ``, which is equivalent to ``. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx -/// Provides headers declaring entities in @ref bsoncxx::v_noabi. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/array -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::array. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/builder -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/builder/basic -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder::basic. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/builder/stream -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::builder::stream. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/config -/// Provides headers related to bsoncxx library configuration. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/document -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::document. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/enums -/// Provides X macro headers over BSON types and binary subtypes. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/exception -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::exception. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/stdx -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::stdx. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/string -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::string. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/types -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::types. -/// - -/// -/// @dir bsoncxx/v_noabi/bsoncxx/types/bson_value -/// Provides headers declaring entities in @ref bsoncxx::v_noabi::types::bson_value. -/// - -/// -/// @namespace bsoncxx::v_noabi -/// Declares entities whose ABI stability is NOT guaranteed. -/// - -/// -/// @namespace bsoncxx::v_noabi::array -/// @copydoc bsoncxx::array -/// - -/// -/// @namespace bsoncxx::v_noabi::builder -/// @copydoc bsoncxx::builder -/// - -/// -/// @namespace bsoncxx::v_noabi::builder::basic -/// @copydoc bsoncxx::builder::basic -/// - -/// -/// @namespace bsoncxx::v_noabi::builder::stream -/// @copydoc bsoncxx::builder::stream -/// - -/// -/// @namespace bsoncxx::v_noabi::document -/// @copydoc bsoncxx::document -/// - -/// -/// @namespace bsoncxx::v_noabi::stdx -/// @copydoc bsoncxx::stdx -/// - -/// -/// @namespace bsoncxx::v_noabi::string -/// @copydoc bsoncxx::string -/// - -/// -/// @namespace bsoncxx::v_noabi::types -/// @copydoc bsoncxx::types -/// -/// @see -/// - @ref bsoncxx::v_noabi::types::bson_value -/// - -/// -/// @namespace bsoncxx::v_noabi::types::bson_value -/// Declares entities representing any BSON value type. -/// diff --git a/src/mongocxx/include/mongocxx/docs/v_noabi.hpp b/src/mongocxx/include/mongocxx/docs/v_noabi.hpp new file mode 100644 index 0000000000..dfb9d56d97 --- /dev/null +++ b/src/mongocxx/include/mongocxx/docs/v_noabi.hpp @@ -0,0 +1,126 @@ +// Copyright 2009-present MongoDB, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#if !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) +#error "This file is for documentation purposes only. It should not be included." +#endif // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) + +/// +/// @file +/// For documentation purposes only. +/// +/// @note This header is not includable! +/// + +/// +/// @dir mongocxx/v_noabi +/// The directory relative to which headers declaring entities in @ref mongocxx::v_noabi +/// are typically included. +/// +/// For backward compatibility, unstable ABI headers may be included using the syntax +/// ``, which is equivalent to ``. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx +/// Provides headers declaring entities in @ref mongocxx::v_noabi. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/config +/// Provides headers related to mongocxx library configuration. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/events +/// Provides headers declaring entities in @ref mongocxx::v_noabi::events. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/exception +/// Provides headers declaring entities in @ref mongocxx::v_noabi::exception. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/gridfs +/// Provides headers declaring entities in @ref mongocxx::v_noabi::gridfs. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/model +/// Provides headers declaring entities in @ref mongocxx::v_noabi::model. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/options +/// Provides headers declaring entities in @ref mongocxx::v_noabi::options. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/options/gridfs +/// Provides headers declaring entities in @ref mongocxx::v_noabi::options::gridfs. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/result +/// Provides headers declaring entities in @ref mongocxx::v_noabi::result. +/// + +/// +/// @dir mongocxx/v_noabi/mongocxx/result/gridfs +/// Provides headers declaring entities in @ref mongocxx::v_noabi::result::gridfs. +/// + +/// +/// @namespace mongocxx::v_noabi +/// Declares entities whose ABI stability is NOT guaranteed. +/// + +/// +/// @namespace mongocxx::v_noabi::events +/// @copydoc mongocxx::events +/// + +/// +/// @namespace mongocxx::v_noabi::gridfs +/// @copydoc mongocxx::gridfs +/// + +/// +/// @namespace mongocxx::v_noabi::model +/// @copydoc mongocxx::model +/// +/// @see +/// - @ref mongocxx::v_noabi::bulk_write +/// + +/// +/// @namespace mongocxx::v_noabi::options +/// @copydoc mongocxx::options +/// + +/// +/// @namespace mongocxx::v_noabi::options::gridfs +/// @copydoc mongocxx::options::gridfs +/// + +/// +/// @namespace mongocxx::v_noabi::result +/// @copydoc mongocxx::result +/// + +/// +/// @namespace mongocxx::v_noabi::result::gridfs +/// @copydoc mongocxx::result::gridfs +/// diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/fwd.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/fwd.hpp index 60eb706e4d..4a48e4e43c 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/fwd.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/fwd.hpp @@ -119,105 +119,3 @@ /// @par Includes /// - All header files under `mongocxx/v_noabi/mongocxx` whose filename ends with `-fwd.hpp`. /// - -/// -/// @dir mongocxx/v_noabi -/// The directory relative to which headers declaring entities in @ref mongocxx::v_noabi -/// are typically included. -/// -/// For backward compatibility, unstable ABI headers may be included using the syntax -/// ``, which is equivalent to ``. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx -/// Provides headers declaring entities in @ref mongocxx::v_noabi. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/config -/// Provides headers related to mongocxx library configuration. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/events -/// Provides headers declaring entities in @ref mongocxx::v_noabi::events. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/exception -/// Provides headers declaring entities in @ref mongocxx::v_noabi::exception. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/gridfs -/// Provides headers declaring entities in @ref mongocxx::v_noabi::gridfs. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/model -/// Provides headers declaring entities in @ref mongocxx::v_noabi::model. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/options -/// Provides headers declaring entities in @ref mongocxx::v_noabi::options. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/options/gridfs -/// Provides headers declaring entities in @ref mongocxx::v_noabi::options::gridfs. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/result -/// Provides headers declaring entities in @ref mongocxx::v_noabi::result. -/// - -/// -/// @dir mongocxx/v_noabi/mongocxx/result/gridfs -/// Provides headers declaring entities in @ref mongocxx::v_noabi::result::gridfs. -/// - -/// -/// @namespace mongocxx::v_noabi -/// Declares entities whose ABI stability is NOT guaranteed. -/// - -/// -/// @namespace mongocxx::v_noabi::events -/// @copydoc mongocxx::events -/// - -/// -/// @namespace mongocxx::v_noabi::gridfs -/// @copydoc mongocxx::gridfs -/// - -/// -/// @namespace mongocxx::v_noabi::model -/// @copydoc mongocxx::model -/// -/// @see -/// - @ref mongocxx::v_noabi::bulk_write -/// - -/// -/// @namespace mongocxx::v_noabi::options -/// @copydoc mongocxx::options -/// - -/// -/// @namespace mongocxx::v_noabi::options::gridfs -/// @copydoc mongocxx::options::gridfs -/// - -/// -/// @namespace mongocxx::v_noabi::result -/// @copydoc mongocxx::result -/// - -/// -/// @namespace mongocxx::v_noabi::result::gridfs -/// @copydoc mongocxx::result::gridfs -/// From b72eb2eee8993cb198a0cbea4a5ca4a34b57c356 Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 8 Jan 2025 14:24:10 -0600 Subject: [PATCH 3/4] Add documentation for docs subdirectories --- src/bsoncxx/include/bsoncxx/docs/top.hpp | 5 +++++ src/mongocxx/include/mongocxx/docs/top.hpp | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/src/bsoncxx/include/bsoncxx/docs/top.hpp b/src/bsoncxx/include/bsoncxx/docs/top.hpp index 42b46dac9a..cb135bba13 100644 --- a/src/bsoncxx/include/bsoncxx/docs/top.hpp +++ b/src/bsoncxx/include/bsoncxx/docs/top.hpp @@ -28,6 +28,11 @@ /// Provides headers declaring entities in @ref bsoncxx /// +/// +/// @dir include/bsoncxx/docs +/// For documentation purposes only. +/// + /// /// @namespace bsoncxx /// The top-level namespace within which all bsoncxx library entities are declared. diff --git a/src/mongocxx/include/mongocxx/docs/top.hpp b/src/mongocxx/include/mongocxx/docs/top.hpp index 1af6dac8be..7bd1ffa879 100644 --- a/src/mongocxx/include/mongocxx/docs/top.hpp +++ b/src/mongocxx/include/mongocxx/docs/top.hpp @@ -28,6 +28,11 @@ /// Provides headers declaring entities in @ref mongocxx /// +/// +/// @dir include/mongocxx/docs +/// For documentation purposes only. +/// + /// /// @namespace mongocxx /// The top-level namespace within which all mongocxx library entities are declared. From fa09681f12174e360ea8145c93c9fb835ec6e911 Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 8 Jan 2025 14:24:10 -0600 Subject: [PATCH 4/4] Move topic page documentation into topics.hpp --- src/bsoncxx/include/bsoncxx/docs/top.hpp | 69 ----------- src/bsoncxx/include/bsoncxx/docs/topics.hpp | 93 ++++++++++++++ src/mongocxx/include/mongocxx/docs/top.hpp | 91 -------------- src/mongocxx/include/mongocxx/docs/topics.hpp | 115 ++++++++++++++++++ 4 files changed, 208 insertions(+), 160 deletions(-) create mode 100644 src/bsoncxx/include/bsoncxx/docs/topics.hpp create mode 100644 src/mongocxx/include/mongocxx/docs/topics.hpp diff --git a/src/bsoncxx/include/bsoncxx/docs/top.hpp b/src/bsoncxx/include/bsoncxx/docs/top.hpp index cb135bba13..3d4530d9fe 100644 --- a/src/bsoncxx/include/bsoncxx/docs/top.hpp +++ b/src/bsoncxx/include/bsoncxx/docs/top.hpp @@ -88,72 +88,3 @@ /// @namespace bsoncxx::types::bson_value /// Declares entities representing any BSON value type. /// - -/// -/// @page topic-bsoncxx The bsoncxx Library -/// @brief Topics relating to the bsoncxx library. -/// @li @subpage topic-bsoncxx-examples -/// @li @subpage topic-bsoncxx-about -/// - -/// -/// @page topic-bsoncxx-examples How-To Guides -/// @brief Examples of how to use the bsoncxx library. -/// @li @subpage topic-bsoncxx-examples-bson-documents -/// @li @subpage topic-bsoncxx-examples-bson-errors -/// @li @subpage topic-bsoncxx-examples-decimal128 -/// @li @subpage topic-bsoncxx-examples-oid -/// @li @subpage topic-bsoncxx-examples-validation -/// - -/// -/// @page topic-bsoncxx-examples-bson-documents BSON Documents -/// @brief How to create and use BSON documents. -/// @tableofcontents -/// @include{doc} api/bsoncxx/examples/bson_documents/create_doc.md -/// @include{doc} api/bsoncxx/examples/bson_documents/create_array.md -/// @include{doc} api/bsoncxx/examples/bson_documents/access_doc.md -/// @include{doc} api/bsoncxx/examples/bson_documents/access_array.md -/// @include{doc} api/bsoncxx/examples/bson_documents/elements.md -/// @include{doc} api/bsoncxx/examples/bson_documents/values.md -/// @include{doc} api/bsoncxx/examples/bson_documents/json.md -/// - -/// -/// @page topic-bsoncxx-examples-bson-errors BSON Error Handling -/// @brief How to handle BSON document failures, errors, and exceptions. -/// @tableofcontents -/// @include{doc} api/bsoncxx/examples/bson_errors.md -/// - -/// -/// @page topic-bsoncxx-examples-decimal128 Decimal128 -/// @brief How to use Decimal128 interfaces. -/// @tableofcontents -/// @see @parblock -/// @li [BSON Decimal128 Type Handling in Drivers (MongoDB -/// Specifications)](https://specifications.readthedocs.io/en/latest/bson-decimal128/decimal128/) -/// @li [Conversions (General Decimal Arithmetic -/// Specification)](https://speleotrove.com/decimal/daconvs.html) -/// @endparblock -/// @include{doc} api/bsoncxx/examples/decimal128.md -/// - -/// -/// @page topic-bsoncxx-examples-oid ObjectID -/// @brief How to use ObjectID (OID) interfaces. -/// @tableofcontents -/// @include{doc} api/bsoncxx/examples/oid.md -/// - -/// -/// @page topic-bsoncxx-examples-validation Validation -/// @brief How to use BSON document validation interfaces. -/// @tableofcontents -/// @include{doc} api/bsoncxx/examples/validation.md -/// - -/// -/// @page topic-bsoncxx-about Explanation -/// @brief Design decisions, history, and other technical details about the bsoncxx library. -/// diff --git a/src/bsoncxx/include/bsoncxx/docs/topics.hpp b/src/bsoncxx/include/bsoncxx/docs/topics.hpp new file mode 100644 index 0000000000..fc0acc7d58 --- /dev/null +++ b/src/bsoncxx/include/bsoncxx/docs/topics.hpp @@ -0,0 +1,93 @@ +// Copyright 2009-present MongoDB, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#if !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) +#error "This file is for documentation purposes only. It should not be included." +#endif // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) + +/// +/// @file +/// For documentation purposes only. +/// +/// @note This header is not includable! +/// + +/// +/// @page topic-bsoncxx The bsoncxx Library +/// @brief Topics relating to the bsoncxx library. +/// @li @subpage topic-bsoncxx-examples +/// @li @subpage topic-bsoncxx-about +/// + +/// +/// @page topic-bsoncxx-examples How-To Guides +/// @brief Examples of how to use the bsoncxx library. +/// @li @subpage topic-bsoncxx-examples-bson-documents +/// @li @subpage topic-bsoncxx-examples-bson-errors +/// @li @subpage topic-bsoncxx-examples-decimal128 +/// @li @subpage topic-bsoncxx-examples-oid +/// @li @subpage topic-bsoncxx-examples-validation +/// + +/// +/// @page topic-bsoncxx-examples-bson-documents BSON Documents +/// @brief How to create and use BSON documents. +/// @tableofcontents +/// @include{doc} api/bsoncxx/examples/bson_documents/create_doc.md +/// @include{doc} api/bsoncxx/examples/bson_documents/create_array.md +/// @include{doc} api/bsoncxx/examples/bson_documents/access_doc.md +/// @include{doc} api/bsoncxx/examples/bson_documents/access_array.md +/// @include{doc} api/bsoncxx/examples/bson_documents/elements.md +/// @include{doc} api/bsoncxx/examples/bson_documents/values.md +/// @include{doc} api/bsoncxx/examples/bson_documents/json.md +/// + +/// +/// @page topic-bsoncxx-examples-bson-errors BSON Error Handling +/// @brief How to handle BSON document failures, errors, and exceptions. +/// @tableofcontents +/// @include{doc} api/bsoncxx/examples/bson_errors.md +/// + +/// +/// @page topic-bsoncxx-examples-decimal128 Decimal128 +/// @brief How to use Decimal128 interfaces. +/// @tableofcontents +/// @see @parblock +/// @li [BSON Decimal128 Type Handling in Drivers (MongoDB +/// Specifications)](https://specifications.readthedocs.io/en/latest/bson-decimal128/decimal128/) +/// @li [Conversions (General Decimal Arithmetic +/// Specification)](https://speleotrove.com/decimal/daconvs.html) +/// @endparblock +/// @include{doc} api/bsoncxx/examples/decimal128.md +/// + +/// +/// @page topic-bsoncxx-examples-oid ObjectID +/// @brief How to use ObjectID (OID) interfaces. +/// @tableofcontents +/// @include{doc} api/bsoncxx/examples/oid.md +/// + +/// +/// @page topic-bsoncxx-examples-validation Validation +/// @brief How to use BSON document validation interfaces. +/// @tableofcontents +/// @include{doc} api/bsoncxx/examples/validation.md +/// + +/// +/// @page topic-bsoncxx-about Explanation +/// @brief Design decisions, history, and other technical details about the bsoncxx library. +/// diff --git a/src/mongocxx/include/mongocxx/docs/top.hpp b/src/mongocxx/include/mongocxx/docs/top.hpp index 7bd1ffa879..9583329468 100644 --- a/src/mongocxx/include/mongocxx/docs/top.hpp +++ b/src/mongocxx/include/mongocxx/docs/top.hpp @@ -78,94 +78,3 @@ /// @namespace mongocxx::result::gridfs /// Declares entities representing the result of GridFS commands. /// - -/// -/// @page topic-mongocxx The mongocxx Library -/// @brief Topics relating to the mongocxx library. -/// @li @subpage topic-mongocxx-examples -/// @li @subpage topic-mongocxx-about -/// - -/// -/// @page topic-mongocxx-examples How-To Guides -/// @brief Examples of how to use the mongocxx library. -/// @li @subpage topic-mongocxx-examples-instance -/// @li @subpage topic-mongocxx-examples-logger -/// @li @subpage topic-mongocxx-examples-uri -/// @li @subpage topic-mongocxx-examples-clients -/// @li @subpage topic-mongocxx-examples-databases -/// @li @subpage topic-mongocxx-examples-collections -/// @li @subpage topic-mongocxx-examples-client-sessions -/// @li @subpage topic-mongocxx-examples-change-streams -/// @li @subpage topic-mongocxx-examples-operation-exceptions -/// - -/// -/// @page topic-mongocxx-examples-instance Instance -/// @brief How to use a MongoDB C++ Driver instance. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/instance.md -/// - -/// -/// @page topic-mongocxx-examples-logger Logger -/// @brief How to use a custom logger with a MongoDB C++ Driver instance. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/logger.md -/// - -/// -/// @page topic-mongocxx-examples-uri URI -/// @brief How to create and use URIs. -/// @tableofcontents -/// @see -/// - [Connection Strings (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/connection-string/) -/// @include{doc} api/mongocxx/examples/uri.md -/// - -/// -/// @page topic-mongocxx-examples-clients Clients -/// @brief How to use clients and client pools. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/clients.md -/// - -/// -/// @page topic-mongocxx-examples-client-sessions Client Sessions -/// @brief How to create and use client sessions. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/client_sessions.md -/// - -/// -/// @page topic-mongocxx-examples-databases Databases -/// @brief How to obtain and use databases. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/databases.md -/// - -/// -/// @page topic-mongocxx-examples-collections Collections -/// @brief How to obtain and use collections. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/collections.md -/// - -/// -/// @page topic-mongocxx-examples-change-streams Change Streams -/// @brief How to obtain and use change streams. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/change_streams.md -/// - -/// -/// @page topic-mongocxx-examples-operation-exceptions Operation Exceptions -/// @brief How to handle exceptions thrown by database and collection operations. -/// @tableofcontents -/// @include{doc} api/mongocxx/examples/operation_exceptions.md -/// - -/// -/// @page topic-mongocxx-about Explanation -/// @brief Design decisions, history, and other technical details about the mongocxx library. -/// diff --git a/src/mongocxx/include/mongocxx/docs/topics.hpp b/src/mongocxx/include/mongocxx/docs/topics.hpp new file mode 100644 index 0000000000..468abcb8d7 --- /dev/null +++ b/src/mongocxx/include/mongocxx/docs/topics.hpp @@ -0,0 +1,115 @@ +// Copyright 2009-present MongoDB, Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +#if !defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR) +#error "This file is for documentation purposes only. It should not be included." +#endif // !defined(MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR) + +/// +/// @file +/// For documentation purposes only. +/// +/// @note This header is not includable! +/// + +/// +/// @page topic-mongocxx The mongocxx Library +/// @brief Topics relating to the mongocxx library. +/// @li @subpage topic-mongocxx-examples +/// @li @subpage topic-mongocxx-about +/// + +/// +/// @page topic-mongocxx-examples How-To Guides +/// @brief Examples of how to use the mongocxx library. +/// @li @subpage topic-mongocxx-examples-instance +/// @li @subpage topic-mongocxx-examples-logger +/// @li @subpage topic-mongocxx-examples-uri +/// @li @subpage topic-mongocxx-examples-clients +/// @li @subpage topic-mongocxx-examples-databases +/// @li @subpage topic-mongocxx-examples-collections +/// @li @subpage topic-mongocxx-examples-client-sessions +/// @li @subpage topic-mongocxx-examples-change-streams +/// @li @subpage topic-mongocxx-examples-operation-exceptions +/// + +/// +/// @page topic-mongocxx-examples-instance Instance +/// @brief How to use a MongoDB C++ Driver instance. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/instance.md +/// + +/// +/// @page topic-mongocxx-examples-logger Logger +/// @brief How to use a custom logger with a MongoDB C++ Driver instance. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/logger.md +/// + +/// +/// @page topic-mongocxx-examples-uri URI +/// @brief How to create and use URIs. +/// @tableofcontents +/// @see +/// - [Connection Strings (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/connection-string/) +/// @include{doc} api/mongocxx/examples/uri.md +/// + +/// +/// @page topic-mongocxx-examples-clients Clients +/// @brief How to use clients and client pools. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/clients.md +/// + +/// +/// @page topic-mongocxx-examples-client-sessions Client Sessions +/// @brief How to create and use client sessions. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/client_sessions.md +/// + +/// +/// @page topic-mongocxx-examples-databases Databases +/// @brief How to obtain and use databases. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/databases.md +/// + +/// +/// @page topic-mongocxx-examples-collections Collections +/// @brief How to obtain and use collections. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/collections.md +/// + +/// +/// @page topic-mongocxx-examples-change-streams Change Streams +/// @brief How to obtain and use change streams. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/change_streams.md +/// + +/// +/// @page topic-mongocxx-examples-operation-exceptions Operation Exceptions +/// @brief How to handle exceptions thrown by database and collection operations. +/// @tableofcontents +/// @include{doc} api/mongocxx/examples/operation_exceptions.md +/// + +/// +/// @page topic-mongocxx-about Explanation +/// @brief Design decisions, history, and other technical details about the mongocxx library. +///