Function Documentation

Doxygen recognizes a wide variety of syntaxes and structures for the function comments. The syntax described here is one of many that are possible. If your development requires an option that is not described here, use it. However, you may use the following syntax for everything else.

Note

When linking functions within a ReST file, two possible markups are: :cpp: or :c:. Use :cpp: for functions defined using an extern. Use :c: for functions defined using a #define.

Function Comment Templates

The full template shows the best practices for documenting a function. The simplified version shows the minimal acceptable amount of documentation for a function. Use the simplified template only if you are familiar with Doxygen and how it uses blank lines to recognize the parts of the comment.

Full template:

/**
 * @brief Short description of my_function().
 *
 * @details Longer multi-paragraph description.
 * Use this longer description to provide details about the
 * function's purpose, operation, limitations, etc.
 *
 * @param a This is the first parameter.
 * @param b This is the second parameter.
 *
 * @return Information about the return value.
 *
 * @error
 * Details about the possible error.
 *
 * @warning
 * This would be a warning.
 */
my_function(int a, int b){}

Simplified template:

/**
 * Short description of my_function().
 *
 * Longer multi-paragraph description.
 * Use this longer description to provide details about the
 * function's purpose, operation, limitations, etc.
 *
 * @param a This is the first parameter.
 * @param b This is the second parameter.
 *
 * @return Information about the return value.
 */
my_function(int a, int b){}

Important

Ensure that you have no blank lines between the comment block and the function’s signature. This ensures that Doxygen can link the comment to the function.

Function Documentation Examples

Example 1

Take the very simple function taskA():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
/*This is a hello world example*/
/*taskA exchanges hello messages with taskB*/
/*
* @brief Does Hello message.
* -Calls function helloLoop.
*/
void taskA(void)
{
	helloLoop(__func__, TASKBSEM, TASKASEM);
}

#else

The highlighted lines contain comments that will be missing from the generated documentation. To avoid this, pay careful attention to your commenting syntax. This example shows good commenting syntax. taskA() is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
/**
 * @brief Exchanges Hello messages with taskB.
 *
 * @details
 * Actions:
 *  -# taskA gives its own semaphore, thus it says hello right away.
 *  -# Calls function helloLoop, thus taskA exchanges hello messages with taskB.
 */
void taskA(void)
{
	task_sem_give (TASKASEM); /* Action 1 */

	helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */
}

The highlighted lines show how to reference the code from within a comment block. The direct reference is optional and the comments on lines 11 and 13 are not added to the documentation. This method allows for easy maintenance of the code blocks and easy addition of further details. It also helps maintain the 72 character line length.

Example 2

Take the more complex function hello_loop():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
 /* @brief A loop saying hello.
 *
 \param taskname The task's identification string.
 \param mySem    The task's semaphore.
 \param otherSem The other task's semaphore.
 *
 */
void taskA(void)
{
	helloLoop(__func__, TASKBSEM, TASKASEM);
}
#else
 /* Actions:
 *
 * -# Ouputs "Hello World!".
 * -# Waits, then lets another task run.
 */

The function parameters have been documented using the correct Doxygen command, yet notice line 1. The comment block was not started with /** so, Doxygen will not parse it correctly.

The parameters have been documented using the \param command. This is equivalent to using @param but incorrect according to these guidelines. Restructured Text uses the \ as the escape for special characters. To avoid possible conflicts, the @ symbol must be used instead.

Notice that there is no blank line between the comment and the function’s signature, lines 7 and 8. This allows Doxygen to correctly link the comment to the function.

Lines 13-16 contain comments that will not be included by Doxygen in the documentation. To include that information, use the brief description or the detailed description inside the comment block. Remember that variables must be documented separately. See Variable Documentation for more details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
/**
 * @brief A loop saying hello.
 *
 * @details
 * Actions:
 * 	 -# Ouputs "Hello World!".
 * 	 -# Waits, then lets another task run.

 @param taskname The task's identification string.
 @param mySem    The task's semaphore.
 @param otherSem The other task's semaphore.
 */
void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem)
{
	while (1)
	{
		task_sem_take (mySem, TICKS_UNLIMITED);

		PRINT ("%s: Hello World!\n", taskname); /* Action 1 */

		task_sleep (SLEEPTICKS); /* Action 2 */
		task_sem_give (otherSem);
	}
}

Comment blocks must have the following structure:

  1. Brief description. See line 2.
  2. Detailed description. See lines 4-7.
  3. Parameter information. See lines 9-11.
  4. Return information. Return information is optional for void functions.
  5. Other special commands. There is no specific order for any further special commands.

The description of the actions referenced in lines 19 and 21 is part of the detailed description in the comment block. The references shown in lines 19 and 21 are optional.