Doxygen + graphviz + Windows Help Workshop代码文档生成工具

1.Doxygen

Doxygen能将程序中的特定批注转换成为说明文件。它可以依据程序本身的结构，将程序中按规范注释的批注经过处理生成一个纯粹的参考手册，通过提取代码结构或借助自动生成的包含依赖图（include dependency graphs）、继承图（inheritance diagram）以及协作图（collaboration diagram）来可视化文档之间的关系， Doxygen生成的帮助文档的格式可以是CHM、RTF、PostScript、PDF、HTML等。
下载地址 https://www.doxygen.nl/download.html

2.graphviz

Graphviz(Graph Visualization Software)是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。要使用Doxygen生成依赖图、继承图以及协作图，必须先安装graphviz软件。
下载地址 https://graphviz.org/download/

3.HTML Help WorkShop

微软出品的HTML Help WorkShop是制作CHM文件的最佳工具，它能将HTML文件编译生成CHM文档。Doxygen软件默认生成HTML文件或Latex文件，我们要通过HTML生成CHM文档，需要先安装HTML Help WorkShop软件，并在Doxygen中进行关联
下载地址 https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads

规范

规范综述

简要的说，Doxygen注释块其实就是在C、C++注释块的基础添加一些额外标识,使Doxygen把它识别出来, 并将它组织到生成的文档中去。
在每个代码项中都可以有两类描述：一种就是brief描述,另一种就是detailed。两种都是可选的，但不能同时没有。简述(brief)就是在一行内简述地描述。而详细描述(detailed)则提供更长,更详细的文档。
在Doxygen中,主要通过以下方法将注释块标识成详细(detailed)描述:

JavaDoc风格，在C风格注释块开始使用两个星号’*’：

/**
*  ... 描述 ...
*/

Qt风格代码注释,即在C风格注释块开始处添加一个叹号’!’:

/*!
* ... 描述 ...
*/

使用连续两个以上C++注释行所组成的注释块, 而每个注释行开始处要多写一个斜杠或写一个叹号：

///
/// ... 描述 ...
///

同样的，简要说明（brief）有也有多种方式标识，这里推荐使用@brief命令强制说明，例如

/** 
* @brief 简要注释Brief Description. 
*/

```css
/** 
* @brief 简要注释Brief Description. 
*/

**注意以下几点：**

1.Doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、全局变量、宏等注释，而忽略函数内局部变量、代码等的注释。
2.注释应写在对应的函数或变量前面。JavaDoc风格下，自动会把第一个句号"."前的文本作为简要注释，后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF或者QT_AUTOBRIEF设为YES。
3.先从文件开始注释，然后是所在文件的全局函数、结构体、枚举变量、命名空间→命名空间中的类→成员函数和成员变量。
4.Doxygen无法为DLL中定义的类导出文档。

```cpp
@file

档案的批注说明。

@author

作者的信息

@brief

用于class 或function的批注中，后面为class 或function的简易说明。

@param

格式为

@param arg_name 参数说明

主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。

@return

后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。

@retval

格式为

@retval value 传回值说明

主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

异常

模块
Modules是一种归组things在分离的page上的方式。组的成员可以是file，namespace，classes，functions，variables，enums，typedefs和defines，但也可以是其他groups。
要定义一个group，应该在一个特殊注释块放置\defgroup。命令的第一个参数应该是唯一标志该group的标签。要将一个entity归为某个group的一个member，在entity前放置\ingroup命令。第二个参数是group的title。
要避免在注释中每个member前放置\ingroup命令，可以将member用@{和@}封装起来。@{@}标记可以放置group的注释中，也可以在一个独立的注释块
使用这些group的标记符号groups也可以嵌套。
如果多次使用一个group标签，将会出错。如果不希望doxygen强行执行唯一标签，可以使用\addtogroup而非\defgroup。运作方式和\defgroup很像，但是如果该group已经定义，它默认向已存在的注释中添加一个新的项。Group的title对此命令是可选的，也可以考虑使用它。

/*

• @defgroup 模块名 模块的说明文字
• @{
  /
  … 定义的内容 …
  /* @} */
  // 模块结尾这样可以在其他地方以更加详细的说明添加members到一个group。

如果一个compound（例如一个class或file）有多个members，通常我们希望将其group。Doxygen已经可以自动按照类型和protection级别将这些things归组在一起，但可能你会认为仅仅这样是不够的或者这种缺省的方法是错误的。例如你认为有不同（语法）的类型需要归入同一个group（语意）。
这样定义一个member group：

//@{
…
//@}
块或者使用。

/@{/
…
/@}/

注释实例
1.文件注释
举例说明如下，在代码文件头部写上这段注释。可以看到可以标注一些文本名称、作者、邮件、版本、日期、介绍、以及版本详细记录。

