CXX-2288 Add forward headers for bsoncxx and mongocxx (#1061)

* Add forward headers to clang-format rules

* Add forward headers for bsoncxx and mongocxx

* Make using namespace declaration in list.hpp VERY noticable

* Ensure headers provide the definitive declaration for all entities (no rogue forward declarations).

* Use simple-type-specifier form for friend class declarations

Author: eramongodb

.clang-format

@@ -9,12 +9,14 @@ Cpp11BracedListStyle: true
 DerivePointerAlignment: false
 IncludeBlocks: Regroup
 IncludeCategories:
-  - Regex:    'prelude\.(hpp|hh)' # preludes
-    Priority: 3
-  - Regex:    '<[[:alnum:]_.]+>' # system headers
+  - Regex: 'prelude\.(hpp|hh)' # preludes
+    Priority: 4
+  - Regex: '<[[:alnum:]_.]+>' # system headers
     Priority: 1
-  - Regex:    '.*' # driver headers
+  - Regex: '.*(-|\/)fwd\.(hpp|hh)' # forwarding headers
     Priority: 2
+  - Regex: '.*' # driver headers
+    Priority: 3
 IndentWidth: 4
 MaxEmptyLinesToKeep: 1
 NamespaceIndentation: None

src/bsoncxx/include/CMakeLists.txt

@@ -20,55 +20,87 @@ install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/
 
 set_dist_list(src_bsoncxx_include_DIST
     CMakeLists.txt
+    bsoncxx/v_noabi/bsoncxx/array/element-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/array/element.hpp
+    bsoncxx/v_noabi/bsoncxx/array/value-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/array/value.hpp
     bsoncxx/v_noabi/bsoncxx/array/view_or_value.hpp
+    bsoncxx/v_noabi/bsoncxx/array/view-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/array/view.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/basic/array-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/array.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/basic/document-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/document.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/helpers.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/impl.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/kvp.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/basic/sub_array-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/sub_array.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/basic/sub_document-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/basic/sub_document.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/concatenate-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/core-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/core.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/list-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/list.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/array_context-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/array_context.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/array-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/array.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/closed_context-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/closed_context.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/document-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/document.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/helpers-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/helpers.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/key_context-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/key_context.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/single_context-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/single_context.hpp
+    bsoncxx/v_noabi/bsoncxx/builder/stream/value_context-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/builder/stream/value_context.hpp
     bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
     bsoncxx/v_noabi/bsoncxx/config/postlude.hpp
     bsoncxx/v_noabi/bsoncxx/config/prelude.hpp
+    bsoncxx/v_noabi/bsoncxx/decimal128-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/decimal128.hpp
+    bsoncxx/v_noabi/bsoncxx/document/element-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/document/element.hpp
+    bsoncxx/v_noabi/bsoncxx/document/value-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/document/value.hpp
     bsoncxx/v_noabi/bsoncxx/document/view_or_value.hpp
+    bsoncxx/v_noabi/bsoncxx/document/view-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/document/view.hpp
     bsoncxx/v_noabi/bsoncxx/enums/binary_sub_type.hpp
     bsoncxx/v_noabi/bsoncxx/enums/type.hpp
+    bsoncxx/v_noabi/bsoncxx/exception/error_code-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/exception/error_code.hpp
+    bsoncxx/v_noabi/bsoncxx/exception/exception-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/exception/exception.hpp
+    bsoncxx/v_noabi/bsoncxx/json-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/json.hpp
+    bsoncxx/v_noabi/bsoncxx/oid-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/oid.hpp
     bsoncxx/v_noabi/bsoncxx/stdx/make_unique.hpp
     bsoncxx/v_noabi/bsoncxx/stdx/optional.hpp
     bsoncxx/v_noabi/bsoncxx/stdx/string_view.hpp
     bsoncxx/v_noabi/bsoncxx/stdx/type_traits.hpp
     bsoncxx/v_noabi/bsoncxx/string/to_string.hpp
+    bsoncxx/v_noabi/bsoncxx/string/view_or_value-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/string/view_or_value.hpp
+    bsoncxx/v_noabi/bsoncxx/types-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/types.hpp
     bsoncxx/v_noabi/bsoncxx/types/bson_value/make_value.hpp
+    bsoncxx/v_noabi/bsoncxx/types/bson_value/value-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp
     bsoncxx/v_noabi/bsoncxx/types/bson_value/view_or_value.hpp
+    bsoncxx/v_noabi/bsoncxx/types/bson_value/view-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/types/bson_value/view.hpp
     bsoncxx/v_noabi/bsoncxx/types/value.hpp
     bsoncxx/v_noabi/bsoncxx/util/functor.hpp
+    bsoncxx/v_noabi/bsoncxx/validate-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/validate.hpp
+    bsoncxx/v_noabi/bsoncxx/view_or_value-fwd.hpp
     bsoncxx/v_noabi/bsoncxx/view_or_value.hpp
 )

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

@@ -0,0 +1,29 @@
+// Copyright 2023 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.
+
+#pragma once
+
+#include <bsoncxx/config/prelude.hpp>
+
+namespace bsoncxx {
+inline namespace v_noabi {
+namespace array {
+
+class BSONCXX_API element;
+
+}  // namespace array
+}  // namespace v_noabi
+}  // namespace bsoncxx
+
+#include <bsoncxx/config/postlude.hpp>

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

@@ -17,18 +17,16 @@
 #include <cstddef>
 #include <cstdint>
 
+#include <bsoncxx/array/element-fwd.hpp>
+#include <bsoncxx/array/view-fwd.hpp>
+#include <bsoncxx/types/bson_value/view-fwd.hpp>
+
 #include <bsoncxx/document/element.hpp>
 
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
 inline namespace v_noabi {
-namespace types {
-namespace bson_value {
-class view;
-}  // namespace bson_value
-}  // namespace types
-
 namespace array {
 
 ///
@@ -38,7 +36,7 @@ namespace array {
 /// interrogated by calling type() and a specific value can be extracted through
 /// get_X() accessors.
 ///
-class BSONCXX_API element : private document::element {
+class element : private document::element {
    public:
     element();
 
@@ -80,7 +78,7 @@ class BSONCXX_API element : private document::element {
     using document::element::raw;
 
    private:
-    friend class view;
+    friend ::bsoncxx::v_noabi::array::view;
 
     BSONCXX_PRIVATE explicit element(const std::uint8_t* raw,
                                      std::uint32_t length,
@@ -121,7 +119,6 @@ BSONCXX_API bool BSONCXX_CALL operator!=(const types::bson_value::view& v, const
 ///
 
 }  // namespace array
-
 }  // namespace v_noabi
 }  // namespace bsoncxx
 

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

@@ -0,0 +1,29 @@
+// Copyright 2023 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.
+
+#pragma once
+
+#include <bsoncxx/config/prelude.hpp>
+
+namespace bsoncxx {
+inline namespace v_noabi {
+namespace array {
+
+class BSONCXX_API value;
+
+}  // namespace array
+}  // namespace v_noabi
+}  // namespace bsoncxx
+
+#include <bsoncxx/config/postlude.hpp>

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

@@ -17,6 +17,8 @@
 #include <cstdlib>
 #include <memory>
 
+#include <bsoncxx/array/value-fwd.hpp>
+
 #include <bsoncxx/array/view.hpp>
 #include <bsoncxx/document/value.hpp>
 
@@ -31,7 +33,7 @@ namespace array {
 /// out of scope, the underlying buffer is freed. Generally this class should be used
 /// sparingly; array::view should be used instead wherever possible.
 ///
-class BSONCXX_API value {
+class value {
    public:
     using deleter_type = void (*)(std::uint8_t*);
     using unique_ptr_type = std::unique_ptr<uint8_t[], deleter_type>;

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

@@ -0,0 +1,29 @@
+// Copyright 2023 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.
+
+#pragma once
+
+#include <bsoncxx/config/prelude.hpp>
+
+namespace bsoncxx {
+inline namespace v_noabi {
+namespace array {
+
+class BSONCXX_API view;
+
+}  // namespace array
+}  // namespace v_noabi
+}  // namespace bsoncxx
+
+#include <bsoncxx/config/postlude.hpp>

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

@@ -18,25 +18,22 @@
 #include <cstdint>
 #include <iterator>
 
+#include <bsoncxx/array/view-fwd.hpp>
+#include <bsoncxx/types/bson_value/view-fwd.hpp>
+
 #include <bsoncxx/array/element.hpp>
 #include <bsoncxx/document/view.hpp>
 
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
 inline namespace v_noabi {
-namespace types {
-namespace bson_value {
-class view;
-}  // namespace bson_value
-}  // namespace types
-
 namespace array {
 
 ///
 /// A read-only, non-owning view of a BSON document.
 ///
-class BSONCXX_API view {
+class view {
    public:
     class BSONCXX_API const_iterator;
     using iterator = const_iterator;
@@ -155,7 +152,7 @@ class BSONCXX_API view {
 /// This iterator type provides a const forward iterator interface to array
 /// view elements.
 ///
-class BSONCXX_API view::const_iterator {
+class view::const_iterator {
    public:
     ///
     /// std::iterator_traits

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

@@ -0,0 +1,27 @@
+// Copyright 2023 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.
+
+#pragma once
+
+namespace bsoncxx {
+inline namespace v_noabi {
+namespace builder {
+namespace basic {
+
+class array;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace v_noabi
+}  // namespace bsoncxx

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

@@ -14,6 +14,8 @@
 
 #pragma once
 
+#include <bsoncxx/builder/basic/array-fwd.hpp>
+
 #include <bsoncxx/array/value.hpp>
 #include <bsoncxx/array/view.hpp>
 #include <bsoncxx/builder/basic/impl.hpp>

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

@@ -0,0 +1,27 @@
+// Copyright 2023 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.
+
+#pragma once
+
+namespace bsoncxx {
+inline namespace v_noabi {
+namespace builder {
+namespace basic {
+
+class document;
+
+}  // namespace basic
+}  // namespace builder
+}  // namespace v_noabi
+}  // namespace bsoncxx

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

@@ -14,6 +14,9 @@
 
 #pragma once
 
+#include <bsoncxx/builder/basic/array-fwd.hpp>
+#include <bsoncxx/builder/basic/document-fwd.hpp>
+
 #include <bsoncxx/builder/basic/impl.hpp>
 #include <bsoncxx/builder/basic/kvp.hpp>
 #include <bsoncxx/builder/basic/sub_document.hpp>
@@ -28,8 +31,6 @@ inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
-class array;
-
 ///
 /// A traditional builder-style interface for constructing
 /// a BSON document.