/** * @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.
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 |
@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 CommandsCommands 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
*/