• Doxygen

This is EARLY WIP - do not complain .. yet

What is this Doxygen thing

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 like !Apple's headerdoc.

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.

How to generate output

PreReq

Install doxygen.

If you are OK to generate in the src tree

cd <SRC>/tools/kerneldoc/subsys

and then either "make all" (this may fail in case of issues in some places and block the generation of "the rest") or if you do not want to have one issue fail all the rest:

for target in $(ls -1 Doxy* | cut -d - -f 2); do

• nice make $target >/dev/null 2>&1

done

If you want to generate outside the src tree

DOXYGEN_DEST_PATH=/path/with/write/access

export DOXYGEN_DEST_PATH

cd ~/source_for_dox/head

SOURCE_LOCATION=$(pwd)/sys

svn update >/dev/null 2>&1

cd tools/kerneldoc/subsys

S=${SOURCE_LOCATION}

export S

DOXYGEN_DEST_PATH= /usr/bin/make clean >/dev/null 2>&1

# decide here what you want to generate, to generate all without issues of one subsys blocking all the rest

for target in $(ls -1 Doxy* | cut -d - -f 2); do

• nice make $target >/dev/null 2>&1

done

Markup Guidelines

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.

C Functions

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

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

Markup is necessary but can be avoided sometimes. We can use doxygen's JAVADOC_AUTOBRIEF option when documenting a function:

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

Doxygen accepts either @ or \ for tagging. Headerdoc only accepts @ so we should use it for portability. 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)

C structs

In general, documenting the main functions is key but you also want to document important headers and structures.

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 ...