CXX-2790 Redeclare bsoncxx::v_noabi as a non-inline namespace (#1066)

* Remove reference to ABI namespace in examples

* Refactor bsoncxx::v_noabi as a non-inline namespace

* Add using-declarations to redeclare entities in root namespace

* Update CONTRIBUTING with root namespace qualifier guidelines

Author: eramongodb

CONTRIBUTING.md

@@ -87,6 +87,50 @@ inline namespace v_noabi {
 #include <driver/config/postlude.hpp>
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### Library Root Namespace
+
+The library root namespace declares ABI namespaces (e.g. `mongocxx::v_noabi`, `mongocxx::v1`, etc.), within which symbols are declared according to their compatibility with an ABI version.
+
+The library root namespace also redeclares ABI-specific entities without an ABI namespace qualifier (e.g. `mongocxx::v_noabi::document::view` as `mongocxx::document::view`) to allow users to automatically opt-into the latest supported ABI version of a given entity without requiring changes to source code. The root namespace redeclarations are intended to be the default method for using library entities. A user should only include the ABI namespace in a qualifier if they require compatibility with that specific ABI version.
+
+To avoid being affected by changes to root namespace redeclarations, interfaces declared within an ABI namespace must not be written in terms of a root namespace redeclaration:
+
+```cpp
+namespace mongocxx {
+namespace v_noabi {
+namespace example {
+
+struct type {}; // The type intended to be referenced below.
+
+// Problem: when `mongocxx::example::type` is changed from `v_noabi` to `v1`,
+// this parameter type will also (incorrectly) change from `v_noabi` to `v1`.
+void fn(mongocxx::example::type param);
+
+}  // namespace example
+}  // namespace v_noabi
+}  // namespace mongocxx
+```
+
+References to ABI-specific entities in ABI namespaces must always be (un)qualified such that it is not affected by changes to root namespace redeclarations:
+
+```cpp
+namespace mongocxx {
+namespace v_noabi {
+namespace example {
+
+struct type {}; // The type intended to be referenced below.
+
+// OK: always resolves to `mongocxx::v_noabi::example::type`.
+void fn(type param);
+
+// Also OK: unambiguously refers to the ABI-specific type.
+void fn(mongocxx::v_noabi::example::type param);
+
+}  // namespace example
+}  // namespace v_noabi
+}  // namespace mongocxx
+```
+
 ### Class Declarations
 
 Guidelines:

examples/mongocxx/mongodb.com/documentation_examples.cpp

@@ -1467,7 +1467,7 @@ static void snapshot_example2(mongocxx::client& client) {
     }
 }
 
-static bool version_at_least(mongocxx::v_noabi::database& db, int minimum_major) {
+static bool version_at_least(mongocxx::database& db, int minimum_major) {
     using bsoncxx::builder::basic::kvp;
     using bsoncxx::builder::basic::make_document;
 

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

@@ -17,7 +17,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 class BSONCXX_API element;
@@ -26,4 +26,12 @@ class BSONCXX_API element;
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace array {
+
+using ::bsoncxx::v_noabi::array::element;
+
+}  // namespace array
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -26,7 +26,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 ///
@@ -122,4 +122,13 @@ BSONCXX_API bool BSONCXX_CALL operator!=(const types::bson_value::view& v, const
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace array {
+
+using ::bsoncxx::v_noabi::array::operator==;
+using ::bsoncxx::v_noabi::array::operator!=;
+
+}  // namespace array
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -17,7 +17,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 class BSONCXX_API value;
@@ -26,4 +26,12 @@ class BSONCXX_API value;
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace array {
+
+using ::bsoncxx::v_noabi::array::value;
+
+}  // namespace array
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -25,7 +25,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 ///

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

@@ -17,7 +17,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 class BSONCXX_API view;
@@ -26,4 +26,12 @@ class BSONCXX_API view;
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace array {
+
+using ::bsoncxx::v_noabi::array::view;
+
+}  // namespace array
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -27,7 +27,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
 ///

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

@@ -22,13 +22,21 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace array {
 
-using view_or_value = bsoncxx::view_or_value<array::view, array::value>;
+using view_or_value = ::bsoncxx::v_noabi::view_or_value<view, value>;
 
 }  // namespace array
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace array {
+
+using ::bsoncxx::v_noabi::array::view_or_value;
+
+}  // namespace array
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -15,7 +15,7 @@
 #pragma once
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -25,3 +25,13 @@ class array;
 }  // namespace builder
 }  // namespace v_noabi
 }  // namespace bsoncxx
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+using ::bsoncxx::v_noabi::builder::basic::array;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx

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

@@ -26,7 +26,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -57,7 +57,7 @@ class array : public sub_array {
     ///
     /// @return A view of the BSON array.
     ///
-    BSONCXX_INLINE bsoncxx::array::view view() const {
+    BSONCXX_INLINE bsoncxx::v_noabi::array::view view() const {
         return _core.view_array();
     }
 
@@ -67,7 +67,7 @@ class array : public sub_array {
     ///
     /// @return A view of the current builder contents.
     ///
-    BSONCXX_INLINE operator bsoncxx::array::view() const {
+    BSONCXX_INLINE operator bsoncxx::v_noabi::array::view() const {
         return view();
     }
 
@@ -80,7 +80,7 @@ class array : public sub_array {
     ///  After calling extract() it is illegal to call any methods
     ///  on this class, unless it is subsequenly moved into.
     ///
-    BSONCXX_INLINE bsoncxx::array::value extract() {
+    BSONCXX_INLINE bsoncxx::v_noabi::array::value extract() {
         return _core.extract_array();
     }
 
@@ -103,13 +103,12 @@ class array : public sub_array {
 ///   builder::basic::sub_array::append accepts.
 ///
 /// @return
-///   A bsoncxx::array::value containing the elements.
+///   A bsoncxx::v_noabi::array::value containing the elements.
 ///
 template <typename... Args>
-bsoncxx::array::value BSONCXX_CALL make_array(Args&&... args) {
-    basic::array array;
+bsoncxx::v_noabi::array::value BSONCXX_CALL make_array(Args&&... args) {
+    array array;
     array.append(std::forward<Args>(args)...);
-
     return array.extract();
 }
 
@@ -118,4 +117,14 @@ bsoncxx::array::value BSONCXX_CALL make_array(Args&&... args) {
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+using ::bsoncxx::v_noabi::builder::basic::make_array;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>

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

@@ -15,7 +15,7 @@
 #pragma once
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -25,3 +25,13 @@ class document;
 }  // namespace builder
 }  // namespace v_noabi
 }  // namespace bsoncxx
+
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+using ::bsoncxx::v_noabi::builder::basic::document;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx

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

@@ -27,7 +27,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-inline namespace v_noabi {
+namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -59,7 +59,7 @@ class document : public sub_document {
     ///
     /// @return A view of the BSON document.
     ///
-    BSONCXX_INLINE bsoncxx::document::view view() const {
+    BSONCXX_INLINE bsoncxx::v_noabi::document::view view() const {
         return _core.view_document();
     }
 
@@ -69,7 +69,7 @@ class document : public sub_document {
     ///
     /// @return A view of the current builder contents.
     ///
-    BSONCXX_INLINE operator bsoncxx::document::view() const {
+    BSONCXX_INLINE operator bsoncxx::v_noabi::document::view() const {
         return view();
     }
 
@@ -82,7 +82,7 @@ class document : public sub_document {
     ///  After calling extract() it is illegal to call any methods
     ///  on this class, unless it is subsequently moved into.
     ///
-    BSONCXX_INLINE bsoncxx::document::value extract() {
+    BSONCXX_INLINE bsoncxx::v_noabi::document::value extract() {
         return _core.extract_document();
     }
 
@@ -105,13 +105,12 @@ class document : public sub_document {
 ///   builder::basic::sub_document::append accepts.
 ///
 /// @return
-///   A bsoncxx::document::value containing the elements.
+///   A bsoncxx::v_noabi::document::value containing the elements.
 ///
 template <typename... Args>
-bsoncxx::document::value BSONCXX_CALL make_document(Args&&... args) {
-    basic::document document;
+bsoncxx::v_noabi::document::value BSONCXX_CALL make_document(Args&&... args) {
+    document document;
     document.append(std::forward<Args>(args)...);
-
     return document.extract();
 }
 
@@ -120,4 +119,14 @@ bsoncxx::document::value BSONCXX_CALL make_document(Args&&... args) {
 }  // namespace v_noabi
 }  // namespace bsoncxx
 
+namespace bsoncxx {
+namespace builder {
+namespace basic {
+
+using ::bsoncxx::v_noabi::builder::basic::make_document;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace bsoncxx
+
 #include <bsoncxx/config/postlude.hpp>