File content as of revision 11:4747badb2448:

Dokumentace souborů

V hlavičkových souborech a main.c pište plnou dokumentaci funkcí, struktur atd., ve všech souborech navíc pište tagy @author a @file. V textu dokumentace používejte angličtinu.

Ukázka hlavičkového souboru
#ifndef MY_AWESOME_LIBRARY_H
#define MY_AWESOME_LIBRARY_H
 
/**
 * @brief   [OPTIONAL] Brief file description.
 * @file    my_awesome_library.h
 * @author  John Doe <john.doe@example.com>
 *
 * [OPTIONAL] Detailed file description.
 */
 
#include <stdlib.h>
// ...
 
#endif // MY_AWESOME_LIBRARY_H
Ukázka jiného (nehlavičkového) souboru
/**
 * @author John Doe <john.doe@example.com>
 * @file   list.c
 */
 
...

Dokumentace struktur a výčtových typů
/**
 * @brief Doubly linked list node.
 *
 * [OPTIONAL] Detailed description.
 */
typedef struct node
{
    struct node *prev; /**< previous node        */
    struct node *next; /**< next node            */
    void        *data; /**< pointer to node data */
} node_t;
 
/**
 * @brief UNIX file system permissions.
 *
 * [OPTIONAL] Detailed description.
 */
typedef enum mode
{
    Read    = 1, /**< read a file or list contents of a directory */
    Write   = 2, /**< modify a file or directory entries          */
    Execute = 4  /**< execute a file or enter a directory         */
} mode_t;


Dokumentace funkcí
Pokud chcete v textu odkazovat parametr funkce, použijte značku @a parametr, hodnoty můžete značit např. značkou @c true. Funkce, které nic nevrací (mají návratový typ void) pochopitelně nemusí mít značku @return.

/**
 * @brief   Halting problem solver.
 * @param   tm      Turing machine to simulate
 * @param   input   input to simulate the @a tm with
 * @return  @c true if the machine @a tm will halt with the tape @a input, @c false otherwise
 * @note    [OPTIONAL] The content of the @a input tape will remain unchanged.
 * @warning [OPTIONAL] Still under development.
 * @bug     [OPTIONAL] This function can run indefinitely for some inputs.
 *
 * [OPTIONAL] Detailed information on how awesome this function is.
 */
bool halts(machine_t *tm, tape_t *input);
Navíc, pokud je argument funkce ukazatel, přidejte za param položku [in], [out] nebo [in,out] pokud je to vstupní, výstupní resp. vstupno-výstupní argument:

/**
 * @param[in]     ro   memory to be read
 * @param[out]    wo   memory to be filled
 * @param[in,out] rw   memory to be read and written
 */
void foo(const void *ro, size_t *wo, char *rw);