Structure Documentation

Structures, or structs for short, require very little documentation. Structs must be documented wherever they are defined. Basically, structs only require a brief description detailing why they are needed. Each variable that composes a struct must be commented. A fully simplified syntax is therefore appropriate.

Note

Follow the same rules as struct when documenting an enum. Use the simplified syntax to add the brief description.

Structure Comments Template

Structs only have a simplified template:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
/** @brief Brief description of struct pre.
 *
 * Detailed description of struct pre. Optional
 * */
struct pre {
	/** Variable g brief description. */
	int g;

	/** Variable h brief description. */
	int h;
};

Doxygen does not require any commands to recognize the different comments. It does, however, require that line 8 be left blank.

Structure Documentation Example

Correct:

1
2
3
4
5
6
7
8
9
static int initIRQ
	(
	struct isrInitInfo *i
	)
	{
#if defined(CONFIG_X86)
	int  vector;     /* vector to which interrupt is connected */

Make sure to start every comment with /** and end it with */. Every comment must start with a capital letter and end with a period.

Doxygen requires that line 6 is left blank. Ensure a blank line separates each group of variable and comment.

Incorrect:

The struct has no documentation. Developers that want to expand its functionality have no way of understanding why the struct is defined this way nor what its components are.