CXX-3064 Fix use of Doxygen @relates, @relatesalso, and groups

[eramongodb]

Summary

Resolves CXX-3064. Related to CXX-2827.

This PR is a parallel companion to #1169. Whereas #1169 focuses on the deployment process and tooling, this PR focuses on various fixes and improvements to the contents of the current API docs itself.

The "Incompleteness" Problem

The Doxyfile sets EXTRACT_ALL = NO. This enables warnings for undocumented entities. However, this also means directories and namespaces MUST be explicitly documented in order to properly generate their corresponding pages. This is the reason behind so many pages for directories and namespaces being completely devoid of useful information or missing a navigatable page entirely.

For example, this is the page for the bsoncxx/v_noabi/bsoncxx directory (note: subdirectory information is completely absent despite having pages):

Undocumented headers do not generate a page at all (hence their absence in directory pages as above):

Undocumented namespaces similarly do not generate a page at all:

This means the "array" in "bsoncxx > v_noabi > array > element" is not navigatable/interactable (among many similar cases of "dead" links):

These factors all contribute to a feeling of "incompleteness" in the quality of the API docs.

This PR lays the foundations to address all of the issues described above. However, the addition of documentation of directories, namespaces, and files are deferred to a followup PR due to the volume of changes required.

A preview of upcoming changes:

Root Level Forward Headers

This PR adds a bsoncxx/fwd.hpp and mongocxx/fwd.hpp at the library root level, not to be confused with bsoncxx/v_noabi/bsoncxx/fwd.hpp and mongocxx/v_noabi/mongocxx/fwd.hpp added by #1061. These headers are NOT expected to be included or even includeable (<bsoncxx/v_noabi/bsoncxx> is prioritized before <bsoncxx> by include directory search paths, so these new fwd.hpp headers will never be found). Nevertheless, just in case, they are defined to behave equivalently to their v_noabi counterparts should they be included anyways.

These headers may be renamed to something else if fwd.hpp is confusing for their purpose.

The purpose of these headers is to provide a definitive location to add Doxygen documentation for root-level directories and namespaces.

src/bsoncxx/include/ # Similarly for mongocxx.
└── bsoncxx/
    ├── fwd.hpp      # Documents bsoncxx/ and bsoncxx::.
    ├── v_noabi/bsoncxx/
    │   ├── fwd.hpp  # Documents bsoncxx/v_noabi and bsoncxx::v_noabi.
    │   └── ...
    └── v1/          # CXX-2745
        ├── fwd.hpp  # Documents bsoncxx/v1 and bsoncxx::v1.
        └── ...

#1039 (comment) added some of these docs to the prelude.hpp headers, as forward headers were not yet implemented at the time. These are relocated to their corresponding forward headers.

The addition of documentation of directories, namespaces, and files are deferred to a followup PR due to the volume of changes required.

Sorted Documentation

This PR proposes setting various SORT_* options to YES. This is primarily to automate the (alphabetical) grouping of related functions without requiring use of Doxygen groups. This will secondarily discourage writing documentation sensitive to in-source-declaration-order (e.g. "see above/below") allowing for greater freedom of in-source ordering without impacting API documentation results.

@relates, @relatesalso, and Groups

After much pain and debugging, some rules were derived:

1. @relatesalso is not equivalent to @see.
2. @relatesalso is not inherited by group members (@relates is).
3. Member group comments should not be their own doc comment block.
4. Documentation distributed to group members generally comes before the @{, not after, except when DISTRIBUTE_GROUP_DOC applies instead (reuse doc of first group member for the rest).

This PR addresses all known violations of these rules by applying the following patterns (and generally avoiding use of groups when able):

class example {
public:
  ///
  /// @relates example <!-- Inherited by group members. -->
  ///
  /// Common documentation for group members.
  ///
  /// @{ <!-- Asymmetric block for group marker. -->

  friend void group_member(int i);
  friend void group_member(double d);

  /// @} <!-- Asymmetric block for group marker. -->
  ///

  void unrelated(); // Asymmetry of the group marker comments avoid
                    // leaking the group documentation into the
                    // next entity when used in class definition scope.
};

///
/// Common documentation for group members.
///
/// @{

/// @relatesalso example <!-- Per group member. -->
inline void group_member(example e, int i);

/// @relatesalso example <!-- Per group member. -->
inline void group_member(example e, double d);

/// @} <!-- Asymmetric block for group marker. -->
///

It is important to use @relatesalso for non-member functions (especially operators) to ensure their declaration is included in the documentation of the enclosing namespace. Otherwise, they are only documented in the related class page. This is especially important for correctly documenting root namespace redeclarations in CXX-2745.

Use of per-member documentation should be avoided whenever possible to avoid the complexities of merging group-and-member documentations (@param commands in particular are a problem). Copying relevant documentation per member (e.g. mongocxx::v_noabi::hint::operator== overloads) is preferable to twisting contents to accomodate all group members.

BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR

This (and its mongocxx counterpart) are added to facilitate workarounds for the very unfortunate Doxygen using-declaration problem described in #1066. These workarounds will come in a followup PR, but as a preview of their intended usage:

namespace bsoncxx {
namespace array {

#if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

/// @ref v_noabi::array::element
class element {};

#else

using v_noabi::array::element;

#endif // defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR)

} // namespace array
} // namespace bsoncxx

A preview of the results:

This will be discussed in greater detail in the relevant followup PR.

STRIP_FROM_PATH = ON

Old:

New:

Miscellaneous

• Set BSONCXX_INLINE=inline (+ mongocxx) to correctly communicate inline functions to Doxygen.
• Added ClangFormat CommentPragmas to avoid breaking long Doxygen commands by wrapping (e.g. @copydoc).
• Added a missing @internal in util.hpp.
• Fixed links to Working with BSON.

[kevinAlbs]

The documentation improvements are greatly appreciated.

[kevinAlbs]

LGTM with one additional comment.