Structure Documentation

Structures, or structs for short, require very little documentation, and it’s best to document them wherever they are defined. Structs require only a brief description detailing why they are needed. Each variable that composes a struct needs a comment contained within the correct syntax. 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 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
/** Defines the ISR initialization information. */
struct isrInitInfo
	{
	/** Declares the void-void function pointer for the ISR. */
	vvpfn isr[2];

	/** Declares a space for the information. */
	void *arg[2];
	};

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:

1
2
3
4
5

struct isrInitInfo {
	vvpfn isr[2];
	void *arg[2];
};

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.