Doxygen is a tool for generating documentation from annotated C/C++ sources.

The particular format used by the Doxygen software is based on JavaDoc with some extensions and is supported by other tools as well.

Documenting FreeBSD's source code with Doxygen is not mandatory and is in no way considered a replacement for the official documentation or man pages. This said, having documentation within the code is generally seen as a good practice and will make it easier to produce up-to-date content for other developers.

This is an early attempt on a style guide for doxygen-type documents in a unified way. In general we try to respect style(9), we also avoid annotating non-public functions and structures or adding redundant information.

When documenting C code, we prefer Javadoc style for the comment delimiters:

/**
 * ... text ...
 */

Markup is necessary but can be avoided sometimes. We prefer the JAVADOC_AUTOBRIEF option when documenting a function:

/** Brief description which ends at this dot.
 *
 *  Details follow here.
 */

Avoid the @, prefer \ instead. An example function header would be like this:

/** Retrieve the route number of the current recording device.
 *
 * OSSv4 assigns routing numbers to recording devices, unlike the previous
 * API which relied on a fixed table of device numbers and names.  This
 * function returns the routing number of the device currently selected
 * for recording.
 *
 * For now, this function is kind of a goofy compatibility stub atop the
 * existing sound system.  (For example, in theory, the old sound system
 * allows multiple recording devices to be specified via a bitmask.)
 *
 * \param m	mixer context container thing
 *
 * \retval 0		success
 * \retval EIDRM	no recording device found (generally not possible)
 * \todo Ask about error code
 */
static int
mixer_get_recroute(struct snd_mixer *m, int *route)

When documenting members of a structure we prefer maintaining consistency with the above comments so this format is appropriate:

int var; /**< Detailed description after the member */

More to come …