There are several ways to make a documentation file in git more useful than simply a file you view in your code editor:
- Fix doxygen so it doesn't treat foo.txt as C++ and garble it (possibly the same as T106116: The Doxygen version in CI parses README files as garbled C.).
- Prepend /* and add doxygen structural commands, as includes/filebackend/README does, so that it looks good in doxygen (but note T87796: Add includes/filebackend/README as generated documentation page).
- Rename it design.md and use markdown formatting (and light doxygen structural commands) so it looks good in doxygen.
- Rename it design.mediawiki and a person (and eventually T91626: Technology to transclude git content into wiki pages) puts it on mw.org, c.f. how wikibase/docs/lua.wiki in git is copied to https://www.mediawiki.org/wiki/Extension:Wikibase_Client/Lua .
- doxygen doesn't support wiki syntax.
- but github supports some mediawiki syntax when rendering a file with extension .mediawiki (sample).
- Krinkle on IRC: I think we should consider seeking alternatives to Doxygen.
Note: Any bikeshedding here to settle on approaches should never block improving documentation in git, such as T111283: Replace docs/design.txt with a reasonably complete summary of how MW works.