• I’m a bit confused that we have 3 ways of documenting this. • In particular, I want to document a somewhat complicated API - that to be used correctly - one needs to apply changes at multiple places. • This means that the example is like 80 lines. • In the past, I would have just made an rst file in the docs directory, but those tend to get out of sync from the code. • Given that the example would use multiple functions, etc. • I want to keep it in-sync with those.
Article Summaries:
- A discussion on the LLVM project highlights ongoing uncertainty over the preferred documentation format. While Doxygen remains the go‑to for API examples that must stay in sync with code, the community has increasingly adopted Markdown for short, maintainers‑style files, following recent conversions such as the release notes. RST is still required for long‑form documentation in the docs directory, and no formal RFC has been accepted to replace it globally. The debate underscores a lack of a unified policy, with format choice largely driven by file type, contributor preference, and rendering needs on GitHub.
Sources: