Variable Documentation

Variables are the smallest element that requires documentation. As such only a brief description is required detailing the purpose of the variable. Only significant variables have to be documented. A significant variable is a variable that adds functionality to a component. Review the Variable Documentation Examples to understand what constitutes a significant variable.

Variable Comment Template

/** Brief description of singificant_variable's purpose. */
int significant_variable;

Variable Documentation Examples

Example 1

This example shows a function that has been fully documented following the best practices.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
	struct nano_sem *f2;
#else
	/** Declares a fork for the microkernel. */
	kmutex_t f1;
	kmutex_t f2;
#endif
	/** Declares the current philosopher's ID. */
	static int myId;

	/** Declares an interrupt lock level.*/
	int pri = irq_lock();

	/** Declares the next philosopher's ID. */
	int id = myId++;

	irq_unlock(pri);

	if ((id + 1) != N_PHILOSOPHERS) { /* A1 */
		f1 = FORK(id);
		f2 = FORK(id + 1);
	} else {
		f1 = FORK(0);
		f2 = FORK(id);
	}

	while (1) { /* A2 */
		TAKE(f1);
		TAKE(f2);

		PRINT(id, "EATING  ");
		RANDDELAY(id);

		GIVE(f2);
		GIVE(f1);

		PRINT(id, "THINKING");
		RANDDELAY(id);
	}
}

Lines 15 and 18 show the documentation for two variables. The blank line 17 is necessary to increase the clarity of the code and also so Doxygen can determine properly where the comment belongs.

Lines 21-23 show another acceptable way to document two variables with a similar function. Notice that only the first variable is documented. The argument can be made that kmutex_t f2 is no longer a significant variable because it does not add any functionality that has not been described for kmutex_t f1.

Lines 25 and 31 show us a different situation. Although both variables are of the same type and very similar, they have different purposes. Therefore, both must be documented and the difference between them must be noted.

Example 2

Variables outside of functions must be documented as well.

1
2
3
4
5
6
7
8
 * -# Initializes timer.
 * -# Waits for task, then runs.
 * -# Outputs "Hello World!".
 * -# Waits, then yields to another task.
 */
void fiberEntry(void) {
	struct nano_timer timer;
	uint32_t data[2] = { 0, 0 };

As you can see, the syntax of the comment does not change. Always start the comment with /** and end it with */. Remember to begin with a capital letter and end with a period, even if the comment is only a sentence fragment.

Notice that the variable comments also apply for more complex types like structs. The comments on lines 4 and 7 apply only to the specific variable and not to the whole struct. Complex types must be documented wherever they are defined. See Structure Documentation and Type Definition Documentation for further details.