wiki:DoxygenHeaders

Doxygen Headers

Since November 2009, we are in the process to create doxygen headers for the whole code base of vuurmuur. Since it is a very big operation, we have decided to do it in small chunks. We will start documenting the new functions with the doxygen headers and when working on current functions we will add the headers.

Sample header

This section is still Work in Progress.

To document a function we use the following doxygen template. The documentation of functions will be done at the location of the function and not at the prototype.

/** \file
 * A description of the file */

/** \addtogroup Group1
 *  @{ */

/** \brief Layout description of a struct */
typedef struct
{
    char var1; /**< Description of var1 (when it is small) */
    /** Long description of var2 that needs a lot of information and can't
     *  fit on 1 line with the var2 itself */
    int var1;
} StructName;

/**
 * \brief A brief description of the function
 *
 * And a more detailed description of the function that doesn't fit
 * on 1 line
 *
 * \pre The preconditions of the function, which should be checked by the function
 * \post The postconditions of the function
 * \param[in] var1 The value that is used to devide
 * \param[in,out] var2 A pointer to the result, and ...
 * \return The function returns the value of the calculation.
 * \retval -1 When var1 or var2 is 0
 * \note A note that applies to the function
 */
int FunctionName( int var1, char *var2 )
{
    if ( var1 == 0 || var2 == 0 )
    {
        return -1;
    }
    *var2 = *var2/var1;
    return *var2;
}

/** @} */

Generating documentation

Nothing done yet on this part.

Last modified 9 years ago Last modified on 11/09/09 09:41:40