2 * \defgroup coding-style Coding style
4 * This is how a Doxygen module is documented - start with a \defgroup
5 * Doxygen keyword at the beginning of the file to define a module,
6 * and use the \addtogroup Doxygen keyword in all other files that
7 * belong to the same module. Typically, the \defgroup is placed in
8 * the .h file and \addtogroup in the .c file.
15 * A brief description of what this file is.
17 * Adam Dunkels <adam@sics.se>
19 * Every file that is part of a documented module has to have
20 * a \file block, else it will not show up in the Doxygen
21 * "Modules" * section.
24 /* Single line comments look like this. */
27 * Multi-line comments look like this. Comments should prefferably be
28 * full sentences, filled to look like real paragraphs.
34 * Make sure that non-global variables are all maked with the static
35 * keyword. This keeps the size of the symbol table down.
40 * All variables and functions that are visible outside of the file
41 * should have the module name prepended to them. This makes it easy
42 * to know where to look for function and variable definitions.
44 * Put dividers (a single-line comment consisting only of dashes)
47 /*---------------------------------------------------------------------------*/
49 * \brief Use Doxygen documentation for functions.
50 * \param c Briefly describe all parameters.
51 * \return Briefly describe the return value.
52 * \retval 0 Functions that return a few specified values
53 * \retval 1 can use the \retval keyword instead of \return.
55 * Put a longer description of what the function does
56 * after the preamble of Doxygen keywords.
58 * This template should always be used to document
59 * functions. The text following the introduction is used
60 * as the function's documentation.
62 * Function prototypes have the return type on one line,
63 * the name and arguments on one line (with no space
64 * between the name and the first parenthesis), followed
65 * by a single curly bracket on its own line.
68 code_style_example_function(void)
71 * Local variables should always be declared at the start of the
74 int i
; /* Use short variable names for loop
78 * There should be no space between keywords and the first
79 * parenthesis. There should be spaces around binary operators, no
80 * spaces between a unary operator and its operand.
82 * Curly brackets following for(), if(), do, and case() statements
83 * should follow the statement on the same line.
85 for(i
= 0; i
< 10; ++i
) {
87 * Always use full blocks (curly brackets) after if(), for(), and
88 * while() statements, even though the statement is a single line
89 * of code. This makes the code easier to read and modifications
90 * are less error prone.
93 return c
; /* No parentesis around return values. */
94 } else { /* The else keyword is placed inbetween
95 curly brackers, always on its own line. */
100 /*---------------------------------------------------------------------------*/
102 * Static (non-global) functions do not need Doxygen comments. The
103 * name should not be prepended with the module name - doing so would
107 an_example_function(void)
111 /*---------------------------------------------------------------------------*/
113 /* The following stuff ends the \defgroup block at the beginning of