CXX-3085 Upgrade to Doxygen 1.11.0

[eramongodb]

Summary

Resolves CXX-3085.

This PR upgrades the Doxygen version used to generate the latest API doc to the latest release: 1.11.0.

Description

Doxygen 1.9.1 (which is the latest Doxygen version used to generate API docs following #1174) was released in August 2021. Numerous bugfixes, improvements, and new features have been implemented since. This PR proposes upgrading to the current latest version, Doxygen 1.11.0, which was released on May 2024.

This upgrade from 1.9.1 to 1.11.0 includes the following notable changes (among many others):

• added support for @code{.<language>} for syntax highlighting.
• added WARN_IF_INCOMPLETE_DOC for incomplete function parameter documentation.
• added -q command line flag for quieter output (warnings/errors only).
• added support for <details> HTML tag (collapsible sections).
• fixed @copydoc handling of brief descriptions (e.g. mongocxx::v_noabi::gridfs::bucket::download_to_stream is missing the brief description).
• fixed Doxygen confusion of inline function overloads and associated documentation (e.g. bsoncxx::v_noabi::builder::concatenate could not be documented properly).
• added support for a dark theme (disabled for now).
• added WARN_IF_UNDOC_ENUM_VAL to detect undocumented enum values (disabled for now).
• added interactive code folding in HTML output.
• added page and group titles to search results.
• added a "copy to clipboard" button for code blocks.
• improved rendering of alerts (note, warning, etc.).
• added support for GitHub Markdown style alerts (note, warning, etc.).

The workarounds applied in #1170 to overloads such as bsoncxx::v_noabi::builder::concatenate are no longer necessary thanks to a bugfix in 1.9.3(?). This PR removes the workarounds and adds proper documentation for the array overloads.

Doxyfile

The Doxyfile was updated using doxygen -u, which performs an inplace update to the file.

Notable changes include:

• MARKDOWN_ID_STYLE: allow referencing Markdown headings using GitHub style identifiers (enabled).
• SHOW_HEADERFILE: distinct option from SHOW_INCLUDES specifically displaying the header file providing the documented class (enabled).
• WARN_IF_INCOMPLETE_DOC: warnings for incomplete parameter docs (all or none; enabled).
• WARN_IF_UNDOC_ENUM_VAL: warnings for undocumented enumerators (disabled).
• HTML_CODE_FOLDING: support expanding or collapsing code blocks (enabled).
• HTML_COPY_CLIPBOARD: support a convenient copy-to-clipboard button for code blocks (enabled).

The WARN_IF_UNDOC_ENUM_VAL will be enabled once all enumerators have been properly documented (outside scope of this PR). Many are currently undocumented, thus producing a lot of warnings.

DoxygenLayout.xml

The layout file was updating using doxygen -u -l docs/DoxygenLayout.xml and manually copying over the prior settings from the backup file into the new file. Confusingly, the "modules" type, which used to refer to the nagivation tab for named Doxygen groups, is repurposed for C++20 Modules documentation. The old "named Doxygen groups" navigation tab is now indicated by the "topics" type.

doc.hpp

The addition of SHOW_HEADERFILE motivated a revisit of the <includes> tag for class doc pages, which was disabled in #1183 to avoid documenting transitive #include directives we are not committed to supporting.

This section used to look like this (e.g. for 3.10.2):

#1183 proposed the following (in an effort to capture the actual path to the header):

This PR proposes this improvement:

The "SHOW_USED_FILES" section is moved back to its original position at the bottom of the page.

The improvement from a mere <view.hpp> to <bsoncxx/v_noabi/bsoncxx/document/view.hpp> is permitted by the STRIP_FROM_INC_PATH option. However, updating this option emitted the following unresolvable (false positive?) warnings for the root fwd.hpp header files:

warning: the name 'src/bsoncxx/include/bsoncxx/fwd.hpp' supplied as the argument in the \file statement matches the following input files:
  src/bsoncxx/include/bsoncxx/fwd.hpp
Please use a more specific name by including a (larger) part of the path!
warning: the name 'src/mongocxx/include/mongocxx/fwd.hpp' supplied as the argument in the \file statement matches the following input files:
  src/mongocxx/include/mongocxx/fwd.hpp
Please use a more specific name by including a (larger) part of the path!

To avoid further fwd.hpp header confusion, this PR proposes renaming the header to doc.hpp, which better reflects its intended purpose and avoids the warnings above. The header is now explicitly excluded from the install() command. Its documention is accordingly simplified to simply "not includable".

[eramongodb]

A summery / set of examples of other observable changes to appearance and/or functionality relative to the base commit for this PR (Doxygen 1.9.1 vs. Doxygen 1.11.0 with config and layout updates) that were not already shown above.

Images are ordered as old vs. new.

"Sticky" Navigation Bar

The navigation bar remains visible when scrolling down the page.

Tree Icons

Cleaner icons for directories and files.

Directory and File Icons

The cleaner icons are also used in directory and file pages.

Group/Topic Content in Search Results

The title and headers of group/topic pages are now displayed in search results.

Rendering of Admonitions

Notes, Warnings, and similar "admonitions" or "alerts" are now much more visible.

Function Declaration Formatting

Better handling of formatting of multi-line function declarations.

[rcsanchez97]

LGTM

[kevinAlbs]

LGTM. The improvements are much appreciated. I very much like the sticky navigation bar.

Aside: Doxygen 1.12.0 was notably released. At a glance, I do not see anything in the release notes immediately helpful.