BLACKSheep® Doxygen Guideline

From BlueWiki

Jump to: navigation, search

Contents

1 Scope

This page provides a short overview about the Doxygen Source Code documentation tool and how to add doxygen support to your source code.

Get more info about doxygen here.

You have to write your comments in a special style and the doxygen program parses your source code and can be configured in a very flexible way by a configuration file. Doxygen can generate a source code documentation as .rtf,.tex or as set of html pages.

2 Doxygen Syntax

2.1 Defining an Doxygen Block

Doxygen uses a slightly different syntax from standard c/c++ comment blocks.
Doxygen defines different comment styles which can be parsed by the program.

 /**
 *  line 1
 *  line 2
 *  line 3
 **/
 code ...
 
 Code /// a single line
 Code ///< inline comment

2.2 Tags

In addition to simple comments doxygen features special keywords (Tags) in order to structure the output document .
These tags start with an “@” followed by the tag name.

Important tags
Tag Description
@file<name> Starts a documentation block for the file "name".
@brief Brief description (one line).
@author<name> Name of the authors.
@version<name> Version of the source code.
@pre<text> Description of preconditions.
@post<text> Description of postconditions.
@see<entity> Link to another doxygen entity.
@param<name><description> Description of parameter of a function.
@return<name><description> Description of the return value of a function.
@attention<text> Add a warning text to a file and function.
ingroup<name> Associate file to an group.
defgroup <name><text> Define a group with name and description.

2.3 What can/must be documented

The following enties can be documented
  • Files
  • Functions
  • Structs/enums
  • Groups: entities can be grouped in doxygen . And these groups can be documented.
Entity Property Doxytagrequired
file @file<name>Yes
Brief description@brief<text> Yes
Author@author<names> Yes
Version@version<name> Optional
Date@date Optional
Function
Brief description@brief<text> Yes
Long descriptionOptional
Parameter@param<name><description> Yes
Return@return<name><description> Yes
Non-trivial preconditions@pre<text> Yes/Opt.
Non-trivial preconditions@post<text> Yes/Opt.
Struct
Brief description@brief<text> Yes
Long descriptionOptional


2.4 Documenting an entity

2.4.1 File

Every file must contain a standard header featuring doxytags.

Example
 /**
   @file stringTools.h
   @ingroup String
   @brief Additional string functions
   This file contains helpful string functions which are not covered by <string.h>
   BLT_DISCLAIMER(TBD)
   @author Roland Oberhammer
   @version 1.0
   @date 01.04.2010
 **/

2.4.2 Function

Note that every parameter of the function and the return value are documented by using
@param tags- Documents in the function body should not be converted in doxytags.

 /**
        @brief Split string by given seperator  
        @param *pa_acSource source string
        @param pa_cSeparator  Separator character
        @param **acSubstrings   Output, pointer array to seperated substrings
        @return Number of substrings found
 **/
 int strsplit(char *pa_acSource, char pa_cSeparator, char **acSubstrings) {
    register unsigned short nSubStrCount = 0;
    register unsigned short cIndex = 0;
 
    while (cIndex < strlen (pa_acSource)) {
        char *SubStr = acSubstrings[nSubStrCount];
        while ((pa_acSource[cIndex] != pa_cSeparator) && (cIndex < strlen (pa_acSource))) {
            *SubStr = pa_acSource[cIndex];
            SubStr ++;
            cIndex++;
        }
        *SubStr = 0;
        cIndex ++;
        nSubStrCount++;
    }
    return (int)nSubStrCount;
 }

2.4.3 Additional tags

In addition to the required parameters additional tags can be added if necessary.

2.4.4 Attention: @attention < text>

If a function has known bugs or restrictions which are not obvious .
A attention text should be added to notify the user about a special (You can also use @warning instead)

2.4.5 Postcondition: @post < text>

If this function enables some further steps after calling they could be noted here.

2.4.6 Precondition: @pre < text>

Steps that have to be taken before calling this function.

