CXX-3108 Address missing enum member documentation Doxgyen warnings (#1211)

* doxygen: set WARN_IF_UNDOC_ENUM_VAL = YES

* doxygen: address missing enum member documentation warnings

* Avoid wrapping \see references to external resources

* Address false-positive -Wdocumentation warnings due to empty paragraphs

Author: eramongodb

.clang-format

@@ -5,7 +5,7 @@ BasedOnStyle: Google
 BinPackArguments: false
 BinPackParameters: false
 ColumnLimit: 100
-CommentPragmas: '^\s*@(addtogroup|copydoc|defgroup|fn|ref)'
+CommentPragmas: '^\s*(@(addtogroup|copydoc|defgroup|fn|ref)|- )'
 Cpp11BracedListStyle: true
 DerivePointerAlignment: false
 IncludeBlocks: Regroup

Doxyfile

@@ -883,7 +883,7 @@ WARN_NO_PARAMDOC       = NO
 # will automatically be disabled.
 # The default value is: NO.
 
-WARN_IF_UNDOC_ENUM_VAL = NO # TODO: set to YES.
+WARN_IF_UNDOC_ENUM_VAL = YES
 
 # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when
 # a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS

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

@@ -42,7 +42,8 @@ namespace bson_value {
 /// For accessors into this type and to extract the various BSON types out,
 /// please use bson_value::view.
 ///
-/// @see @ref bsoncxx::v_noabi::types::bson_value::view
+/// @see
+/// - @ref bsoncxx::v_noabi::types::bson_value::view
 ///
 class value {
    public:

src/mongocxx/include/mongocxx/v_noabi/mongocxx/exception/error_code.hpp

@@ -97,18 +97,18 @@ enum class error_code : std::int32_t {
     /// A moved-from mongocxx::v_noabi::options::transaction object has been used.
     k_invalid_transaction_options_object,
 
-    // A resource (server API handle, etc.) could not be created:
+    /// A resource (server API handle, etc.) could not be created:
     k_create_resource_fail,
 
-    // A default-constructed or moved-from mongocxx::v_noabi::search_index_model object has been
-    // used.
+    /// A default-constructed or moved-from mongocxx::v_noabi::search_index_model object has been
+    /// used.
     k_invalid_search_index_model,
 
-    // A default-constructed or moved-from mongocxx::v_noabi::search_index_view object has been
-    // used.
+    /// A default-constructed or moved-from mongocxx::v_noabi::search_index_view object has been
+    /// used.
     k_invalid_search_index_view,
 
-    // Timed out while waiting for a client to be returned to the pool
+    /// Timed out while waiting for a client to be returned to the pool
     k_pool_wait_queue_timeout,
 
     // Add new constant string message to error_code.cpp as well!

src/mongocxx/include/mongocxx/v_noabi/mongocxx/logger.hpp

@@ -31,13 +31,13 @@ namespace v_noabi {
 /// The log level of a message passed to a mongocxx::v_noabi::logger.
 ///
 enum class log_level {
-    k_error,
-    k_critical,
-    k_warning,
-    k_message,
-    k_info,
-    k_debug,
-    k_trace,
+    k_error,     ///< Log Level Error.
+    k_critical,  ///< Log Level Critical.
+    k_warning,   ///< Log Level Warning.
+    k_message,   ///< Log Level Message.
+    k_info,      ///< Log Level Info.
+    k_debug,     ///< Log Level Debug.
+    k_trace,     ///< Log Level Trace.
 };
 
 ///

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

@@ -34,12 +34,17 @@ namespace options {
 ///
 /// Class representing options for server API.
 ///
+/// @see
+/// - [Stable API (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/stable-api/)
+///
 class server_api {
    public:
     ///
     /// Enum representing the possible values for server API version.
     ///
-    enum class version { k_version_1 };
+    enum class version {
+        k_version_1,  ///< Stable API Version 1.
+    };
 
     ///
     /// Constructs a new server_api object.

src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp

@@ -52,23 +52,26 @@ namespace v_noabi {
 /// a single document. Note that writes must be made with majority write concern in order for reads
 /// to be linearizable.
 ///
-/// @see https://www.mongodb.com/docs/manual/reference/read-concern/
+/// @see
+/// - [Read Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/)
 ///
 class read_concern {
    public:
     ///
-    /// A class to represent the read concern level.
+    /// A class to represent the read concern level for read operations.
     ///
-    /// @see https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels
+    /// @see
+    /// - [Read Concern Levels (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels)
+    /// - [Default MongoDB Read Concerns/Write Concerns (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#read-concern)
     ///
     enum class level {
-        k_local,
-        k_majority,
-        k_linearizable,
-        k_server_default,
-        k_unknown,
-        k_available,
-        k_snapshot
+        k_local,           ///< Represent read concern level "local".
+        k_majority,        ///< Represent read concern level "majority".
+        k_linearizable,    ///< Represent read concern level "linearizable".
+        k_server_default,  ///< Represent the server's default read concern level.
+        k_unknown,         ///< Represent an unknown read concern level.
+        k_available,       ///< Represent read concern level "available".
+        k_snapshot         ///< Represent read concern level "snapshot".
     };
 
     ///

src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp

@@ -58,14 +58,15 @@ class validation_criteria {
     ///
     /// A class to represent the different validation level options.
     ///
-    /// - k_off: Disable validation entirely.
-    /// - k_moderate: Apply validation rules to inserts, and apply validation rules to updates only
-    ///   if the document to be updated already fulfills the validation criteria.
-    /// - k_strict: Apply validation rules to all inserts and updates.
-    ///
     enum class validation_level {
+        /// Disable validation entirely.
         k_off,
+
+        /// Apply validation rules to inserts, and apply validation rules to updates only if the
+        /// document to be updated already fulfills the validation criteria.
         k_moderate,
+
+        /// Apply validation rules to all inserts and updates.
         k_strict,
     };
 
@@ -92,12 +93,12 @@ class validation_criteria {
     ///
     /// A class to represent the different validation action options.
     ///
-    /// - k_error: Reject any insertion or update that violates the validation criteria.
-    /// - k_warn: Log any violations of the validation criteria, but allow the insertion or update
-    ///   to proceed.
-    ///
     enum class validation_action {
+        /// Reject any insertion or update that violates the validation criteria.
         k_error,
+
+        /// Log any violations of the validation criteria, but allow the insertion or update to
+        /// proceed.
         k_warn,
     };
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp

@@ -55,15 +55,25 @@ namespace v_noabi {
 /// critical operations, clients can adjust the write concern to ensure better performance
 /// rather than persistence to the entire deployment.
 ///
-/// @see https://www.mongodb.com/docs/manual/core/write-concern/
+/// @see
+/// - [Write Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/write-concern/)
 ///
 class write_concern {
    public:
     ///
-    /// A class to represent the special case values for write_concern::nodes.
-    /// @see https://www.mongodb.com/docs/manual/reference/write-concern/#w-option
+    /// A class to represent the write concern level for write operations.
+    ///
+    /// @see
+    /// - [Write Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/write-concern/)
+    /// - [Default MongoDB Read Concerns/Write Concerns](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#write-concern)
     ///
-    enum class level { k_default, k_majority, k_tag, k_unacknowledged, k_acknowledged };
+    enum class level {
+        k_default,         ///< Represent the implicit default write concern.
+        k_majority,        ///< Represent write concern with `w: "majority"`.
+        k_tag,             ///< Represent write concern with `w: <custom write concern name>`.
+        k_unacknowledged,  ///< Represent write concern with `w: 0`.
+        k_acknowledged,    ///< Represent write concern with `w: 1`.
+    };
 
     ///
     /// Constructs a new write_concern.