File Header Documentation

Every .c, .h and .S file must contain a file header comment at the beginning of the file. The file header must contain:

  1. The filename. Use @file for Doxygen to auto-complete the filename.
  2. The brief description: A single line summarizing the file contents. Use @brief to clearly mark the brief description.
  3. The detailed description: One or multiple lines describing the purpose of the file, how it works and any other pertinent information such as copyrights, authors, etc.

Note

Doxygen has special commands for copyrights (@copyright), authors (@author), and other important information. Refer to the Doxygen documentation for details.

Examples

Correct:

  • A file header with a single line description.
1
2
3
4
5
/** @file
 @brief Hello World Demo

 A Hello World demo for the Nanokernel and the Microkernel.
 */
  • A file header with a larger description.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/** @file
 * @brief An implementation of a solution to the dining philosophers problem
 *  for both the nano- and microkernel.
 *
 * This particular implementation uses 6 fibers or tasks of
 * different priority, semaphores and timers. The implementation demostrates
 * fibers and semaphores in the nanokernel and tasks and timers in the
 * microkernel.
 */

Incorrect:

A file header without a detailed description.

1
2
3
/** @file
 *  @brief Solution to the dining philosophers problem using fibers.
 */