CXX-3064 Fix use of Doxygen @relates, @relatesalso, and groups (#1170)

* doxygen: strip include directory from file paths

* clang-format: avoid breaking long single-line Doxygen commands

* doxygen: expand *_INLINE as inline

* docs: add missing @internal command

* docs: fix broken @copydoc in bucket.hpp

* docs: fix URLs to Working with BSON doc page

* doxygen: set SORT_* = YES

* doxygen: add BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR

* CXX-2288 add library root-level forward headers

* CXX-3064 fix @relates and groupings

* Relocate root-level documentation into root forward headers

* Remove order-dependent language from docs

Author: eramongodb

.clang-format

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

Doxyfile

@@ -160,7 +160,8 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = src/bsoncxx/include \
+                         src/mongocxx/include
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -638,7 +639,7 @@ SORT_MEMBER_DOCS       = YES
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
@@ -650,14 +651,14 @@ SORT_BRIEF_DOCS        = NO
 # detailed member documentation.
 # The default value is: NO.
 
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
 
 # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
 # of group names into alphabetical order. If set to NO the group names will
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -667,7 +668,7 @@ SORT_GROUP_NAMES       = NO
 # list.
 # The default value is: NO.
 
-SORT_BY_SCOPE_NAME     = NO
+SORT_BY_SCOPE_NAME     = YES
 
 # If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper
 # type resolution of all parameters of a function it will reject a match between
@@ -2212,11 +2213,13 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = BSONCXX_API= \
                          BSONCXX_CALL= \
                          BSONCXX_DEPRECATED \
-                         BSONCXX_INLINE= \
+                         BSONCXX_INLINE=inline \
+                         BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR= \
                          MONGOCXX_API= \
                          MONGOCXX_CALL= \
-                         MONGOCXX_DEPRECATED \
-                         MONGOCXX_INLINE=
+                         MONGOCXX_DEPRECATED= \
+                         MONGOCXX_INLINE=inline \
+                         MONGOCXX_PRIVATE_DOXYGEN_PREPROCESSOR=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

src/bsoncxx/include/bsoncxx/fwd.hpp

@@ -0,0 +1,22 @@
+// Copyright 2009-present MongoDB, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#if !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+#error "This file is for documentation purposes only. It should not be included."
+#endif  // !defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)
+
+///
+/// @namespace bsoncxx
+/// The top-level namespace for bsoncxx library entities.
+///

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

@@ -88,33 +88,25 @@ class element : private document::element {
     BSONCXX_PRIVATE explicit element(const stdx::string_view key);
 };
 
-///
-/// @{
 ///
 /// Convenience methods to compare for equality against a bson_value.
 ///
-/// Returns true if this element contains a bson_value that matches.
-///
-/// @relates element
+/// Compares equal if this element contains a matching bson_value. Otherwise, compares unequal.
 ///
+/// @{
+
+/// @relatesalso bsoncxx::v_noabi::array::element
 BSONCXX_API bool BSONCXX_CALL operator==(const element& elem, const types::bson_value::view& v);
+
+/// @relatesalso bsoncxx::v_noabi::array::element
 BSONCXX_API bool BSONCXX_CALL operator==(const types::bson_value::view& v, const element& elem);
-///
-/// @}
-///
 
-///
-/// @{
-///
-/// Convenience methods to compare for equality against a bson_value.
-///
-/// Returns false if this element contains a bson_value that matches.
-///
-/// @relates element
-///
+/// @relatesalso bsoncxx::v_noabi::array::element
 BSONCXX_API bool BSONCXX_CALL operator!=(const element& elem, const types::bson_value::view& v);
+
+/// @relatesalso bsoncxx::v_noabi::array::element
 BSONCXX_API bool BSONCXX_CALL operator!=(const types::bson_value::view& v, const element& elem);
-///
+
 /// @}
 ///
 

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/view.hpp

@@ -130,15 +130,13 @@ class view {
     operator document::view() const;
 
     ///
-    /// @{
+    /// @relates bsoncx::v_noabi::document::view
     ///
     /// Compare two views for (in)-equality
     ///
-    /// @relates view
-    ///
+    /// @{
     friend BSONCXX_API bool BSONCXX_CALL operator==(view, view);
     friend BSONCXX_API bool BSONCXX_CALL operator!=(view, view);
-    ///
     /// @}
     ///
 
@@ -173,15 +171,13 @@ class view::const_iterator {
     const_iterator operator++(int);
 
     ///
-    /// @{
-    ///
-    /// Compare two const_iterators for (in)-equality
+    /// @relates bsoncxx::v_noabi::array::view::const_iterator
     ///
-    /// @relates view::const_iterator
+    /// Compare two const_iterators for (in)-equality.
     ///
+    /// @{
     friend BSONCXX_API bool BSONCXX_CALL operator==(const const_iterator&, const const_iterator&);
     friend BSONCXX_API bool BSONCXX_CALL operator!=(const const_iterator&, const const_iterator&);
-    ///
     /// @}
     ///
 

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

@@ -25,7 +25,10 @@ namespace bsoncxx {
 namespace v_noabi {
 namespace array {
 
-using view_or_value = ::bsoncxx::v_noabi::view_or_value<view, value>;
+///
+/// Equivalent to `v_noabi::view_or_value<v_noabi::array::view, v_noabi::array::value>`.
+///
+using view_or_value = v_noabi::view_or_value<view, value>;
 
 }  // namespace array
 }  // namespace v_noabi

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

@@ -82,32 +82,30 @@ struct concatenate_array {
 };
 
 ///
-/// Helper method to concatenate a document. Use this with the document stream
-/// builder to merge an existing document's fields with a new document's.
+/// Helper method to concatenate a document.
 ///
-/// @param doc A document to be concatenated.
+/// Use this with the document stream builder to merge an existing document's fields with a new
+/// document's.
+///
+/// @param doc The document to concatenate.
 ///
 /// @return concatenate_doc A concatenating struct.
 ///
-/// @relatesalso concatenate_doc
+/// @see bsoncxx::v_noabi::builder::concatenate_doc
+///
+/// @note An overload accepting @ref v_noabi::array::view_or_value and returning a @ref
+/// concatenate_array is also declared in this scope.
 ///
 BSONCXX_INLINE concatenate_doc concatenate(document::view_or_value doc) {
     return {std::move(doc)};
 }
 
-///
-/// Method to concatenate an array with a new array. Use this with the array stream
-/// builder to merge an existing array's fields with a new array.
-///
-/// @param array An array to be concatenated.
-///
-/// @return concatenate_array A concatenating struct.
-///
-/// @relatesalso concatenate_array
-///
+// Why is Doxygen unable to parse this overload correctly???
+// @cond DOXYGEN_DISABLE "warning: no matching file member found for ..."
 BSONCXX_INLINE concatenate_array concatenate(array::view_or_value array) {
     return {std::move(array)};
 }
+// @endcond
 
 }  // namespace builder
 }  // namespace v_noabi

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

@@ -32,12 +32,12 @@ namespace builder {
 namespace stream {
 
 ///
-/// A streaming interface for constructing
-/// a BSON array.
+/// A streaming interface for constructing a BSON array.
 ///
-/// @note Use of the stream builder is discouraged. See
-/// https://www.mongodb.com/docs/languages/cpp/drivers/current/working-with-bson/#basic-builder for
-/// more details.
+/// @warning Use of the stream builder is discouraged. See
+/// [Working with
+/// BSON](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/working-with-bson/#basic-builder)
+/// for more details.
 ///
 class array : public array_context<> {
    public:

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

@@ -167,7 +167,7 @@ class array_context {
     ///
     /// Conversion operator for single_context.
     ///
-    /// @relatesalso single_context
+    /// @see bsoncxx::v_noabi::builder::stream::single_context
     ///
     BSONCXX_INLINE operator single_context();
 

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

@@ -30,12 +30,12 @@ namespace builder {
 namespace stream {
 
 ///
-/// A streaming interface for constructing
-/// a BSON document.
+/// A streaming interface for constructing a BSON document.
 ///
-/// @note Use of the stream builder is discouraged. See
-/// https://www.mongodb.com/docs/languages/cpp/drivers/current/working-with-bson/#basic-builder for
-/// more details.
+/// @warning Use of the stream builder is discouraged. See
+/// [Working with
+/// BSON](https://www.mongodb.com/docs/languages/cpp/cpp-driver/current/working-with-bson/#basic-builder)
+/// for more details.
 ///
 class document : public key_context<> {
    public:

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

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

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

@@ -120,21 +120,3 @@
 // CXX-2769: out-of-place, but remains for backward compatibility.
 #pragma push_macro("BSONCXX_ENUM")
 #undef BSONCXX_ENUM
-
-// Doxygen does not account for generated header files.
-// Document globally applicable macros and namespaces here.
-
-///
-/// @namespace bsoncxx
-/// The top-level namespace for bsoncxx library entities.
-///
-
-///
-/// @namespace bsoncxx::v_noabi
-/// Entities declared in this namespace do not have a stable ABI.
-///
-
-///
-/// @namespace bsoncxx::v_noabi::stdx
-/// Declares polyfills for C++17 forward compatibility.
-///

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

@@ -7,6 +7,7 @@
 #define BSONCXX_STRINGIFY_IMPL(...) #__VA_ARGS__
 
 /**
+ * @internal
  * @brief Token-paste two macro arguments, after macro expansion
  */
 #define BSONCXX_CONCAT(A, ...) BSONCXX_CONCAT_IMPL(A, __VA_ARGS__)

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/decimal128.hpp

@@ -65,15 +65,13 @@ class decimal128 {
     std::string to_string() const;
 
     ///
-    /// @{
+    /// @relates bsoncxx::v_noabi::decimal128
     ///
     /// Relational operators for decimal128
     ///
-    /// @relates decimal128
-    ///
+    /// @{
     friend BSONCXX_API bool BSONCXX_CALL operator==(const decimal128& lhs, const decimal128& rhs);
     friend BSONCXX_API bool BSONCXX_CALL operator!=(const decimal128& lhs, const decimal128& rhs);
-    ///
     /// @}
     ///
 

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

@@ -40,7 +40,7 @@ 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.
 ///
-/// @relatesalso array::element
+/// @see bsoncxx::v_noabi::array::element
 ///
 class element {
    public:
@@ -386,33 +386,25 @@ class element {
     stdx::optional<stdx::string_view> _key;
 };
 
-///
-/// @{
 ///
 /// Convenience methods to compare for equality against a bson_value.
 ///
-/// Returns true if this element contains a bson_value that matches.
-///
-/// @relates element
+/// Compares equal if the element contains a matching bson_value. Otherwise, compares unequal.
 ///
+/// @{
+
+/// @relatesalso bsoncxx::v_noabi::document::element
 BSONCXX_API bool BSONCXX_CALL operator==(const element& elem, const types::bson_value::view& v);
+
+/// @relatesalso bsoncxx::v_noabi::document::element
 BSONCXX_API bool BSONCXX_CALL operator==(const types::bson_value::view& v, const element& elem);
-///
-/// @}
-///
 
-///
-/// @{
-///
-/// Convenience methods to compare for equality against a bson_value.
-///
-/// Returns false if this element contains a bson_value that matches.
-///
-/// @relates element
-///
+/// @relatesalso bsoncxx::v_noabi::document::element
 BSONCXX_API bool BSONCXX_CALL operator!=(const element& elem, const types::bson_value::view& v);
+
+/// @relatesalso bsoncxx::v_noabi::document::element
 BSONCXX_API bool BSONCXX_CALL operator!=(const types::bson_value::view& v, const element& elem);
-///
+
 /// @}
 ///