Example
 /**
        @brief Destructs your house
        @attention this function destroys your house!
        @param timer seconds to destruction
        @pre ApplyDynamite()  called
        @post your house is destroyed
 **/
 void Destruct_House(int pa_nSeconds ){
     ...
 }

2.4.7 Struct

Structs/enums are documented with an generic header before the structure which features brief and long description.
Every member of the structure is described with an inline doxygen comment.

Example
 /**
        @brief device info structure to specify transfer parameters   
        these parameters have different meanings for character devices
        (qualified with "on char-devices:")
 */
 typedef struct {
     unsigned long  nBlockCount;      ///<number of blocks, on char-devices: receive buffer size
     unsigned long  nBlockSize;       ///<size of one block, on char-devices: undefined
     unsigned short nCylinderCount;   ///<number of cylinders, on char-devices  
     unsigned short nHeadCount;       ///<number of heads, on char-devices  
     unsigned short nBlocksPerTrack;  ///<number of blocks per track,
     T_DEVICE_TYPE  tDeviceType;      ///<type of device (block device, character device)
 } T_DEVICE_INFO;

2.5 Defining Groups/Modules in Doxygen

Doxygen provides a mechanism to group several source files to modules and groups. A group must be defined once in the source code and then every file can be added to this group. Groups can even be added to other groups to create some sort of hierarchy.

A group can be defined by the following block:

@defgroup <name> (group title)
Example
 /** @defgroup lowleveldrv_grp Low Level Driver
     contains low level hardware support
     @{@}
 */

Note that a group includes all entities between the @{ and the @} tags. But you can also add documented entities.

To add a file to specific group the file header must contain a tag “@ingroup groupname

2.5.1 Creating a group hierarchy

You can also add groups to other groups to create a hierarchical structure of groups.

 /** @defgroup group3 The Third Group
 *  This is the third group
 */
 /** @defgroup group4 The Fourth Group
 *  @ingroup group3
 *  Group 4 is a subgroup of group 3
 */

2.5.2 @see tag

The @see tag can be used to link or point to another documented entities.

Syntax “@see <entity name>

 /**
     @brief device info structure to specify transfer parameters
     these parameters have different meanings for character devices
     (qualified with "on char-devices:")
     @see CharacterDevicesGroup
 */

2.6 Bluetechnix Standard headers

2.6.1 File

 /**
 *    @file filename.c
 *    @ingroup mygroup
 *  
 *    @brief Short description of the File/Module
 *  
 *    maybe a longer description
 *  
 *    which can go over several lines
 *  
 *    BLT_DISCLAIMER
 *  
 *    @author programmer1 , programmer2
 *  
 *    @cond svn
 *  
 *    Information of last commit
 *    $Rev::               $:  Revision of last commit
 *    $Author::            $:  Author of last commit
 *    $Date::              $:  Date of last commit
 *  
 *    @endcond
 **/
 
 /**
 *    @defgroup mygroup My group
 *    @ingroup othergroup
 *    @brief short description
 *  
 *     Some text
 *  
 *  @{@}
 **/

2.6.2 Function

 /**
 *    @brief <text>
 *    @attention  <text>
 *  
 *    More text
 *  
 *    @param  name <text>
 *    @return <text>
 *    @pre <text>
 *    @post  <text>
 **/

2.6.3 Struct/Enum

 /**
 *    @brief <text>
 *    @attention  <text>
 *  
 *    More text
 *  
 *  
 
 **/
 typedef struct {
     type name;  ///< Description
 } T_MY_STRUCT;

2.6.4 Defines and global variables

Single line
#define NAME VALUE    ///< Description

Create a group of defines (e.g. a group of error codes).

 /**
 *    @name Groupname
 */
 //@{
 *    #define NAME1 VALUE1 ///< text1
 *    #define NAME2 VALUE2 ///< text2
 *    #define NAME3 VALUE3 ///< text3
 //@}
Personal tools