This page describes BeRTOS documentation and provides a simple template to cut and paste. Explanations are given inline.

/**
 * \file
 * <!--
 * This file is part of BeRTOS.
 *
 * Bertos is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * As a special exception, you may use this file as part of a free software
 * library without restriction.  Specifically, if other files instantiate
 * templates or use macros or inline functions from this file, or you compile
 * this file and link it with other files to produce an executable, this
 * file does not by itself cause the resulting executable to be covered by
 * the GNU General Public License.  This exception does not however
 * invalidate any other reasons why the executable file might be covered by
 * the GNU General Public License.
 *
 * Copyright 2010 Develer S.r.l. (http://www.develer.com/)
 * -->
 *
 * \defgroup heap Embedded optimized memory allocator
 * \ingroup core
 * \{
 *
 * \brief Heap subsystem (public interface).
 *
 * This is the long documentation of the module.
 * Describe the intended usage.
 *
 * Put at least a code snippet
 * \code
 * //insert a code snippet here
 * \endcode
 *
 * \author [put your name here]
 *
 * $WIZ$ module_name = "heap"
 * $WIZ$ module_configuration = "bertos/cfg/cfg_heap.h"
 */

Code here
#if CONFIG_VAR_DEFINED
/**
 * Don't forget to add CONFIG_VAR_DEFINED to Doxyfile-common, otherwise doxygen
 * won't see this function!
 */
INLINE int foo(int bar)
{
    return 42;
}
#endif

 /** \} */ //defgroup heap

Defining the module

First, we give the module an ID and a brief description, which will be shown in the Modules tab. In this case the ID is heap.

 * \defgroup heap Embedded optimized memory allocator
 * \ingroup core
 * \{

Then decide which group the module will belong to. Currently the following general groups are defined:

• core: this group is for core BeRTOS features. It contains KFile, KBlock, logging, event handling modules etc.
• kern: contains kernel related features. Right now is contains msg, proc, sem, signal
• drivers: all hardware drivers should be added to this group

TODO: most probably I'll add at least the drivers and struct modules.

Documenting the module

When documenting a module, describe how the module is intended to work and put at least one code snippet. See KBlock or KFile for an example. Put your name and email using the \author tag; it must be the last documentation tag before the end of the file preamble.

 * This is the long documentation of the module.
 * Describe the intended usage.
 *
 * Put at least a code snippet
 * \code
 * //insert a code snippet here
 * \endcode
 *
 * \author J. Random Developer <jrandom@provider.com>

You can test your changes by launching doxygen from the root BeRTOS directory:

doxygen Doxyfile-offline

then open the doc/offline-reference/html/index.html and check your changes

Wizard tags

Wizard tags must stay in the .h file, at the top of the file and after all doxygen related stuff.

 * $WIZ$ module_name = "heap"
 * $WIZ$ module_configuration = "bertos/cfg/cfg_heap.h"
 */

Documentation rules

1. Documentation must be put above the implementation of the function. Doxygen is smart (for some definitions of smart); it will take the documentation from .c file if the .h file only has the prototype;
   1. Corollary: DO NOT document functions above the prototype (in .h file) unless the function is INLINE. Most probably the next maintainer will forget to change the documentation if it's defined in another file.
   2. Exceptions are allowed if the .c file documents the implementation details of the function. In this case, documentation for users must go into .h files.
2. If the documented function is inside an #ifdef block, don't forget to define the macro in Doxyfile-common, otherwise doxygen won't see the function and no documentation will be generated;
3. \author tag must be the last doxygen tag in the file preamble, otherwise authorship information will be put in the middle of the description of the module (which is ugly to say the least); 1.