CXX-3070 Address -Wdocumentation Clang warnings (#1175)

Author: eramongodb

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/json.hpp

@@ -57,8 +57,7 @@ BSONCXX_API std::string BSONCXX_CALL to_json(array::view view,
 ///
 /// Constructs a new document::value from the provided JSON text.
 ///
-/// @param 'json'
-///  A string_view into a JSON document.
+/// @param json A string_view into a JSON document.
 ///
 /// @returns A document::value if conversion worked.
 ///
@@ -70,11 +69,9 @@ BSONCXX_API document::value BSONCXX_CALL from_json(stdx::string_view json);
 /// Constructs a new document::value from the provided JSON text. This is the UDL version of
 /// from_json().
 ///
-/// @param 'json'
-///  A string into a JSON document.
+/// @param json A string into a JSON document.
 ///
-/// @param 'len'
-///  The length of the JSON string. This is calculated automatically upon use of the UDL.
+/// @param len The length of the JSON string. This is calculated automatically upon use of the UDL.
 ///
 /// @returns A document::value if conversion worked.
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/stdx/optional.hpp

@@ -475,11 +475,7 @@ constexpr copymove_classification classify_assignment() {
     return CanCopy ? copyable : CanMove ? movable : immobile;
 }
 
-/**
- * @brief Common base class for optional storage implementation
- *
- * @tparam T
- */
+/// Common base class for optional storage implementation
 template <typename T>
 class optional_common_base;
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/stdx/type_traits.hpp

@@ -435,7 +435,7 @@ static constexpr struct invoke_fn {
 /**
  * @brief Yields the type that would result from invoking F with the given arguments.
  *
- * @tparam Fun A invocable: A function pointer or callable object, or a member pointer
+ * @tparam F An invocable function pointer, object, or pointer-to-member.
  * @tparam Args The arguments to apply
  */
 template <typename F, typename... Args>
@@ -444,14 +444,14 @@ using invoke_result_t = decltype(invoke(std::declval<F>(), std::declval<Args>().
 /**
  * @brief Trait type to detect if the given object can be "invoked" using the given arguments.
  *
- * @tparam Fun A invocable: A function pointer or callable object, or a member pointer
+ * @tparam F An invocable function pointer, object, or pointer-to-member.
  * @tparam Args The arguments to match against
  */
-template <typename Fun, typename... Args>
+template <typename F, typename... Args>
 #if defined(_MSC_VER) && _MSC_VER < 1910
-using is_invocable = is_detected<invoke_result_t, Fun, Args...>;
+using is_invocable = is_detected<invoke_result_t, F, Args...>;
 #else
-struct is_invocable : is_detected<invoke_result_t, Fun, Args...> {
+struct is_invocable : is_detected<invoke_result_t, F, Args...> {
 };
 #endif
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types.hpp

@@ -240,8 +240,7 @@ BSONCXX_INLINE bool operator==(const b_binary& lhs, const b_binary& rhs) {
 ///
 /// A BSON undefined value.
 ///
-/// @deprecated
-///   This BSON type is deprecated and use by clients is discouraged.
+/// @deprecated This BSON type is deprecated. Usage is discouraged.
 ///
 struct b_undefined {
     static constexpr auto type_id = type::k_undefined;
@@ -409,10 +408,9 @@ BSONCXX_INLINE bool operator==(const b_regex& lhs, const b_regex& rhs) {
 }
 
 ///
-/// A BSON DBPointer value.
+/// A BSON DBPointer (aka DBRef) value.
 ///
-/// @deprecated
-///   A BSON DBPointer (aka DBRef) is still supported but deprecated.
+/// @deprecated This BSON type is deprecated. Usage is discouraged.
 ///
 struct b_dbpointer {
     static constexpr auto type_id = type::k_dbpointer;
@@ -467,8 +465,7 @@ BSONCXX_INLINE bool operator==(const b_code& lhs, const b_code& rhs) {
 ///
 /// A BSON Symbol value.
 ///
-/// @deprecated
-///   This BSON type is deprecated and use by clients is discouraged.
+/// @deprecated This BSON type is deprecated. Usage is discouraged.
 ///
 struct b_symbol {
     static constexpr auto type_id = type::k_symbol;

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp

@@ -153,8 +153,7 @@ class value {
     /// @param value
     ///     the object id
     ///
-    /// @deprecated
-    ///   A BSON DBPointer (aka DBRef) is still supported but deprecated.
+    /// @warning The DBPointer (aka DBRef) BSON type is deprecated. Usage is discouraged.
     ///
     value(stdx::string_view collection, oid value);
 
@@ -192,10 +191,8 @@ class value {
     ///
     /// @throws bsoncxx::v_noabi::exception if the type's value is not k_code, k_regex, or k_symbol.
     ///
-    /// @deprecated
-    ///   The BSON symbol type is deprecated and use by clients is discouraged.
-    /// @deprecated
-    ///   The BSON undefined type is deprecated and use by clients is discouraged.
+    /// @warning The Symbol BSON type is deprecated. Usage is discouraged.
+    /// @warning The Undefined BSON type is deprecated. Usage is discouraged.
     ///
     value(const type id, stdx::string_view v);
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/client_session.hpp

@@ -168,6 +168,11 @@ class client_session {
     ///
     void abort_transaction();
 
+    ///
+    /// Represents a callback invoked within a transaction.
+    ///
+    using with_transaction_cb = std::function<void MONGOCXX_CALL(client_session*)>;
+
     ///
     /// Helper to run a user-provided callback within a transaction.
     ///
@@ -189,7 +194,6 @@ class client_session {
     /// @throws mongocxx::v_noabi::operation_exception if there are errors completing the
     /// transaction.
     ///
-    using with_transaction_cb = std::function<void MONGOCXX_CALL(client_session*)>;
     void with_transaction(with_transaction_cb cb, options::transaction opts = {});
 
    private:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/auto_encryption.hpp

@@ -96,6 +96,11 @@ class auto_encryption {
     ///
     const stdx::optional<mongocxx::v_noabi::pool*>& key_vault_pool() const;
 
+    ///
+    /// Represents the name of a database and a collection.
+    ///
+    using ns_pair = std::pair<std::string, std::string>;
+
     ///
     /// Sets the namespace to use to access the key vault collection, which
     /// contains all data keys used for encryption and decryption. This
@@ -112,7 +117,6 @@ class auto_encryption {
     ///
     /// @see https://www.mongodb.com/docs/manual/core/security-client-side-encryption/
     ///
-    using ns_pair = std::pair<std::string, std::string>;
     auto_encryption& key_vault_namespace(ns_pair ns);
 
     ///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/client_encryption.hpp

@@ -58,6 +58,11 @@ class client_encryption {
     ///
     const stdx::optional<mongocxx::v_noabi::client*>& key_vault_client() const;
 
+    ///
+    /// Represents the name of a database and a collection.
+    ///
+    using ns_pair = std::pair<std::string, std::string>;
+
     ///
     /// Sets the namespace to use to access the key vault collection, which
     /// contains all data keys used for encryption and decryption. This
@@ -74,7 +79,6 @@ class client_encryption {
     ///
     /// @see https://www.mongodb.com/docs/manual/core/security-client-side-encryption/
     ///
-    using ns_pair = std::pair<std::string, std::string>;
     client_encryption& key_vault_namespace(ns_pair ns);
 
     ///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/data_key.hpp

@@ -122,6 +122,11 @@ class data_key {
     ///
     const std::vector<std::string>& key_alt_names() const;
 
+    ///
+    /// Represents binary data used to represent key material.
+    ///
+    using key_material_type = std::vector<uint8_t>;
+
     ///
     /// Sets the binary data for the key material
     ///
@@ -140,7 +145,6 @@ class data_key {
     ///
     /// @see https://www.mongodb.com/docs/v6.0/reference/method/KeyVault.createKey/
     ///
-    using key_material_type = std::vector<uint8_t>;
     data_key& key_material(key_material_type key_material);
 
     ///