CXX-3069 document directories, namespaces, and generated headers

[eramongodb]

Summary

Partially resolves CXX-3069. Followup to #1170.

Adds Doxygen documentation for directories, namespaces, and generated headers. Docs for files and root namespace redeclarations are deferred to a followup PR.

This PR proposes organizing Doxygen documentation at the bottom of header files in the following order:

// License notice.

#pragma once

#include <headers> // Include directives and etc.

namespace bsoncxx { ... } // Declarations and definitions.

///
/// @file
/// Documentation for this file.
///

///
/// @dir path/to/dir
/// Documentation for relevant subdirectories.
///

///
/// @namespace ns::qualifier
/// Documentation for relevant namespaces.
///

This is to avoid their interference with general development workflows, as these particular sets of documentation is not expected to be changed often.

Directories

This PR adds documentation of directories, which partially enables navigation via intermediate directories and the "File List" page.

More importantly, it triggers population of directory pages with subdirectory and file information (file docs are deferred to a followup PR).

Directories defer documentation to namespaces whenever able to avoid redundancy by referencing the namespace in its brief, since the directory structure mirrors the namespace structure.

To avoid ambiguity regarding which header within subdirectory to place directory documentation, all directory docs are collectively placed in the ABI directory's fwd.hpp file (with the exception of the library root directory itself).

Note: sometimes paths must be fully qualified relative to the project root directory or the library root directory for proper disambiguation by Doxygen, but this usually isn't necessary.

Namespaces

This PR adds documentation of namespaces (including root namespaces; redeclaration docs are deferred to a followup PR), which enables navigation via intermediate namespaces.

This triggers population of namespace pages with nested namespaces.

Similar to namespaces, all namespace docs are collectively placed in the ABI directory's fwd.hpp file to avoid placement ambiguity.

Currently, due to having a 1-to-1 relationship, v_noabi namespace docs reuse root namespace docs via @copydoc. This may no longer be possible if namespace restructuring occurs in the future, but this is expected to be a far-future concern.

Config Headers

This PR also adds documentation for generated headers under config/ (i.e. config.hpp) in the form of Doxygen modules (aka "named groups"). This PR also documents headers already visible under the config/ directory (i.e. prelude.hpp) for completeness.

This means macros such as BSONCXX_POLY_USE_* and BSONCXX_VERSION_* are finally documented proper by the API doc pages! 🎉

Headers which are not intended for use by consumers of the library are labeled with a @warning For internal use only!. Docs for such files are intentionally kept brief and sparse in detail to avoid encouraging users to use the provided entities despite the warning.

Due to generated headers "not existing" according to Doxygen due to docs being generated from files under include/ only, their docs are defined in the ABI directory's fwd.hpp file alongside directory and namespace docs within a #if defined(BSONCXX_PRIVATE_DOXYGEN_PREPROCESSOR) block defining stubs for entities (primarily macros) provided by the relevant header files.

This has the effect of listing the generated header docs both in the fwd.hpp file page (where it is document) as well as the dedicated Module page (corresponding to the generated header). Some care and emphasis was required to make clear what file actually provides the documented entities.

Transitive Includes

The prelude.hpp and fwd.hpp headers demonstrates how supported transitive includes are intended to be explicitly documented following SHOW_INCLUDE_FILES = NO in #1166.

This is implemented using a @par command with a paragraph title and a @li list. The @parblock is not strictly necessary but is included regardless to clearly denote the expected scope of the page element (e.g. such that it does not unintentionally apply to subsequent paragraphs).

This pattern is expected to be used sparingly and only for header files where the transitive includes are clearly expected and deliberately supported (e.g. view_or_value.hpp transitively includes the corresponding view.hpp and value.hpp headers).

[kevinAlbs]

LGTM with one question.

[kevinAlbs]

Remove BSONCXX_STATIC? The rendered documentation notes "These macros are provided by export.hpp". But BSONCXX_STATIC is applied on the CMake target, rather than defined in export.hpp.

Similar question applies to MONGOCXX_STATIC.

[eramongodb]

Good point. Removed as suggested.