/**
  * @file     	sensor.c
  * @author   	aaa
  * @email   	aaa@163.com
  * @version	V1.0
  * @date    	20211231
  * @license  	aaa
  * @brief   	aaaa
  * @detail		detail
  * @attention
  *  This file is aaaaaaaaa.   					            					\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V1.0|aaa|20211231|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  

2.类和成员注释

/**

• @class <class‐name> [header‐file] [<header‐name]
• @brief brief description
• @author
• @note
• detailed description
  */
  如果对文件、结构体、联合体、类或者枚举的成员进行文档注释的话,并且要在成员中间添加注释,而这些注释往往都是在每个成员后面。为此,可以使用在注释段中使用’<'标识。

int var; /**< Detailed description after the member */
对一个类的注释例子如下：

class Test
{
public:
    /** @brief A enum, with inline docs */
    enum TEnum 
    {
        TVal1, /**< enum value TVal1. */ 
        TVal2, /**< enum value TVal2. */ 
        TVal3 /**< enum value TVal3. */ 
    } 
   *enumPtr, /**< enum pointer. */
    enumVar; /**< enum variable. */
    /** @brief A constructor. */ 
Test(); 
/** @brief A destructor. */ 
~Test();
 /** @brief a normal member taking two arguments and returning an integer value. */ 
    int testMe(int a,const char *s); 

    /** @brief A pure virtual member. 
    * @param[in] c1 the first argument. 
    * @param[in] c2 the second argument. 
    * @see testMe() 

3.函数注释

直接看案例如下，见明知意，不在赘述。

	/**
		* @brief		can send the message
		* @param[in]	canx : The Number of CAN
		* @param[in]	id : the can id	
		* @param[in]	p : the data will be sent
		* @param[in]	size : the data size
		* @param[in]	is_check_send_time : is need check out the time out
		* @note	Notice that the size of the size is smaller than the size of the buffer.		
		* @return		
		*	+1 Send successfully \n
		*	-1 input parameter error \n
		*	-2 canx initialize error \n
		*	-3 canx time out error \n
		* @par Sample
		* @code
		*	u8 p[8] = {0};
		*	res_ res = 0; 
		* 	res = can_send_msg(CAN1,1,p,0x11,8,1);
		* @endcode
		*/							
	extern s32 can_send_msg(const CAN_TypeDef * canx,
							const u32 id,
							const u8 *p,
							const u8 size,
							const u8 is_check_send_time);	

打开注释网页后展示如下。

4.枚举注释

直接看案例如下，见明知意，不在赘述。

/** bool */  
typedef enum
{
    false = 0,  /**< FALSE 0  */
    true = 1    /**< TRUE  1  */
}bool;

5.全局变量和宏

6.模块注释
Group定义命令的优先级（从高到低）：\ingroup，\defgroup，\addtogroup，\weakgroup。而\weakgroup很像一个有低优先级的\addtogroup。它被设计为实现一个“lazy”的group定义方法：可以在.h文件中使用高优先级来定义结构，在.cpp文件中使用\weakgroup这样不会重复.h文件中的层次结构。
在实际使用中，我们可以看到具体的网页展示如下。

在图中有个BSP下的LED模块，这个模块就是承载驱动文件LED。具体代码如下，为了显示效果，我把函数的注释删除了。

/**
  * @file     	aa.h
  * @author   	aaa
  * @email   	aaa@163.com
  * @version	V1.01
  * @date    	20211231
  * @license  	aaa
  * @brief   	Controller Area Network
  * @detail		detail
  * @attention
  *  This file is part of aaa		\n
  *   																			\n
  * @htmlonly 
  * <span style="font-weight: bold">History</span> 
  * @endhtmlonly 
  * Version|Auther|Date|Describe
  * ------|----|------|-------- 
  * V1.0|aaa|20211231|Create File
  * <h2><center>&copy;COPYRIGHT 2017 WELLCASA All Rights Reserved.</center></h2>
  */  
/** @addtogroup  BSP
  * @{
  */
/**
  * @brief Light Emitting Diode
  */
/** @addtogroup LED 
  * @{
  */ 
#ifndef __LED_H__
#define __LED_H__
#ifdef __cplusplus
extern "C" {
#endif 
	#include "bsp.h"
	extern s32  led_init(Led_TypeDef led);
	extern s32 	led_config(void);
	extern s32  led_on(Led_TypeDef led);
	extern s32  led_off(Led_TypeDef led);
	extern s32  led_toggle(Led_TypeDef led);
#ifdef __cplusplus
}
#endif
#endif  /*__LED_H__ */
/**
  * @}
  */
/**
  * @}
  */
/******************* (C)COPYRIGHT 2021 aaa All Rights Reserved. *****END OF FILE****/

前面说明了是C语言的，C语言没有继承一说，在C++中有时候需要展示继承。