codingStyle.txt

/**
 * Description of the coding style for the source files.
 *
 * @file        codingStyle.txt
 * @ingroup     codingStyle
 * @version     SVN: \$Id$
 * @author      Janez Paternoster
 * @copyright   2013 Janez Paternoster
 * 
 * License.
 */


#ifndef XYZ_H
#define XYZ_H


/**
 * @defgroup codingStyle Description of coding style
 * @ingroup parentGroup
 * @{
 *
 * Contents of this file should be the base for .h source file, except function
 * body at the end.
 *
 * ###Indentation
 * Indent size is 4.
 * Spaces are used, not tabs.
 *
 * ###Doxygen
 * Documentation is generated by <http://doxygen.org>.
 * Doxygen comment starts with /**. /**< is used after member.
 * Documentation is usually in header.
 * Doxygen settings:
 *  - JAVADOC_AUTOBRIEF = YES.
 *  - See doxyfile for other settings.
 *
 * Doxygen specifics: If description of the structure member is one sentence only,
 * don't use period after the sentence.
 *
 * ###Misra C
 * Code shall follow MISRA-C:2004 standard.
 *
 * ###Version control
 * Version is updated automatically by SVN commit. Number before the date is SVN
 * revision number. (Setup for each added file: TortoiseSVN->proprties->New->ID).
 */


/**
 * Brief description of the object ends at this dot. Details follow
 * here.
 */
typedef struct{
    int8_t              member1;        /**< Short description of the member 1 */
    uint16_t            member2;        /**< Note the '/**<' sequence after the member 2 */
    /** Long description of the variable stringMember. More description. */
    char_t              stringMember[5];
}object1_t;


/**
 * Function example 1.
 *
 * This is global function. Local functions (and variables) used inside one file
 * are declared as static and not documented by Doxygen.
 *
 * @param obj Pointer to object. Function operates on this object (not on global
 * variables).
 * @param arg2 Description of the argument.
 * @param arg3 Description of the argument.
 * @param arg4 Description of the argument.
 *
 * @return Some value.
 */
int32_t foo1(
        object1_t              *obj,
        int32_t                 arg2,
        uint16_t                arg3,
        float32_t               arg4)
{
    /* Comment */

    /* Multiline
     * comment.
     */

    if(xy == yz){   /* Comment. '//' comments are not allowed by MISRA-C */
        ...
    }
    else{
        ...
    }

    switch(zx){
        case 1:{
            ...
        }
    }
}

/** @} */
#endif