Doxygen(一) - 入门篇

---

前言

介绍了Doxygen常用注释标记、注释编写和使用doxywizard的方法。

---

一、常用注释标记表格

注释标记	含义
@brief	简要描述
@param	对函数参数进行描述
@return	对函数返回值进行描述
@throws	对函数可能抛出的异常进行描述
@see	链接到其他相关的函数、类或文档
@note	补充额外的说明
@deprecated	标记为已过时、已失效或不推荐使用
@code / @endcode	用于标记代码块
@file	对文件进行描述
@namespace	对命名空间进行描述
@class / @struct	对类或结构体进行描述
@enum	对枚举类型进行描述
@var	对变量进行描述
@defgroup / @addtogroup	对相关的函数进行分组
@mainpage	标记为主页，用于生成文档的首页
@page	创建自定义页面，并在索引中添加链接
@section / @subsection / @subsubsection	创建章节、子章节
@link / @endlink	可以链接函数、变量、类
@image	插入图片
@example	插入代码示例

二、编写注释

1.注释块格式 - Javadoc样式

/**
 * ... text ...
 */

2.文件注释

/**
* @file        Test.h
* @brief       简介.
* @details     详细描述.
* @author      作者
* @date        2023/08/31
* @version     1.0
*/

3.函数注释

/**
* @brief 函数功能说明
* @param[in] param1 输入参数1含义
* @param[in] param2 输入参数2含义
* @param[out] param3 输出参数3含义
* @return 返回值 @link STATUS_OK @endlink
* @code
* 示例代码片段
* @endcode
*/
int setFunction(int param1, int param2, int *param3); 

4.结构体注释

/** @brief 结构体含义 */
typedef struct _TestStruct
{
	/** @brief param1含义 */
	int param1; 
	/** @brief param2含义 */
	int param2; 
	/** @brief param3含义 */
	int param3; 
}TestStruct; 

5.枚举注释(归类到Enum define组)

/**
 * @addtogroup EnumGroup Enum define
 * @{
 */

/** @brief 星期定义*/
typedef enum _Weekday
{
    /** @brief 星期一*/
    Monday = 1,
    /** @brief 星期二*/
    Tuesday = 2,
    /** @brief 星期三*/
    Wednesday = 3,
    /** @brief 星期四*/
    Thursday = 4,
    /** @brief 星期五*/
    Friday = 5,
    /** @brief 星期六*/
    Saturday = 6,
    /** @brief 星期日*/
    Sunday = 7
	
}Weekday; 

/**
 * @}
 */

6.插入图片

* @image html image.png "Figure1"

7.插入表格

/**
 * <table>
 * <caption>表格标题</caption>
 * <tr><th>表头1                                  <th>表头2     <th>表头3     <th>表头4     <th>表头5
 * <tr><td>行1列1                                 <td>行1列2    <td>行1列3    <td>行1列4    <td>行1列5
 * <tr><td rowspan="5">合并第一列(第2行到第6行)    <td>行2列2    <td>行2列3    <td>行2列4    <td>行2列5
 * <tr>                                           <td>行3列2    <td>行3列3    <td>行3列4    <td>行3列5
 * <tr>                                           <td>行4列2    <td>行4列3    <td>行4列4    <td>行4列5
 * <tr>                                           <td>行5列2    <td>行5列3    <td>行5列4    <td>行5列5
 * <tr>                                           <td>行6列2    <td>行6列3    <td>行6列4    <td>行6列5
 * <tr><td>行7列1                                 <td>行7列2    <td>行7列3    <td>行7列4    <td>行7列5
 * <tr><td colspan="5">合并第8行(第1列到第5列)                                              
 * <tr><td>行9列1                                 <td>行9列2    <td>行9列3    <td>行9列4    <td>行9列5
 * </table>
 */

三、使用doxywizard生成chm\HTML

3.1 Wizard->Project

3.2 Wizard->Mode

3.3 Wizard->Output

选择输出格式为HTML(.chm)

3.4 Wizard->Diagrams

如果要生成调用关系图需要安装GraphViz工具

3.5 Expert->Project

3.6 Expert->Project

CHM_FILE：配置输出的chm文件名；

HHC_LOCATION：输入windows HTML Help Workshop hhc.exe安装路径；

3.7 运行

先保存下doxygen配置文件，下次就可以直接导入，不用再手动设置一边。

点击Run doxygen生成chm手册。如果沈城失败，请根据生成过程中的日志定位原因。

---

总结

介绍了Doxygen注释编写和使用doxywizard.exe的方法，方便快速上手。