/** * @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:

- Each file has have a header.
- All members placed in headerfiles must have documentation.
- While reading this, open the existing documentation for examples!
- After documenting run Doxygen, fix all errors and test the documentation!

Formatting rules:

- Use the Doxygen JavaDoc style notation: @verbatim /** * @tagname value * */ @endverbatim
- Use the at-character for Doxygen tags in all code files.
- Use tabs to separate tags and their values to align the nicely. Make sure you editor does not replace tabs by spaces.

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

- \ref docs_module
- \ref docs_file
- \ref docs_fn
- \ref docs_commands

@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

*/