pair* APIs

[Phil Mayers]

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)