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: