Skip to content

Move Doxygen dir+ns+pages documentation into docs subdirectory #1316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jan 9, 2025

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