/** * @page docs Documenting the code * @ingroup guidedev * @author Michael Baar

Code developed for the ScatterWeb system shall be documented using Doxygen. To keep it consistent the same style of Doxygen tags shall be used throughout the whole code.

Some general rules:

Formatting rules:

If you're using Eclipse as your editor, it will gladly support you by creating the stars at the beginning of the lines.

@section docs_module Module Documentation

Modules are documented as separate pieces of documentation. Place one or more files with module documentation into a "docs" subdirectory of the library. Make sure the file names match the code file names (e.g. ScatterWeb.Configuration). Documentation files shall use the extension "doc.html".

To create a module section in the documentation you have to create a group using defgroup. Files and other documentation blocks can then be added to this group. See grouping.

Example:

@verbatim
/**
 * @defgroup config Node Configuration
   
Documentation using doxygen plus simple html tags (paragraphs, tables, bold) goes here.

 @section	config_s1	Section 1

Text...
 
 @section	config_s2	Section 2

Text ...*/ @endverbatim
@section docs_file File Documentation
@verbatim
/**
 * @file        ScatterWeb.Configuration.c
 * @ingroup     config						
 * @brief       Configuration public interface
 * @version     $Revision$					
 * @since       1.0
 * @author      Michael Baar
 *
 * Long description of file. If module description is available, a link to this.
 *
 * $Id$
 */
/**
  * @ingroup config
  * @{

File Contents...

/** @} */
 @endverbatim

The first documentation block describes the file contents. The second block, that spans over the whole files says that all documentation inside it belongs to the module "config". This way you don't have to add the \@ingroup tag to every member.

Tag Description
\@file file name without path
\@ingroup module (see \ref docs_module)
\@brief Short description of what this file contains.
\@version always $Rev$ (which gets replaced by the SVN revision)
\@since First ScatterWeb version this file was introduced.
\@author One or more authors separated by comma (if applicable).
(description) More detailed documentation on this file. If there is module documentation, provide a link and make this short. Again, always put "$Id$" at the end. It is replaced by subversion.

Note: Make sure, that there's a blank line above

@section docs_fn Function Declarations
@verbatim
/**
 * @brief         Get a string from a stringtable
 * 
 * @param[in]     table    Stringtable
 * @param[in]     index    String to get from table
 * @return                 Pointer to start of string index from table. If the end of the table is reached, returns pointer to '\0';
 * 
 * @since         1.1
 * 
 * A stringtable shall be a character array with one or more strings, with each string
 * ending with a null-character. The table is to be terminated by an end-of-text character.
 * The first string shall have the index 0.
 *
 * Example: const char stringtable[] = "string1\0string2\0\3"
 */
const char* String_stringtableGet(const char* table, register const UINT16 index);
@endverbatim
Tag Description
\@brief Short description of what this functions does
\@param Direction, Name of parameter (must match that in declaration) and short description.
\@return Short description of return value (if any).
\@since First ScatterWeb version this function was introduced.
  Documentation of function using possibly (may use few, simple html tags)

Private functions (those which are not declared in header files) shall be documented by at least a brief documentation inside the c-file.

@section docs_commands Commands

Commands are essentially functions, but defined by macros and with parameters that are not defined in code. They will be shown in the documentation as ASCII_COMMAND(name). They are to be documented like any other function, but Doxygen will display warning about parameters, which are not found in the code.

Document the command line within the brief tag, as seen below. Mandatory parameter names shall be noted without brackets, optional parameters with square brackets. All command shall be added to the "commands" group.

Example:

@verbatim
/**
 * @brief	       Node id property \\n id [newid]
 * @ingroup        commands
 * @param	       newid    New node id (optional)
 * @return         Current id
 */
COMMAND(id, 0, cmdargs) {
...
}
@endverbatim
*/