doxygen总结

//
// example.h
/**
 * @copyright Copyright (C) 2008-2012, ABC Corporation. All rights reserved.
 * @file example.h （文件也可以在一个模块中，使用 ingroup指令指定其所属的模块）注意文件名必须正确，否则无法链接
 * @brief 这里是文件example.h的说明
 * @author 某某某
 * @version 0.1
 * @date 2012-04-08
 */


/** 
 * @defgroup Module_Macro 常量定义部分 （这里是一个模块）
 * 该模块的详细说明 \n
 * 详细说明继续
 * @{
 */
/** 这里是宏EXAMPLE_OK的说明 */
#define EXAMPLE_OK 0




/** 
 * @name 文件名常量 （这里是一个成员组，要放入一个模块中。不要定义成员组，可以用枚举来取代）
 * @{
 */
/** 日志文件名 */
#define LOG_FILENAME "d:\\log\\debug.log"




#define DATA_FILENAME "d:\\data\\detail.dat" /**< 数据文件名 */




/** 存档文件名 */
#define BAK_FILENAME "d:\\data\\backup.dat"
/** @} 文件名常量 */




/** 
 * @name 系统状态常量 （这里是一个成员组，要放入一个模块中）
 * @{
 */
/** 正常状态 */
#define SYS_NORMAL 0




/** 故障状态 */
#define SYS_FAULT 1




/** 警告状态 */
#define SYS_WARNNING 2
/** @} 系统状态常量 */




/** @brief 定义类型 EDayOfWeek （这个说明是必须的，如果没有这个说明，成员的说明不会出现在文档中） */
typedef enum
{
    SUN = 0, /**< 星期天（注意：跟在变量之后的说明要以<开头） */
    MON = 1, /**< 星期一 */
    TUE = 2, /**< 星期二 */
    WED = 3, /**< 星期三 */
    THU = 4, /**< 星期四 */
    FRI = 5, /**< 星期五 */
    SAT = 6  /**< 星期六 */
} EDayOfWeek;




/** @} Module_Macro */




// 另一种加入模块中的方式
/** 
 * @ingroup Module_Macro
 * @brief 这里是宏EXAMPLE_FAILED的说明
 */
#define EXAMPLE_FAILED -1




/** 
 * @defgroup Module_Global 全局变量 （这里是一个模块）
 * @{
 */
int g_i32GlobalVal; /**< 这个全局变量的说明 */
/** @} Module_Global */




/** 
 * @defgroup Module_FileUtil 文件操作接口 （这里是一个模块）
 * 操作文件的接口集合
 */




// 另一种加入模块中的方式
/** @addtogroup Module_FileUtil
 *  More documentation for the first group.
 *  @{
 */
int OpenFile(const char* file_name, const char* file_mode);
int ReadFile(int file, char* buffer, int len);
int WriteFile(int file, const char* buffer, int len);
int CloseFile(int file);
/** @} Module_FileUtil */




/** 
 * @brief 这里是类Example的简要说明
 * @details （class、struct可以不放入模块中，因为doxygen会单独生成一个类tab页，其中放置class和struct。 \n
 *           其它的东西（宏、枚举、函数）都应该放入模块中，否则只能显示在文件tab页中，不好看。 \n
 *           模块可以嵌套，表示多级关系
 */
class CExample
{
private:
    int m_i32Val1; /**< 这里是private成员m_i32Val1的说明，不会在文档中出现 */




public:
    int m_i32Val2; /**< 这里是public成员m_i32Val2的说明，会出现在文档中 */




    int Func1(int a, int b);
    char* Func2(char* c);
    void Func3();
};




/** @brief 定义类型 TStructType （这个说明是必须的，如果没有这个说明，成员的说明不会出现在文档中） */
typedef struct
{
    int m_i32Val1; /**< 成员1 */
    void* m_pvVal2; /**< 成员2 */
} TStructType;




/** 
 * @defgroup Module_MiscInterface 杂项接口 （这里是一个模块）
 * @{
 */
int func(int& ri32Val, EDayOfWeek enDay, CExample& roExample);
/** @} Module_MiscInterface */




//
// 列表
/* 
 * A list of events:
 *  - mouse events
 *   -# mouse move event
 *   -# mouse click event \n
 *      More info about the click event.
 *   -# mouse double click event
 * - keyboard events
 *  -# key down event
 *  -# key up event
 *
 * More text here.
 */




//
// example.cpp
/**
 * @copyright Copyright (C) 2008-2012, ABC Corporation. All rights reserved.
 * @file example.cpp（文件也可以在一个模块中，使用 ingroup指令指定其所属的模块）注意文件名必须正确，否则无法链接
 * @brief 这里是文件example.h的说明
 * @author 某某某
 * @version 0.1
 * @date 2012-04-08
 */




