【VA】使用Visual Assist X进行快捷doxygen模板注释

【VA】使用Visual Assist X进行快捷doxygen模板注释

Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言。使用doxygen方式注释，可以生成HTML及chm等格式的开发文档。

利用assistX工具，可以设置doxygen模板，快捷地生成代码注释。

安装好Visual Assist X后，打开VC开发工具。这里以VS2010为例。点击Visual Assist X Options，即工具栏上的番茄图标或菜单栏VassistX-Visual Assist X Options，会弹出设置对话框，点击Suggestions-Edit VA Snippets，如下图：

新建自定义的模板。

1. 函数注释模板。

        Title: doxyen method
   
        Shortcut: //M        
   

/**

  *  @brief  Thisis a brief description.

  *  @param[in]  inArgName input argument description.type name:purpose(Range)

  *  @param[out] outArgName output argument description.

  *  @Return:    $SymbolType$:description of the return value

  *  - TRUE

  *  - FALSE

  *

  *  @note   matters needing attention

  *  @see    other functions   

  */

2. 头文件注释模板

在assistX中设置的方法与函数注释模板类似。

	Title: doxyen file header

    Shortcut: //F

/**

  * @file   $FILE_BASE$.$FILE_EXT$

  * @brief Thisis a brief description.

  * @author $Author$

  * @par   Copyright (c):

  *          $Author$.

  *         All Rights Reserved

  * @date   $YEAR$:$MONTH_02$:$DAY_02$ 

  *  @note   mattersneeding attention

  *  @version <version  number>

  */ 

3. 类文件注释模板

在assistX中一般设置。

	Title: doxyen class

    Shortcut: //C

/**

  * @class <class‐name>

  *  @brief  This is a brief description.

  *  @note   mattersneeding attention

 */

4. 其他doxygen注释

由于注释都比较简单，就无需放assistX中设置成模板了。

类成员注释：

int var;  ///<  Brief description  after  the member

枚举类型注释：

/**  @brief   This is a brief description.  */

enum  XXXEnum          

{ 

V1,  /**< value  1  */           

V2   /**< value  2  */         

};

全局变量及宏注释：

/** @brief  some  brief description  */

int g_Var;

或

#define XXXX_XX ///< some  brief  description。

此处同时附上其他常用的doxygen命令列表：

@exception 用来说明异常类及抛出条件

@deprecated 已废弃函数

@details  详细描述

@par  开始一个段落，段落名称描述由你自己指定
@code .. @endcode 包含一段代码
@fn  函数说明
@retval  描述返回值意义
@include 包含文件

@note  表示注解，暴露给源码阅读者的文档

@remark  表示评论，暴露给客户程序员的文档

最后的效果图如下：