Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eramongodb merged 13 commits into from
Aug 5, 2024
Merged

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

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
113aec1
Formatting
eramongodb Jul 30, 2024
ab85f82
Address -Wzero-as-null-pointer-constant warnings
eramongodb Jul 30, 2024
7e467c8
Address -Wundef warnings
eramongodb Jul 31, 2024
6384d80
Restrict Doxygen examples to examples/
eramongodb Jul 31, 2024
015851a
Fix Doxygen docs and parsing in stdx and config headers
eramongodb Jul 30, 2024
09de5ae
Partially fix docs for bsoncxx::v_noabi::error_code
eramongodb Jul 30, 2024
13ed686
CXX-3069 document headers and redeclarations (bsoncxx)
eramongodb Jul 31, 2024
51bc74b
Fix consistency of @file descriptions
eramongodb Aug 1, 2024
12e1de2
Fix copy-paste errors
eramongodb Aug 5, 2024
6de89ae
Document make_unique as deprecated
eramongodb Aug 5, 2024
87dafaf
Update examples to avoid using stdx::make_unique
eramongodb Aug 5, 2024
14ad303
Address -Wmissing-include-dirs warnings for examples
eramongodb Aug 5, 2024
250c2b2
Also add docs for make_unique redeclarations
eramongodb Aug 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions Doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
18 changes: 18 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
27 changes: 27 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
18 changes: 18 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/value-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
5 changes: 5 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/value.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
///
18 changes: 18 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
5 changes: 5 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,3 +190,8 @@ class view::const_iterator {
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// Provides @ref bsoncxx::v_noabi::array::view.
///
18 changes: 18 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view_or_value.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
20 changes: 20 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/array-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
21 changes: 21 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/array.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Copy link
Collaborator

@kevinAlbs kevinAlbs Aug 2, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirming: Is mixing ABI namespace and root namespace discouraged?

// Do this:
bsoncxx::foo f = bsoncxx::get_foo();
// Or even better:
auto f = bsoncxx::get_foo();
// Not this:
bsoncxx::v_noabi::foo f = bsoncxx::get_foo();

I expect using the root namespace helps avoid source code changes on ABI incompatible (but API compatible) driver changes. However, mixing may result in more needed source code changes (e.g. if bsoncxx::get_foo() later defined to return bsoncxx::v1::foo).

Copy link
Contributor Author

@eramongodb eramongodb Aug 5, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is mixing ABI namespace and root namespace discouraged?

Yes, for the reason you described regarding bsoncxx::get_foo() returning bsoncxx::v1::foo.

However, old ABI namespace interfaces are expected to provide conversion functions to/from the new ABI namespace interfaces, which will assist with incremental migration across ABI namespaces. This is already being implemented for CXX-2745.

// OK: implicit conversion from `v1::foo` to `v_noabi::foo`
// as defined by `v_noabi::foo` (implicit constructor).
v_noabi::foo f = v1::get_foo();

// OK: explicit conversion from `v1::foo` to `v_noabi::foo`
// via the `v_noabi` conversion function.
v_noabi::foo f = v_noabi::from_v1(v1::get_foo());

// error: from v1 to what? (ADL not supported.)
v_noabi::foo f = from_v1(v1::get_foo());

// error: conversion from `v_noabi::foo` to `v1::foo`
// must be explicit (one-way implicit conversions).
v1::foo f = v_noabi::get_foo();

// OK: explicit forward-compatibility via conversion function.
v1::foo f = v_noabi::to_v1(v_noabi::get_foo());

// OK: same as above, but found via ADL.
v1::foo f = to_v1(v_noabi::get_foo());

The (implicit) conversions will of course come with a performance cost, so relying on them too much is not recommended. However, this will faciliate incremental migration from vA to vB both in user code and in internal code.


} // namespace basic
} // namespace builder
} // namespace bsoncxx

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
20 changes: 20 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/document-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
21 changes: 21 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/document.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
23 changes: 23 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/helpers.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,26 @@ using ::bsoncxx::v_noabi::builder::basic::concatenate;
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// Redeclares @ref bsoncxx::v_noabi::builder::concatenate in the @ref
/// bsoncxx::v_noabi::builder::basic namespace.
///

#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

namespace bsoncxx {
namespace builder {
namespace basic {

/// @ref bsoncxx::v_noabi::builder::concatenate(v_noabi::document::view_or_value doc)
/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
/// v_noabi::builder::concatenate_array is also declared in this scope.
v_noabi::concatenate_doc concatenate(v_noabi::document::view_or_value doc);

} // namespace basic
} // namespace builder
} // namespace bsoncxx

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
5 changes: 5 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/impl.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,3 +62,8 @@ BSONCXX_INLINE void value_append(core* core, T&& t) {
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// For internal use only!
///
21 changes: 21 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/kvp.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,3 +48,24 @@ using ::bsoncxx::v_noabi::builder::basic::kvp;
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// Declares @ref bsoncxx::v_noabi::builder::basic::kvp.
///

#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

namespace bsoncxx {
namespace builder {
namespace basic {

/// @ref bsoncxx::v_noabi::builder::basic::kvp
template <typename T, typename U>
std::tuple<T&&, U&&> kvp(T&& t, U&& u);

} // namespace basic
} // namespace builder
} // namespace bsoncxx

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
20 changes: 20 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_array-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,23 @@ using ::bsoncxx::v_noabi::builder::basic::sub_array;
} // namespace basic
} // namespace builder
} // namespace bsoncxx

///
/// @file
/// Declares @ref bsoncxx::v_noabi::builder::basic::sub_array.
///

#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

namespace bsoncxx {
namespace builder {
namespace basic {

/// @ref bsoncxx::v_noabi::builder::basic::sub_array
class sub_array {};

} // namespace basic
} // namespace builder
} // namespace bsoncxx

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
5 changes: 5 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_array.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,8 @@ class sub_array {
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// Provides @ref bsoncxx::v_noabi::builder::basic::sub_array.
///
20 changes: 20 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_document-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,3 +35,23 @@ using ::bsoncxx::v_noabi::builder::basic::sub_document;
} // namespace basic
} // namespace builder
} // namespace bsoncxx

///
/// @file
/// Declares @ref bsoncxx::v_noabi::builder::basic::sub_document.
///

#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

namespace bsoncxx {
namespace builder {
namespace basic {

/// @ref bsoncxx::v_noabi::builder::basic::sub_document
class sub_document {};

} // namespace basic
} // namespace builder
} // namespace bsoncxx

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
5 changes: 5 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/basic/sub_document.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,3 +106,8 @@ class sub_document {
} // namespace bsoncxx

#include <bsoncxx/config/postlude.hpp>

///
/// @file
/// Provides @ref bsoncxx::v_noabi::builder::basic::sub_document.
///
Loading