#include "example.h"




/** 
 * @brief 打开文件 （这里是函数的说明）
 * @param [in] file_name 文件名字符串 （这里是参数说明）
 * @param [in] file_mode 文件打开模式字符串，可以由以下几个值组合而成：
 *  - r 只读
 *  - w 只写
 *  - a 添加
 *  - t 文本模式(不能与 b 联用)
 *  - b 二进制模式(不能与 t 联用)
 * @return 返回文件编号 （这里是返回值说明）
 *  - -1 表示打开文件失败 （只有一条的说明）
 * @note 文件打开成功后，必须使用 ::CloseFile 函数关闭 （这里是注解，注意函数名前后有空格，否则不能链接，其它地方类似）
 * @par 示例代码: （这里是一个段落）
 * @code （这里是引用代码块的开始）
    // 用文本只读方式打开文件
    int f = OpenFile("d:\\test.txt", "rt");
 * @endcode （这里是引用代码块的结束）
 * @see ::ReadFile ::WriteFile ::CloseFile （这里是相关的参考）
 * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。（这里是接口可能弃用的说明）
 */
int OpenFile( const char* file_name, const char* file_mode )
{
    return 0;
}




/** 
 * @brief 读取文件 
 * @param [in] file 文件编号，参见： ::OpenFile 
 * @param [out] buffer 用于存放读取的文件内容
 * @param [in] len 需要读取的文件长度
 * @return 返回读取文件的长度
 *  - -1 表示读取文件失败
 * @pre \e file 变量必须使用 ::OpenFile 返回值 （这里是前置条件， \e 表示斜体 \b 表示黑体）
 * @pre \e buffer 不能为 NULL
 * @see ::OpenFile ::WriteFile ::CloseFile
 */
int ReadFile(int file, char* buffer, int len)
{
    return 0;
}




/** 
 * @brief 写入文件 
 * @param [in] file 文件编号，参见：::OpenFile
 * @param [in] buffer 用于存放将要写入的文件内容
 * @param [in] len 需要写入的文件长度
 * @return 返回写入的长度
 *  - -1 表示写入文件失败
 * @pre \e file 变量必须使用 ::OpenFile 返回值
 * @see ::OpenFile ::ReadFile ::CloseFile
 */
int WriteFile(int file, const char* buffer, int len)
{
    return 0;
}




/** 
 * @brief 关闭文件 
 * @param [in] file 文件编号，参见：::OpenFile
 * @retval  0 成功 （这里是具体返回值的含义，一般不和return指令一起使用）
 * @retval -1 失败 （这里是具体返回值的含义，一般不和return指令一起使用）
 * @see ::OpenFile ::WriteFile ::ReadFile
 * @deprecated 由于特殊的原因，这个函数可能会在将来的版本中取消。
 */
int CloseFile(int file)
{
    return 0;
}




/**
 * @brief Func1的说明
 * @details 函数Func1的更多说明
 * @param [in] a 参数a
 * @param [in] b 参数b
 * @return 两个参数的和
 */
int CExample::Func1( int a, int b )
{
return a + b;
}




/**
 * @brief Func2的说明 
 * @param [in] c 参数c
 * @return 传入的参数
 */
char* CExample::Func2( char* c )
{
return c;
}




/**
 * @brief Func3的简要说明
 * @details 函数Func3没有参数，也没有返回值
 */
void CExample::Func3()
{




}




/**
 * @brief func的简要说明
 * @details func的详细说明
 * @param [in,out] ri32Val 既是入参又是出参
 * @param [in] enDay 参数2的说明
 * @param [in] roExample 参数3的说明
 * @retval 0 成功
 * @retval 其它 失败
 * @note 这里是注解
 * @attention 这里是注意事项
 * @warning 这里是警告信息
 * @see EDayOfWeek CExample g_i32GlobalVal
 * @exception 异常描述，表示本函数可能抛出的异常
 * @bug Not all memory is freed when deleting an object of this class.
 */
int func(int& ri32Val, EDayOfWeek enDay, CExample& roExample)
{
    return 0;
}

配置：

下面的配置设置输出语言为中文

下面的配置设置源代码文件的编码，中文为GBK

下面的配置用于生成条件编译块包围的文档，例如：

#if (defined(__linux__))
/** 
 * @brief BOOL类型
 * @details 变量前缀：[b]，不要使用系统的bool类型 */
typedef enum
{
    FALSE = 0, /**< 假 */
    TRUE = 1   /**< 真 */
} BOOL;
#endif