自己的一些理解:
(1) @defgroup是用于定义一些分组
(2) @addtogroup 用于把它所包含的分组添加到某个分组里面去,可以嵌套添加
基于STM32的Doxygen使用简明手册
为了能使代码能够被Doxygen识别,必须遵循Doxygen的书写规则。注释必须以/**打头,以*/结束。
一、添加类型
1、 添加首页(mainpage):
格式:
/**
\mainpage RIOM DSP Software Library
*
* <b>Introduction</b>
*
* This user manual describes the CMSIS DSP software library
*/
关键字:
\mainpage
描述:
用以显示在首页中,一般用于对整个工程进行描述。
2、 添加define分组(defgroup):
格式:
/** @defgroup ZHM2
* @{
*/
#define XXX YYY
/**
* @}
*/
关键字:
@defgroup name
@{
@}
描述:
定义一个define分组,用以显示在生成的文件中,一般多出现在.h文件中。
3、 添加到分组(addtogroup)
格式:
/** @addtogroup STM32F2xx_StdPeriph_Driver
* @{
*/
XXXX
/**
* @}
*/
关键字:
@addtogroup name
@{
@}
描述:
把一些东西添加到某个分组中去,该分组可以定义在其他文件下,Doxygen会自动搜索该分组,然后将需要添加的添加到该分组。可以进行跨文件关联。
通过addtogroup可以形成树结构,如果原来不存在该分组,它会自动新建该分组,然后添加到该分组。
4、 文件注释:
格式:
/**
******************************************************************************
* @file main.c
* @author ZhengHangming
* @version V1.0.0
* @date 04/16/2012
* @brief This file provides all the detail functions.
******************************************************************************
* @copy
*
* THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS
* WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE
* TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY
* DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING
* FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE
* CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
*
* <h2><center>© COPYRIGHT 2010 STMicroelectronics</center></h2>
*/
关键字:
@file:文件名,xx.c; zz.h等
@author:作者
@version:版本号
@date:日期
@brief:简介
@copy/@attention:详细描述
描述:
用以说明整个文件的各种信息。
5、 函数注释:
格式:
/**
* @brief Enables or disables the specified DAC channel.
* @param DAC_Channel: The selected DAC channel.
* This parameter can be one of the following values:
* @arg DAC_Channel_1: DAC Channel1 selected
* @arg DAC_Channel_2: DAC Channel2 selected
* @param NewState: new state of the DAC channel.
* This parameter can be: ENABLE or DISABLE.
* @note When the DAC channel is enabled the trigger source can no more be modified.
* @retval None
*/
关键字:
@brief:对函数简要描述
@param:参数说明,以’:’作为参数结束标志;
@arg:参数里面可选择参量列举,对于可数情况可进行参量列举,同样以’:’作为参数结束标志;
@note:注释,配合brief一起使用可以达到很好的注释效果;
@retval:返回值说明。
描述:
对函数体进行说明,包括功能,参数和返回值。
二、字体段落操作
编号 | 功能 | 格式 | 描述 |
1 | <b>****</b> | 以<b>开头,以</b>结束。 | 用以将段落或者字体加粗 |
2 | <h2>***</h2> | 以<h2>开头,以</h2>结束 | 段落加粗加大 |
3 | <center>***</center> | 以<center >开头,以</center >结束 | 段落居中 |
4 | @verbatim***@endverbatim | 以@verbatim开头,以@endverbatim结束 | 用于建立一个框,来说明整个文件或者函数的功能。 |
|
|
|
|
|
|
|
|
三、特殊符号添加:
编号 | 代码 | 效果 | 说明 |
1 | © | © | 版权标志 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
四、.c和.h的常用规范:
1、 .c文件开头定义一些常用规范如下所示。
/* Includes ------------------------------------------------------------------*/
/* Private typedef -----------------------------------------------------------*/
/* Private define ------------------------------------------------------------*/
/* Private macro -------------------------------------------------------------*/
/* Private variables ---------------------------------------------------------*/
/* Private function prototypes -----------------------------------------------*/
/* Private functions ---------------------------------------------------------*/
最后加一个copyright。
2、 .h文件开头的一些常用规范如下所示:
/* Define to prevent recursive inclusion -------------------------------------*/
/* Includes ------------------------------------------------------------------*/
/* Exported types ------------------------------------------------------------*/
/* Exported constants --------------------------------------------------------*/
/* Exported macro ------------------------------------------------------------*/
/* Exported functions --------------------------------------------------------*/
最后加一个copyright。