Doxygen [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
**//This is EARLY WIP - do not complain .. yet//** 

===== What is this Doxygen thing =====

[[http://www.stack.nl/~dimitri/doxygen/|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:

<code>
/**
 * ... text ...
 */
</code>

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

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

Doxygen accepts either //@// or //\// for tagging. Headerdoc only accepts //@// so we should use it for portability.
An example function header would be like this:

<code>
/**
 * 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)
</code>

==== 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:

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

//More to come ...//