The [[ https://phabricator.wikimedia.org/diffusion/MW/browse/master/docs/ | docs ]] directory in core contains various documentation files, e.g. [[ https://phabricator.wikimedia.org/diffusion/MW/browse/master/docs/design.txt | design.txt ]]. doxgen turns this into [[ https://doc.wikimedia.org/mediawiki-core/master/php/design_8txt.html | garbled nonsense ]] in our generated doc at doc.wikimedia.org ☹.
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}).
# Prepend `/*` and add doxygen [[https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock | structural commands ]], as [[ https://phabricator.wikimedia.org/diffusion/MW/browse/master/includes/filebackend/README | includes/filebackend/README ]] does, so that it looks good in doxygen (but note {T87796}).
# 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}) puts it on mw.org, c.f. how [[ https://phabricator.wikimedia.org/diffusion/EWBA/browse/master/docs/lua.wiki | 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` ([[ https://github.com/wikimedia/mediawiki-extensions-MobileFrontend/blob/master/tests/browser/README.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}.