CXX-3110 Standardize \see, \par, and \code command formatting (#1213)

* CXX-3110 Standardize \see command formatting

* Replace use of \parblock + \li with Markdown lists

* Replace \code with Markdown code blocks

Author: eramongodb

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/concatenate.hpp

@@ -91,7 +91,8 @@ struct concatenate_array {
 ///
 /// @return concatenate_doc A concatenating struct.
 ///
-/// @see bsoncxx::v_noabi::builder::concatenate_doc
+/// @see
+/// - @ref bsoncxx::v_noabi::builder::concatenate_doc
 ///
 inline concatenate_doc concatenate(document::view_or_value doc) {
     return {std::move(doc)};
@@ -107,7 +108,8 @@ inline concatenate_doc concatenate(document::view_or_value doc) {
 ///
 /// @return concatenate_doc A concatenating struct.
 ///
-/// @see bsoncxx::v_noabi::builder::concatenate_doc
+/// @see
+/// - @ref bsoncxx::v_noabi::builder::concatenate_doc
 ///
 inline concatenate_array concatenate(array::view_or_value array) {
     return {std::move(array)};

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/list.hpp

@@ -60,7 +60,8 @@ class list {
     /// @param value
     ///     the BSON value
     ///
-    /// @see bsoncxx::v_noabi::types::bson_value::value.
+    /// @see
+    /// - @ref bsoncxx::v_noabi::types::bson_value::value.
     ///
     template <typename T>
     list(T value) : val{value} {}
@@ -81,15 +82,17 @@ class list {
     ///     bsoncxx::v_noabi::builder::document or bsoncxx::v_noabi::builder::array constructor,
     ///     respectively.
     ///
-    /// @see bsoncxx::v_noabi::builder::document
-    /// @see bsoncxx::v_noabi::builder::array
+    /// @see
+    /// - @ref bsoncxx::v_noabi::builder::document
+    /// - @ref bsoncxx::v_noabi::builder::array
     ///
     list(initializer_list_t init) : list(init, true, true) {}
 
     ///
     /// Provides a view of the underlying BSON value.
     ///
-    /// @see bsoncxx::v_noabi::types::bson_value::view.
+    /// @see
+    /// - @ref bsoncxx::v_noabi::types::bson_value::view.
     ///
     operator bson_value::view() {
         return view();
@@ -98,7 +101,8 @@ class list {
     ///
     /// Provides a view of the underlying BSON value.
     ///
-    /// @see bsoncxx::v_noabi::types::bson_value::view.
+    /// @see
+    /// - @ref bsoncxx::v_noabi::types::bson_value::view.
     ///
     bson_value::view view() {
         return val.view();
@@ -168,8 +172,9 @@ class document : public list {
     /// @param init
     ///     the initializer list used to construct the BSON document
     ///
-    /// @see bsoncxx::v_noabi::builder::list
-    /// @see bsoncxx::v_noabi::builder::array
+    /// @see
+    /// - @ref bsoncxx::v_noabi::builder::list
+    /// - @ref bsoncxx::v_noabi::builder::array
     ///
     document(initializer_list_t init) : list(init, false, false) {}
 };
@@ -192,8 +197,9 @@ class array : public list {
     /// @param init
     ///     the initializer list used to construct the BSON array
     ///
-    /// @see bsoncxx::v_noabi::builder::list
-    /// @see bsoncxx::v_noabi::builder::document
+    /// @see
+    /// - @ref bsoncxx::v_noabi::builder::list
+    /// - @ref bsoncxx::v_noabi::builder::document
     ///
     array(initializer_list_t init) : list(init, false, true) {}
 };

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/array_context.hpp

@@ -166,7 +166,8 @@ class array_context {
     ///
     /// Conversion operator for single_context.
     ///
-    /// @see bsoncxx::v_noabi::builder::stream::single_context
+    /// @see
+    /// - @ref bsoncxx::v_noabi::builder::stream::single_context
     ///
     operator single_context();
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/helpers.hpp

@@ -61,8 +61,7 @@ struct open_array_type {
 /// A stream manipulator to open a subarray.
 ///
 /// @see
-/// https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/working-with-bson/#std-label-cpp-bson-builders
-/// for help building arrays in loops.
+/// - https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/working-with-bson/#std-label-cpp-bson-builders for help building arrays in loops.
 ///
 constexpr open_array_type open_array;
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/builder/stream/value_context.hpp

@@ -108,7 +108,8 @@ class value_context {
     ///
     /// Conversion operator for single_context.
     ///
-    /// @see bsoncxx::v_noabi::builder::stream::single_context
+    /// @see
+    /// - @ref bsoncxx::v_noabi::builder::stream::single_context
     ///
     operator single_context();
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/postlude.hpp

@@ -104,5 +104,6 @@ static_assert(false, "BSONCXX_ENUM must be undef'ed");
 /// This header uses macro pragmas to guard macros defined by the bsoncxx library for internal use
 /// by "popping" their prior definition onto the stack after use by bsoncxx headers.
 ///
-/// @see bsoncxx/v_noabi/bsoncxx/config/prelude.hpp
+/// @see
+/// - @ref bsoncxx/v_noabi/bsoncxx/config/prelude.hpp
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/config/prelude.hpp

@@ -131,16 +131,16 @@
 ///
 /// @warning For internal use only!
 ///
-/// @par "Includes" @parblock
-/// @li @ref bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-config-hpp
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-export-hpp
-/// @li @ref bsoncxx/v_noabi/bsoncxx/config/util.hpp
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-version-hpp
-/// @endparblock
+/// @par Includes
+/// - @ref bsoncxx/v_noabi/bsoncxx/config/compiler.hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-config-hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-export-hpp
+/// - @ref bsoncxx/v_noabi/bsoncxx/config/util.hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-version-hpp
 ///
 /// This header uses macro pragmas to guard macros defined by the bsoncxx library for internal use
 /// by "pushing" their prior definition onto the stack before use by bsoncxx headers.
 ///
-/// @see bsoncxx/v_noabi/bsoncxx/config/postlude.hpp
+/// @see
+/// - @ref bsoncxx/v_noabi/bsoncxx/config/postlude.hpp
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/document/element.hpp

@@ -40,7 +40,8 @@ namespace document {
 /// interrogated by calling type(), the key can be extracted by calling key() and
 /// a specific value can be extracted through get_X() accessors.
 ///
-/// @see bsoncxx::v_noabi::array::element
+/// @see
+/// - @ref bsoncxx::v_noabi::array::element
 ///
 class element {
    public:

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/fwd.hpp

@@ -51,10 +51,8 @@
 /// @file
 /// Aggregate of all forward headers declaring entities in @ref bsoncxx::v_noabi.
 ///
-/// @par "Includes" @parblock
-/// @li All header files under @ref src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx
-/// "bsoncxx/v_noabi/bsoncxx" whose filename ends with `-fwd.hpp`.
-/// @endparblock
+/// @par Includes
+/// - All header files under @ref src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx "bsoncxx/v_noabi/bsoncxx" whose filename ends with `-fwd.hpp`.
 ///
 
 ///
@@ -95,13 +93,11 @@
 /// @dir bsoncxx/v_noabi/bsoncxx/config
 /// Provides headers related to bsoncxx library configuration.
 ///
-/// @par "Generated Headers"
-///
+/// @par Generated Headers
 /// Generated headers are documented by the following pages:
-///
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-config-hpp
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-export-hpp
-/// @li @ref bsoncxx-v_noabi-bsoncxx-config-version-hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-config-hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-export-hpp
+/// - @ref bsoncxx-v_noabi-bsoncxx-config-version-hpp
 ///
 
 #if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
@@ -421,7 +417,8 @@
 /// @namespace bsoncxx::v_noabi::types
 /// @copydoc bsoncxx::types
 ///
-/// @see bsoncxx::v_noabi::types::bson_value
+/// @see
+/// - @ref bsoncxx::v_noabi::types::bson_value
 ///
 
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/oid.hpp

@@ -35,7 +35,8 @@ namespace v_noabi {
 /// @note we use 'oid' to refer to this concrete class. We use 'ObjectId' to refer
 /// to the BSON type.
 ///
-/// @see https://www.mongodb.com/docs/manual/reference/object-id/
+/// @see
+/// - https://www.mongodb.com/docs/manual/reference/object-id/
 ///
 class oid {
    public:

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

@@ -853,8 +853,8 @@ using ::bsoncxx::v_noabi::stdx::optional;
 /// configuration variables and the `BSONCXX_POLY_USE_*` macros provided by @ref
 /// bsoncxx-v_noabi-bsoncxx-config-config-hpp.
 ///
-/// @see [Choosing a C++17
-/// Polyfill](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/polyfill-selection/)
+/// @see
+/// - [Choosing a C++17 Polyfill](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/polyfill-selection/)
 ///
 
 #if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

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

@@ -483,8 +483,8 @@ using ::bsoncxx::v_noabi::stdx::string_view;
 /// configuration variables and the `BSONCXX_POLY_USE_*` macros provided by @ref
 /// bsoncxx-v_noabi-bsoncxx-config-config-hpp.
 ///
-/// @see [Choosing a C++17
-/// Polyfill](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/polyfill-selection/)
+/// @see
+/// - [Choosing a C++17 Polyfill](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/polyfill-selection/)
 ///
 
 #if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/string/to_string.hpp

@@ -31,17 +31,15 @@ namespace string {
 /// This function may be used in place of explicit conversion to `std::string`, which may not be
 /// supported across all polyfill build configurations.
 ///
-/// @par "Example" @parblock
-/// @code{.cpp}
+/// @par Example
+/// ```cpp
 /// std::string example(bsoncxx::v_noabi::stdx::string_view sv) {
 ///   // This may not be supported depending on the polyfill library.
 ///   // return std::string(sv);
 ///
 ///   // This is supported regardless of the polyfill library.
 ///   return bsoncxx::v_noabi::string::to_string(sv);
 /// }
-/// @endcode
-/// @endparblock
 ///
 template <class CharT,
           class Traits = std::char_traits<CharT>,

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/string/view_or_value.hpp

@@ -30,9 +30,8 @@ namespace string {
 ///
 /// Class representing a view-or-value variant type for strings.
 ///
-/// @par "Derived From" @parblock
-/// @li @ref bsoncxx::v_noabi::view_or_value<stdx::string_view, std::string>
-/// @endparblock
+/// @par Derived From
+/// - @ref bsoncxx::v_noabi::view_or_value<stdx::string_view, std::string>
 ///
 /// This class adds several string-specific methods to the bsoncxx::v_noabi::view_or_value template:
 /// - a constructor overload for const char*

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

@@ -325,9 +325,8 @@ using not_view = is_bson_view_compatible<T>;
 ///
 /// Compares a view with a type representable as a view.
 ///
-/// @par "Constraints" @parblock
-/// @li @ref bsoncxx::v_noabi::types::bson_value::view is constructible from `T`.
-/// @endparblock
+/// @par Constraints
+/// - @ref bsoncxx::v_noabi::types::bson_value::view is constructible from `T`.
 ///
 /// @{
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/bulk_write.hpp

@@ -38,8 +38,9 @@ namespace v_noabi {
 /// method. Options that you would typically specify for individual write operations (such as write
 /// concern) are instead specified for the aggregate operation.
 ///
-/// @see https://www.mongodb.com/docs/manual/core/crud/
-/// @see https://www.mongodb.com/docs/manual/core/bulk-write-operations/
+/// @see
+/// - https://www.mongodb.com/docs/manual/core/crud/
+/// - https://www.mongodb.com/docs/manual/core/bulk-write-operations/
 ///
 class bulk_write {
    public:
@@ -96,7 +97,8 @@ class bulk_write {
     ///
     /// @return The optional result of the bulk operation execution, a result::bulk_write.
     ///
-    /// @see https://www.mongodb.com/docs/manual/core/bulk-write-operations/
+    /// @see
+    /// - https://www.mongodb.com/docs/manual/core/bulk-write-operations/
     ///
     MONGOCXX_ABI_EXPORT_CDECL(stdx::optional<result::bulk_write>) execute() const;
 

src/mongocxx/include/mongocxx/v_noabi/mongocxx/change_stream.hpp

@@ -96,7 +96,8 @@ class change_stream {
     /// resume token of the most recently returned document in the stream, or a
     /// postBatchResumeToken if the current batch of documents has been exhausted.
     ///
-    /// @see https://www.mongodb.com/docs/manual/changeStreams/#resume-tokens
+    /// @see
+    /// - https://www.mongodb.com/docs/manual/changeStreams/#resume-tokens
     ///
     /// The returned document::view is valid for the lifetime of the stream and
     /// its data may be updated if the change stream is iterated after this function.