Move Doxygen dir+ns+pages documentation into docs subdirectory #1316
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
In preparation for the addition of v1 interfaces and corresponding documentation, this PR proposes moving Doxygen documentation for directories, namespaces, and toipc pages under a dedicated
docs
subdirectory.The original design proposed by #1185 expected the following structure:
On further consideration, using
fwd.hpp
(aggregate of forward headers for use by users) felt inappropriate as the header to contain Doxygen documentation (solely for documentation purposes). This naturally led to an attempt to introduce dedicateddoc.hpp
headers under each ABI namespace directory:However, due to doxygen/doxygen#11261, the
bsoncxx/doc.hpp
andbsoncxx/v_noabi/bsoncxx/doc.hpp
headers are considered ambiguous. This motivated the structure proposed by this PR that collects all Doxygen dir+ns+pages documentation under adocs
subdirectory that is entirely separate from the proper installed-and-meant-to-be-used library headers:This permitted a natural regrouping of Doxygen topic pages (not related to directories or namespaces) into its own
topics.hpp
header such that thetop.hpp
andv*.hpp
headers have better symmetry of their contents.The new File List page looks as follows in generated HTML: