基于STM32的Doxygen使用简明手册

基于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>&copy; 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

&copy

©

版权标志

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

四、.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。