CXX-3069 document headers and root namespace redeclarations (bsoncxx) (#1182)

* Address -Wzero-as-null-pointer-constant warnings

* Address -Wundef warnings

* Restrict Doxygen examples to examples/

* Fix Doxygen docs and parsing in stdx and config headers

* Partially fix docs for bsoncxx::v_noabi::error_code

* CXX-3069 document headers and redeclarations (bsoncxx)

* Update examples to avoid using stdx::make_unique

* Address -Wmissing-include-dirs warnings for examples

Author: eramongodb

Doxyfile

@@ -901,8 +901,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/stdx/operators.hpp \
-                         src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/stdx/type_traits.hpp
+EXCLUDE                =
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -938,7 +937,7 @@ EXCLUDE_SYMBOLS        = bsoncxx::detail \
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = .
+EXAMPLE_PATH           = examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

examples/bsoncxx/CMakeLists.txt

@@ -12,10 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-include_directories(
-    ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v_noabi
-)
-
 set(BSONCXX_EXAMPLES
     builder_core.cpp
     builder_list.cpp

examples/mongocxx/CMakeLists.txt

@@ -12,11 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-include_directories(
-    ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/bsoncxx/v_noabi
-    ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}/mongocxx/v_noabi
-)
-
 set(MONGOCXX_EXAMPLES
     aggregate.cpp
     automatic_client_side_field_level_encryption.cpp

examples/mongocxx/connect.cpp

@@ -19,7 +19,6 @@
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/builder/basic/kvp.hpp>
 #include <bsoncxx/json.hpp>
-#include <bsoncxx/stdx/make_unique.hpp>
 #include <mongocxx/client.hpp>
 #include <mongocxx/instance.hpp>
 #include <mongocxx/logger.hpp>
@@ -44,6 +43,11 @@ class logger final : public mongocxx::logger {
     std::ostream* const _stream;
 };
 
+// Use `std::make_unique` with C++14 and newer.
+std::unique_ptr<logger> make_logger() {
+    return std::unique_ptr<logger>(new logger(&std::cout));
+}
+
 }  // namespace
 
 int main(int argc, char* argv[]) {
@@ -53,7 +57,7 @@ int main(int argc, char* argv[]) {
     // The mongocxx::instance constructor and destructor initialize and shut down the driver,
     // respectively. Therefore, a mongocxx::instance must be created before using the driver and
     // must remain alive for as long as the driver is in use.
-    mongocxx::instance inst{bsoncxx::stdx::make_unique<logger>(&std::cout)};
+    mongocxx::instance inst{make_logger()};
 
     try {
         const auto uri = mongocxx::uri{(argc >= 2) ? argv[1] : mongocxx::uri::k_default_uri};

examples/mongocxx/gridfs.cpp

@@ -17,16 +17,13 @@
 #include <ostream>
 
 #include <bsoncxx/json.hpp>
-#include <bsoncxx/stdx/make_unique.hpp>
 #include <mongocxx/client.hpp>
 #include <mongocxx/gridfs/bucket.hpp>
 #include <mongocxx/instance.hpp>
 #include <mongocxx/uri.hpp>
 
 using namespace mongocxx;
 
-using bsoncxx::stdx::make_unique;
-
 int main() {
     // The mongocxx::instance constructor and destructor initialize and shut down the driver,
     // respectively. Therefore, a mongocxx::instance must be created before using the driver and
@@ -61,7 +58,9 @@ int main() {
     auto bytes_counter = 0;
 
     auto buffer_size = std::min(file_length, static_cast<std::int64_t>(downloader.chunk_size()));
-    auto buffer = make_unique<std::uint8_t[]>(static_cast<std::size_t>(buffer_size));
+
+    // Use `std::make_unique` with C++14 and newer.
+    auto buffer = std::unique_ptr<std::uint8_t[]>(new std::uint8_t[buffer_size]);
 
     while (auto length_read =
                downloader.read(buffer.get(), static_cast<std::size_t>(buffer_size))) {

examples/mongocxx/index.cpp

@@ -14,7 +14,6 @@
 
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/builder/basic/kvp.hpp>
-#include <bsoncxx/stdx/make_unique.hpp>
 #include <mongocxx/client.hpp>
 #include <mongocxx/instance.hpp>
 #include <mongocxx/uri.hpp>
@@ -58,8 +57,11 @@ int main(int, char**) {
     {
         db["restaurants"].drop();
         mongocxx::options::index index_options{};
-        std::unique_ptr<mongocxx::options::index::wiredtiger_storage_options> wt_options =
-            bsoncxx::stdx::make_unique<mongocxx::options::index::wiredtiger_storage_options>();
+
+        // Use `std::make_unique` with C++14 and newer.
+        std::unique_ptr<mongocxx::options::index::wiredtiger_storage_options> wt_options{
+            new mongocxx::options::index::wiredtiger_storage_options()};
+
         wt_options->config_string("block_allocation=first");
         index_options.storage_options(std::move(wt_options));
         db["restaurants"].create_index(make_document(kvp("cuisine", 1)), index_options);

examples/mongocxx/instance_management.cpp

@@ -14,8 +14,8 @@
 
 #include <cstdlib>
 #include <memory>
+#include <type_traits>
 
-#include <bsoncxx/stdx/make_unique.hpp>
 #include <bsoncxx/stdx/optional.hpp>
 #include <bsoncxx/stdx/string_view.hpp>
 #include <mongocxx/instance.hpp>
@@ -80,11 +80,14 @@ void configure(mongocxx::uri uri) {
                                 bsoncxx::stdx::string_view) noexcept {}
     };
 
-    auto instance =
-        bsoncxx::stdx::make_unique<mongocxx::instance>(bsoncxx::stdx::make_unique<noop_logger>());
+    // Use `std::make_unique` with C++14 and newer.
+    auto instance = std::unique_ptr<mongocxx::instance>(
+        new mongocxx::instance(std::unique_ptr<noop_logger>(new noop_logger())));
 
-    mongo_access::instance().configure(std::move(instance),
-                                       bsoncxx::stdx::make_unique<mongocxx::pool>(std::move(uri)));
+    // Use `std::make_unique` with C++14 and newer.
+    auto pool = std::unique_ptr<mongocxx::pool>(new mongocxx::pool(std::move(uri)));
+
+    mongo_access::instance().configure(std::move(instance), std::move(pool));
 }
 
 bool do_work() {

examples/mongocxx/view_or_value_variant.cpp

@@ -15,7 +15,6 @@
 #include <bsoncxx/builder/basic/array.hpp>
 #include <bsoncxx/builder/basic/document.hpp>
 #include <bsoncxx/builder/basic/kvp.hpp>
-#include <bsoncxx/stdx/make_unique.hpp>
 #include <mongocxx/client.hpp>
 #include <mongocxx/instance.hpp>
 #include <mongocxx/stdx.hpp>

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element-fwd.hpp

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

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element.hpp

@@ -124,3 +124,30 @@ using ::bsoncxx::v_noabi::array::operator!=;
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::array::element.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace array {
+
+/// @ref bsoncxx::v_noabi::array::operator==(const v_noabi::array::element& elem, const v_noabi::types::bson_value::view& v)
+bool operator==(const v_noabi::array::element& elem, const v_noabi::types::bson_value::view& v);
+
+/// @ref bsoncxx::v_noabi::array::operator==(const v_noabi::types::bson_value::view& v, const v_noabi::array::element& elem)
+bool operator==(const v_noabi::types::bson_value::view& v, const v_noabi::array::element& elem);
+
+/// @ref bsoncxx::v_noabi::array::operator!=(const v_noabi::array::element& elem, const v_noabi::types::bson_value::view& v)
+bool operator!=(const v_noabi::array::element& elem, const v_noabi::types::bson_value::view& v);
+
+/// @ref bsoncxx::v_noabi::array::operator!=(const v_noabi::types::bson_value::view& v, const v_noabi::array::element& elem)
+bool operator!=(const v_noabi::types::bson_value::view& v, const v_noabi::array::element& elem);
+
+}  // namespace array
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/value-fwd.hpp

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

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/value.hpp

@@ -120,3 +120,8 @@ BSONCXX_INLINE value::operator array::view() const noexcept {
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::array::value.
+///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view-fwd.hpp

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

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view.hpp

@@ -190,3 +190,8 @@ class view::const_iterator {
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::array::view.
+///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view_or_value.hpp

@@ -43,3 +43,21 @@ using ::bsoncxx::v_noabi::array::view_or_value;
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::array::view_or_value.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace array {
+
+/// @ref bsoncxx::v_noabi::array::view_or_value
+class view_or_value {};
+
+}  // namespace array
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/array-fwd.hpp

@@ -35,3 +35,23 @@ using ::bsoncxx::v_noabi::builder::basic::array;
 }  // namespace basic
 }  // namespace builder
 }  // namespace bsoncxx
+
+///
+/// @file
+/// Declares @ref bsoncxx::v_noabi::builder::basic::array.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+/// @ref bsoncxx::v_noabi::builder::basic::array
+class array {};
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/array.hpp

@@ -136,3 +136,24 @@ using ::bsoncxx::v_noabi::builder::basic::make_array;
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::builder::basic::array.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+/// @ref bsoncxx::v_noabi::builder::basic::make_array
+template <typename... Args>
+v_noabi::array::value make_array(Args&&... args);
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/document-fwd.hpp

@@ -35,3 +35,23 @@ using ::bsoncxx::v_noabi::builder::basic::document;
 }  // namespace basic
 }  // namespace builder
 }  // namespace bsoncxx
+
+///
+/// @file
+/// Declares @ref bsoncxx::v_noabi::builder::basic::document.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+/// @ref bsoncxx::v_noabi::builder::basic::document
+class document {};
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/document.hpp

@@ -135,3 +135,24 @@ using ::bsoncxx::v_noabi::builder::basic::make_document;
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>
+
+///
+/// @file
+/// Provides @ref bsoncxx::v_noabi::builder::basic::document.
+///
+
+#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+/// @ref bsoncxx::v_noabi::builder::basic::make_document
+template <typename... Args>
+v_noabi::document::value make_document(Args&&... args);
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
+#endif  // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)