On 24/06/11 10:53, Alan DeKok wrote:
What do we think about the various API doc tool e.g. Doxygen? It might make navigating the source easier for people unfamiliar with it.
That would be wonderful.
What do people think of this: http://philmayers.github.com/freeradius-server/doxygen/html/ Doxygen source and some files modified with the comment metadata are in this github branch: https://github.com/philmayers/freeradius-server/tree/doxygen Comments welcome. It's very much a proof-of-concept. If people are interested, I used the "libnl" source base as the idea to aim for: http://www.infradead.org/~tgr/libnl/doc-git/api/index.html The libnl source tarball has some neat examples of Doxygen tricks and stuff. tl;dr version of Doxygen: 1. Start each file as follows: /** * @file name.c * @brief One sentence description */ 2. Prefix functions with: /** * @brief does some magic * * This will be turned into a link: process() * This will be a list: * - One * - Two * * @param word the magic word * @return 0 on success, -1 on failure */ int magic(char *word) { } 3. Use a fake meta-source file to build table-of-contents (see doc/source/extra/toc.c)