Post History

Source: https://writers.stackexchange.com/a/32758
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

We solved this by adding overview files in Markdown format into the source tree and making one small configuration change.

In Doxyfile, we [set GENERATE\_TREEVIEW to yes](http://www.doxygen.nl/manual/customize.html). This enables the sidebar table of contents, which is needed if you want these overview files to actually show up somewhere. (Normally doxygen just emits code elements -- classes, interfaces, and so on. The treeview gives you a place to put other things.) While you're editing Doxyfile, make sure MARKDOWN\_SUPPORT is set to yes. (I think that's the default.)

We then added one Markdown file (.md extension) to each subdirectory in our source tree. Doxygen supports [all the usual Markdown features](http://www.doxygen.nl/manual/markdown.html). We named each file to match its containing directory. For example, in the "server" directory we named the file server.md.

The usual doxygen treeview has sections for namespaces, classes, files, and perhaps other things. (This might vary by language; ours is C++.) Our additional files show up in a section above these sections, which makes sense -- "classes" is _only_ about the classes, and the package overview that explains how they work together sits above that. We didn't attempt fancier organization, as we needed only a few files at that level.

Original score: 3