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
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 all 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
4 changes: 0 additions & 4 deletions examples/bsoncxx/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 0 additions & 5 deletions examples/mongocxx/CMakeLists.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 6 additions & 2 deletions examples/mongocxx/connect.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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[]) {
Expand All @@ -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};
Expand Down
7 changes: 3 additions & 4 deletions examples/mongocxx/gridfs.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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))) {
Expand Down
8 changes: 5 additions & 3 deletions examples/mongocxx/index.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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);
Expand Down
13 changes: 8 additions & 5 deletions examples/mongocxx/instance_management.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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() {
Expand Down
1 change: 0 additions & 1 deletion examples/mongocxx/view_or_value_variant.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
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

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

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)
Loading