CXX-3083 Reorganize layout of Doxygen API page content

[eramongodb]

Summary

Resolves CXX-3083.

Applies some site-wide cleanup and adjustements to the generated API doc pages.

Removed Todo, Test, Bug, and Examples Lists

These lists have been disabled or hidden due to lack of utility:

• The Todo List is better tracked by JIRA tickets (e.g. CXX-2038).
• The Test List is completely unused.
• The Bug List is completely unused (and better tracked by JIRA tickets).
• The Examples List will be replaced with a better approach in CXX-3082.

There was only a single use of the @todo command in uri.hpp. This command was removed due to being noise for those reading the API documentation (TODO is for maintainers, not users).

There was only a single use of the @examples in client_session.cpp. This command was removed in favor of using a better approach in CXX-3082.

DoxygenLayout.xml

This file is used to control the layout of content across all API doc pages. This PR adds this file (which is always implicitly used by Doxygen) to the repository to support subsequent modifications to the layout of API page content.

Note

Doxygen doesn't support a convenient update command like doxygen -u Doxyfile for the layout file. Updating the Doxygen version will likely require manually translating the old settings into the new layout file.

This PR proposes two major changes to the layout of API page contents.

Navigation Tabs

Before:

After:

The Files / Namespaces / Classes dropdown menus have been moved to the front of the list, as they are expected to be used the most often. The ordering is roughly from greater-to-lesser scope (files contain namespaces, namespaces contain classes).

The "Modules" tab is renamed to "Groups" to better describe its actual purpose (documenting a named group of related entities via the @defgroup/@ingroup/etc. commands). Named groups are currently only used to document generated header files. This is unlikely to change in the near future; for most cases, a Topic page will likely be more suitable than a named group.

The "Modules" tab is renamed to "Topics" to better describe its actual purpose (documenting topics related to the API via the @page command). Currently, following the removal of the Todo List, only the auto-generated Deprecated List is present. In the near future, more topics pages are expected to be introduced (e.g. API and ABI stability, polyfill library configuration, comprehensive examples, etc.).

Page Description Order

Before:

After:

The "Detailed Description" is moved up to the top of the page, replacing the "Brief Description" on all pages and titled simply "Description".

The repetition of the brief description, once at the top of the page, then once more somewhere below in the middle of the page (surrounded by interface documentation) is noisy. Furthermore, the proper general description of the directory/file/namespace/class being documented is arguably much more important to see first than the summary (or details) of the provided interfaces. Therefore, the detailed description is now the first content a user will see on all pages. As seen in the image above, this also has immediate benefits w.r.t. visibility of usage examples (related to CXX-3082).

For (rough) symmetry with file pages, which contain a "Go to the source code of this file." link immediately following their description, this PR moves up the "usedfiles" element to come immediately after the detailed description in class pages for easier back-navigation from the class page to the parent file.

Navigation Tree Expansion

This PR also sets HTML_INDEX_NUM_ENTRIES = 0 which has the effect of fully expanding trees indexes by default. Collapsing irrelevant entries is considered preferable to having to expand relevant entries + having all entries expanded from the start better supports Ctrl+F navigation workflows.

A method to conveniently group ABI namespaces and directories at the top of their respective tree levels (instead of mixed within root namespace entries) is being investigated.