时间戳

首页 > 技术文章 > 代码文档生成工具Doxygen的使用备忘

代码文档生成工具Doxygen的使用备忘

tyw66 原文

Doxygen备忘

下载与安装

一般步骤

  • 生成配置文件Doxyfile: doxygen (-s) -g
  • 建立目录结构, 比如Doxyfile文件doc文件夹(输出)src文件夹(放代码) ->三者在同一目录下
  • 根据情况设置配置文件中的参数(关键)
  • 运行doxygen Doxyfile生成大概结构
  • 针对每个代码文件写doxygen注释
  • 继续运行doxygen Doxyfile

配置文件Doxyfile设置

DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "Project Name"
PROJECT_NUMBER         = 1.0
PROJECT_BRIEF          = "This is a brief descript."
EXTRACT_ALL            = YES
OUTPUT_DIRECTORY       = "./doc"
OUTPUT_LANGUAGE        = Chinese
FULL_PATH_NAMES        = NO
WARN_LOGFILE           ="./doc/build.log"
INPUT                  ="./src"
FILE_PATTERNS          =
SOURCE_BROWSER         = NO
GENERATE_LATEX         = NO
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
UML_LOOK               = YES
RECURSIVE              = YES

各种注释规范

文件注释

	/**
	* Copyright (c) 2017, All rights reserverd.
	* 
	* @file $file$
	* @brief $brief$
	* Details.
	* 
	* @author  $author$,$email$
	* @date  $yy$-$mm$-$dd$
	* @version   $maj$.$min$
	*
	*************************************************/

命名空间

	/**
	* @brief $brief$
	* Details.
	**/

结构体枚举

	/** 
	* @brief $brief$
	* Details.
	**/

类注释

	/**
	* @brief $brief$
	* Details.
	**/

成员变量注释

  1. 在变量上面加
    /** 成员变量描述 */
  2. 在变量后面加
    /**<成员变量描述 */

函数注释

	/** 
	* @brief $brief$-$test$
	* Details.
	* @param $param1$ : $param1_detail$
	* @param $param2$ : $param2_detail$
	* @return $return_detail$
	*        -<em>false</em> fail
	*        -<em>true</em>  succeed
	* @retval $return_note$
	* @deprecated $deprecated$
	* @see $see$
	* @pre $pre$
	**/

备注:

  • note：指定函数注意项事或重要的注解指令操作符
    note格式如下：
    @note 简要说明

  • retval：指定函数返回值说明指令操作符。(注:更前面的return有点不同.这里是返回值说明)
    retval格式如下：
    @retval 返回值 简要说明

  • pre：指定函数前置条件指令操作符
    pre格式如下：
    @pre 简要说明

  • par：指定扩展性说明指令操作符讲。（它一般跟code、endcode一起使用 ）
    par格式如下：
    @par 扩展名字

  • code、endcode：指定
    code、endcode格式如下：
    @code
    简要说明(内容)
    @endcode

  • see：指定参考信息。
    see格式如下：
    @see 简要参考内容

  • deprecated：指定函数过时指令操作符。
    deprecated格式如下：
    @deprecated 简要说明　
    调试Bug说明
    解决的bug说明，@bug
    警告说明 (warning)
    定义一些关于这个函数必须知道的事情，@warning
    备注说明 (remarks)
    定义一些关于这个函数的备注信息，@remarks
    将要完成的工作 (todo)
    说明哪些事情将在不久以后完成，@todo
    使用例子说明 (example)
    例子说明，@example example.cpp

关键字收集

@author          作者
@brief             摘要
@version         版本号
@date             日期
@file                文件名，可以默认为空，DoxyGen会自己加
@class             类名
@param           函数参数
@return           函数返回值描述
@exception      函数抛异常描述
@warning         函数使用中需要注意的地方
@remarks        备注
@see               see also字段
@note             brief下空一行后的内容表示详细描述，但也可以不空行用note表示
@par               开始一个段落，段落名称描述由你自己指定，比如可以写一段示例代码
@code             引用代码段
@endcode        引用代码段结束
@pre               函数前置条件，比如对输入参数的要求
@post             函数后置条件，比如对系统状态的影响或返回参数的结果预期


@param[in|out]     参数名及其解释
@exception            用来说明异常类及抛出条件
@return                   对函数返回值做解释
@note                      表示注解，暴露给源码阅读者的文档
@remark                表示评论，暴露给客户程序员的文档
@since                   表示从那个版本起开始有了这个函数
@deprecated        引起不推荐使用的警告
@see                      表示交叉参考

推荐阅读