doc/code-style.c

   1 /**
   2  * \defgroup coding-style Coding style
   3  *
   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.
   9  *
  10  * @{
  11  */
  12
  13 /**
  14  * \file
  15  *         A brief description of what this file is.
  16  * \author
  17  *         Adam Dunkels <adam@sics.se>
  18  *
  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.
  22  */
  23
  24 /* Single line comments look like this. */
  25
  26 /*
  27  * Multi-line comments look like this. Comments should prefferably be
  28  * full sentences, filled to look like real paragraphs.
  29  */
  30
  31 #include "contiki.h"
  32
  33 /*
  34  * Make sure that non-global variables are all maked with the static
  35  * keyword. This keeps the size of the symbol table down.
  36  */
  37 static int flag;
  38
  39 /*
  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.
  43  *
  44  * Put dividers (a single-line comment consisting only of dashes)
  45  * between functions.
  46  */
  47 /*---------------------------------------------------------------------------*/
  48 /**
  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.
  54  *
  55  *             Put a longer description of what the function does
  56  *             after the preamble of Doxygen keywords.
  57  *
  58  *             This template should always be used to document
  59  *             functions. The text following the introduction is used
  60  *             as the function's documentation.
  61  *
  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.
  66  */
  67 void
  68 code_style_example_function(void)
  69 {
  70   /*
  71    * Local variables should always be declared at the start of the
  72    * function.
  73    */
  74   int i;                   /* Use short variable names for loop
  75                               counters. */
  76
  77   /*
  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.
  81    *
  82    * Curly brackets following for(), if(), do, and case() statements
  83    * should follow the statement on the same line.
  84    */
  85   for(i = 0; i < 10; ++i) {
  86     /*
  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.
  91      */
  92     if(i == c) {
  93       return c;           /* No parentesis around return values. */
  94     } else {              /* The else keyword is placed inbetween
  95                              curly brackers, always on its own line. */
  96       c++;
  97     }
  98   }
  99 }
 100 /*---------------------------------------------------------------------------*/
 101 /*
 102  * Static (non-global) functions do not need Doxygen comments. The
 103  * name should not be prepended with the module name - doing so would
 104  * create confusion.
 105  */
 106 static void
 107 an_example_function(void)
 108 {
 109
 110 }
 111 /*---------------------------------------------------------------------------*/
 112
 113 /* The following stuff ends the \defgroup block at the beginning of
 114    the file: */
 115
 116 /** @} */