CXX-2762 Ensure ABI namespace is included in API documentation (#1039)

* Replace use of inline namespace macros with v_noabi

* Document top-level and v_noabi namespaces in prelude headers

* Update input paths and files to Doxygen

* Address warnings for undocumented entities

* Remove unused relates documentation for friend declarations

* Address undocumented parameter warnings

* Address ambiguous reference warnings for friend eclarations

* Address warnings for documentation of unnamed parameters

* Use @copydoc instead of group to document parameters

* Add missing generated macros to Doxygen config

* Ensures stdx entities are also documented

* Exclude detail namespace from Doxygen documentation

Author: eramongodb

CONTRIBUTING.md

@@ -43,9 +43,9 @@ General structure:
  - System Headers `<vector>` (alphabetical order)
  - Driver Headers `<path/to/header.hpp>` (alphabetical order)
  - Open Namespace mongocxx 
- - `MONGOCXX_INLINE_NAMESPACE_BEGIN`
+ - `inline namespace v_noabi {`
  -    Code
- - `MONGOCXX_INLINE_NAMESPACE_END`
+ - `}  // namespace v_noabi`
  - Close Namespace mongocxx
  - Header Postlude
 
@@ -75,13 +75,13 @@ Example:
 #include <driver/blah.hpp>
 
 namespace mongocxx {
-MONGOCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 
 // Declarations
 
 // Inline Implementations
 
-MONGOCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace mongocxx
 
 #include <driver/config/postlude.hpp>

Doxyfile

@@ -854,7 +854,8 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src \
+INPUT                  = src/bsoncxx/include \
+                         src/mongocxx/include \
                          etc/apidocmenu.md
 
 # This tag can be used to specify the character encoding of the source files
@@ -899,10 +900,7 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = src/third_party \
-                         src/mongocxx/test_util \
-                         src/mongocxx/private \
-                         src/bsoncxx/stdx
+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
@@ -918,7 +916,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = */private/*
+EXCLUDE_PATTERNS       =
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -929,7 +927,10 @@ EXCLUDE_PATTERNS       = */private/*
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = bsoncxx::detail \
+                         bsoncxx::*::detail \
+                         mongocxx::detail \
+                         mongocxx::*::detail
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2186,7 +2187,7 @@ SEARCH_INCLUDES        = YES
 # preprocessor.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           =
+INCLUDE_PATH           = src/bsoncxx/include/bsoncxx/v_noabi
 
 # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
 # patterns (like *.h and *.hpp) to filter out the header-files in the
@@ -2204,12 +2205,14 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = BSONCXX_INLINE= \
-                         BSONCXX_API= \
+PREDEFINED             = BSONCXX_API= \
                          BSONCXX_CALL= \
-                         MONGOCXX_INLINE= \
+                         BSONCXX_DEPRECATED \
+                         BSONCXX_INLINE= \
                          MONGOCXX_API= \
-                         MONGOCXX_CALL=
+                         MONGOCXX_CALL= \
+                         MONGOCXX_DEPRECATED \
+                         MONGOCXX_INLINE=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

docs/content/contributing/_index.md

@@ -53,9 +53,9 @@ General structure:
  - System Headers `<vector>` (alphabetical order)
  - Driver Headers `<path/to/header.hpp>` (alphabetical order)
  - Open Namespace mongocxx
- - `MONGOCXX_INLINE_NAMESPACE_BEGIN`
+ - `inline namespace v_noabi {`
  -    Code
- - `MONGOCXX_INLINE_NAMESPACE_END`
+ - `}  // namespace v_noabi`
  - Close Namespace mongocxx
  - Header Postlude
 
@@ -85,13 +85,13 @@ Example:
 #include <driver/blah.hpp>
 
 namespace mongocxx {
-MONGOCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 
 // Declarations
 
 // Inline Implementations
 
-MONGOCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace mongocxx
 
 #include <driver/config/postlude.hpp>

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

@@ -22,8 +22,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
-
+inline namespace v_noabi {
 namespace types {
 namespace bson_value {
 class view;
@@ -123,7 +122,7 @@ BSONCXX_API bool BSONCXX_CALL operator!=(const types::bson_value::view& v, const
 
 }  // namespace array
 
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -23,7 +23,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace array {
 
 ///
@@ -114,7 +114,7 @@ BSONCXX_INLINE value::operator array::view() const noexcept {
 }
 
 }  // namespace array
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -24,8 +24,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
-
+inline namespace v_noabi {
 namespace types {
 namespace bson_value {
 class view;
@@ -194,7 +193,7 @@ class BSONCXX_API view::const_iterator {
 };
 
 }  // namespace array
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

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

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

@@ -24,7 +24,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -113,7 +113,7 @@ bsoncxx::array::value BSONCXX_CALL make_array(Args&&... args) {
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -24,7 +24,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -116,7 +116,7 @@ bsoncxx::document::value BSONCXX_CALL make_document(Args&&... args) {
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -19,15 +19,15 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
 using bsoncxx::builder::concatenate;
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -21,7 +21,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 namespace impl {
@@ -63,7 +63,7 @@ BSONCXX_INLINE void value_append(core* core, T&& t) {
 }  // namespace impl
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -19,7 +19,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -34,7 +34,7 @@ BSONCXX_INLINE std::tuple<T&&, U&&> kvp(T&& t, U&& u) {
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -21,7 +21,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -80,7 +80,7 @@ class sub_array {
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

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

@@ -22,7 +22,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace basic {
 
@@ -99,7 +99,7 @@ class sub_document {
 
 }  // namespace basic
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp

@@ -20,7 +20,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 
 ///
@@ -116,7 +116,7 @@ BSONCXX_INLINE concatenate_array concatenate(array::view_or_value array) {
 }
 
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/core.hpp

@@ -28,7 +28,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 
 ///
@@ -692,7 +692,7 @@ class BSONCXX_API core {
 };
 
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/list.hpp

@@ -24,7 +24,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 using namespace bsoncxx::types;
 
@@ -184,5 +184,5 @@ class array : public list {
     array(initializer_list_t init) : list(init, false, true) {}
 };
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx

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

@@ -25,7 +25,7 @@
 #include <bsoncxx/config/prelude.hpp>
 
 namespace bsoncxx {
-BSONCXX_INLINE_NAMESPACE_BEGIN
+inline namespace v_noabi {
 namespace builder {
 namespace stream {
 
@@ -84,7 +84,7 @@ class array : public array_context<> {
 
 }  // namespace stream
 }  // namespace builder
-BSONCXX_INLINE_NAMESPACE_END
+}  // namespace v_noabi
 }  // namespace bsoncxx
 
 #include <bsoncxx/config/postlude.hpp>