From 310460fb61b8d638b01efe9fe6cc7d40910f2191 Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 18 Sep 2024 15:32:15 -0500 Subject: [PATCH 1/5] doxygen: set WARN_IF_UNDOC_ENUM_VAL = YES --- Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doxyfile b/Doxyfile index 7ba9557838..052fb63226 100644 --- a/Doxyfile +++ b/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 From 7695e4af48cf09e752a28885ee180174db25a3ec Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 18 Sep 2024 15:32:17 -0500 Subject: [PATCH 2/5] doxygen: address missing enum member documentation warnings --- .../v_noabi/mongocxx/exception/error_code.hpp | 12 ++++----- .../mongocxx/v_noabi/mongocxx/logger.hpp | 14 +++++----- .../v_noabi/mongocxx/options/server_api.hpp | 7 ++++- .../v_noabi/mongocxx/read_concern.hpp | 26 ++++++++++++------- .../v_noabi/mongocxx/validation_criteria.hpp | 20 +++++++------- .../v_noabi/mongocxx/write_concern.hpp | 23 ++++++++++++---- 6 files changed, 62 insertions(+), 40 deletions(-) diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/exception/error_code.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/exception/error_code.hpp index 6da2d15435..f3978efbb9 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/exception/error_code.hpp +++ b/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! diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/logger.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/logger.hpp index a069020a99..9d6b78fd2b 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/logger.hpp +++ b/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. }; /// diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp index a7ce897d76..896407a0d4 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp @@ -34,12 +34,17 @@ namespace options { /// /// Class representing options for server API. /// +/// @see @li [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. diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp index 3f9fe3ff00..845f5fdf72 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp @@ -52,23 +52,29 @@ 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 @li [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 @parblock + /// @li [Read Concern Levels (MongoDB + /// Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels) + /// @li [Default MongoDB Read Concerns/Write Concerns (MongoDB + /// Manual)](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#read-concern) + /// @endparblock /// 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". }; /// diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp index d926f88299..f4a482be8b 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp +++ b/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,13 +93,10 @@ 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 { - k_error, - k_warn, + 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. }; /// diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp index d17d8e3bb1..7d051933dc 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp @@ -55,15 +55,28 @@ 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 @li [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 - /// - enum class level { k_default, k_majority, k_tag, k_unacknowledged, k_acknowledged }; + /// A class to represent the write concern level for write operations. + /// + /// @see @parblock + /// @li [Write Concern (MongoDB + /// Manual)](https://www.mongodb.com/docs/manual/reference/write-concern/) + /// @li [Default MongoDB Read Concerns/Write + /// Concerns](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#write-concern) + /// @endparblock + /// + 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: `. + k_unacknowledged, ///< Represent write concern with `w: 0`. + k_acknowledged, ///< Represent write concern with `w: 1`. + }; /// /// Constructs a new write_concern. From 886bb89554a570e31aa29352bcbf28707c963c5f Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 18 Sep 2024 16:25:55 -0500 Subject: [PATCH 3/5] Avoid wrapping \see references to external resources --- .clang-format | 2 +- .../mongocxx/v_noabi/mongocxx/options/server_api.hpp | 3 +-- .../include/mongocxx/v_noabi/mongocxx/read_concern.hpp | 9 +++------ .../include/mongocxx/v_noabi/mongocxx/write_concern.hpp | 9 +++------ 4 files changed, 8 insertions(+), 15 deletions(-) diff --git a/.clang-format b/.clang-format index ee492ffdc5..5732f18d60 100644 --- a/.clang-format +++ b/.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|li \[|ref|see @li \[)' Cpp11BracedListStyle: true DerivePointerAlignment: false IncludeBlocks: Regroup diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp index 896407a0d4..9922c4025b 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp @@ -34,8 +34,7 @@ namespace options { /// /// Class representing options for server API. /// -/// @see @li [Stable API (MongoDB -/// Manual)](https://www.mongodb.com/docs/manual/reference/stable-api/) +/// @see @li [Stable API (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/stable-api/) /// class server_api { public: diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp index 845f5fdf72..aaa4807136 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp @@ -52,8 +52,7 @@ namespace v_noabi { /// a single document. Note that writes must be made with majority write concern in order for reads /// to be linearizable. /// -/// @see @li [Read Concern (MongoDB -/// Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/) +/// @see @li [Read Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/) /// class read_concern { public: @@ -61,10 +60,8 @@ class read_concern { /// A class to represent the read concern level for read operations. /// /// @see @parblock - /// @li [Read Concern Levels (MongoDB - /// Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels) - /// @li [Default MongoDB Read Concerns/Write Concerns (MongoDB - /// Manual)](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#read-concern) + /// @li [Read Concern Levels (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels) + /// @li [Default MongoDB Read Concerns/Write Concerns (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#read-concern) /// @endparblock /// enum class level { diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp index 7d051933dc..35ccf67a04 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp @@ -55,8 +55,7 @@ namespace v_noabi { /// critical operations, clients can adjust the write concern to ensure better performance /// rather than persistence to the entire deployment. /// -/// @see @li [Write Concern (MongoDB -/// Manual)](https://www.mongodb.com/docs/manual/core/write-concern/) +/// @see @li [Write Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/core/write-concern/) /// class write_concern { public: @@ -64,10 +63,8 @@ class write_concern { /// A class to represent the write concern level for write operations. /// /// @see @parblock - /// @li [Write Concern (MongoDB - /// Manual)](https://www.mongodb.com/docs/manual/reference/write-concern/) - /// @li [Default MongoDB Read Concerns/Write - /// Concerns](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#write-concern) + /// @li [Write Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/write-concern/) + /// @li [Default MongoDB Read Concerns/Write Concerns](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#write-concern) /// @endparblock /// enum class level { From 0bddc8b5dbdbae79dc990e573f9d0e94e915bd83 Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 18 Sep 2024 16:26:27 -0500 Subject: [PATCH 4/5] Avoid wrapping of inline enumerator documentation --- .../mongocxx/v_noabi/mongocxx/validation_criteria.hpp | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp index f4a482be8b..8b62a435b5 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/validation_criteria.hpp @@ -94,9 +94,12 @@ class validation_criteria { /// A class to represent the different validation action options. /// enum class validation_action { - 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. + /// 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, }; /// From 534fd5bd47aefca7c96da1d3b94970f169b4239c Mon Sep 17 00:00:00 2001 From: Ezra Chung Date: Wed, 18 Sep 2024 16:42:05 -0500 Subject: [PATCH 5/5] Address false-positive -Wdocumentation warnings due to empty paragraphs --- .clang-format | 2 +- .../bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp | 3 ++- .../mongocxx/v_noabi/mongocxx/options/server_api.hpp | 3 ++- .../include/mongocxx/v_noabi/mongocxx/read_concern.hpp | 10 +++++----- .../mongocxx/v_noabi/mongocxx/write_concern.hpp | 10 +++++----- 5 files changed, 15 insertions(+), 13 deletions(-) diff --git a/.clang-format b/.clang-format index 5732f18d60..f82be6d0cc 100644 --- a/.clang-format +++ b/.clang-format @@ -5,7 +5,7 @@ BasedOnStyle: Google BinPackArguments: false BinPackParameters: false ColumnLimit: 100 -CommentPragmas: '^\s*@(addtogroup|copydoc|defgroup|fn|li \[|ref|see @li \[)' +CommentPragmas: '^\s*(@(addtogroup|copydoc|defgroup|fn|ref)|- )' Cpp11BracedListStyle: true DerivePointerAlignment: false IncludeBlocks: Regroup diff --git a/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp b/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp index 52a0ba2f6f..166405f6d7 100644 --- a/src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp +++ b/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: diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp index 9922c4025b..f560c38afc 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/options/server_api.hpp @@ -34,7 +34,8 @@ namespace options { /// /// Class representing options for server API. /// -/// @see @li [Stable API (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/stable-api/) +/// @see +/// - [Stable API (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/stable-api/) /// class server_api { public: diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp index aaa4807136..dfa04b7d1b 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/read_concern.hpp @@ -52,17 +52,17 @@ namespace v_noabi { /// a single document. Note that writes must be made with majority write concern in order for reads /// to be linearizable. /// -/// @see @li [Read Concern (MongoDB Manual)](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 for read operations. /// - /// @see @parblock - /// @li [Read Concern Levels (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/read-concern/#read-concern-levels) - /// @li [Default MongoDB Read Concerns/Write Concerns (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#read-concern) - /// @endparblock + /// @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, ///< Represent read concern level "local". diff --git a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp index 35ccf67a04..bee83a759f 100644 --- a/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp +++ b/src/mongocxx/include/mongocxx/v_noabi/mongocxx/write_concern.hpp @@ -55,17 +55,17 @@ namespace v_noabi { /// critical operations, clients can adjust the write concern to ensure better performance /// rather than persistence to the entire deployment. /// -/// @see @li [Write Concern (MongoDB Manual)](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 write concern level for write operations. /// - /// @see @parblock - /// @li [Write Concern (MongoDB Manual)](https://www.mongodb.com/docs/manual/reference/write-concern/) - /// @li [Default MongoDB Read Concerns/Write Concerns](https://www.mongodb.com/docs/manual/reference/mongodb-defaults/#write-concern) - /// @endparblock + /// @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, ///< Represent the implicit default write concern.