Skip to content

Conversation

@eramongodb
Copy link
Contributor

@eramongodb eramongodb commented Jan 8, 2025

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:

bsoncxx/
├── doc.hpp (root dir+ns+pages)
├── v_noabi/bsoncxx/
│   ├── fwd.hpp (v_noabi dir+ns)
│   └── ...
└── v1/
    ├── fwd.hpp (v1 dir+ns)
    └── ...

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 dedicated doc.hpp headers under each ABI namespace directory:

bsoncxx/
├── doc.hpp (top-level dir+ns+pages)
├── v_noabi/bsoncxx/
│   ├── doc.hpp (v_noabi dir+ns)
│   ├── fwd.hpp
│   └── ...
└── v1/
    ├── doc.hpp (v1 dir+ns)
    ├── fwd.hpp
    └── ...

However, due to doxygen/doxygen#11261, the bsoncxx/doc.hpp and bsoncxx/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 a docs subdirectory that is entirely separate from the proper installed-and-meant-to-be-used library headers:

bsoncxx/
├── docs
│   ├── top.hpp (top-level dir+ns)
│   ├── topics.hpp (pages)
│   ├── v_noabi.hpp (v_noabi dir+ns)
│   ├── v1.hpp (v1 dir+ns)
│   └── ...
├── v_noabi/bsoncxx/
│   ├── fwd.hpp
│   └── ...
└── v1/
    ├── fwd.hpp
    └── ...

This permitted a natural regrouping of Doxygen topic pages (not related to directories or namespaces) into its own topics.hpp header such that the top.hpp and v*.hpp headers have better symmetry of their contents.

The new File List page looks as follows in generated HTML:

image

@eramongodb eramongodb requested a review from kevinAlbs January 8, 2025 20:26
@eramongodb eramongodb self-assigned this Jan 8, 2025
@eramongodb eramongodb merged commit 1457c1d into mongodb:master Jan 9, 2025
15 of 17 checks passed
@eramongodb eramongodb deleted the cxx-docs branch January 9, 2025 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants