doxygen的安装与配置

来源：互联网发布：sql库位库存分配编辑：程序博客网时间：2024/06/06 21:38

<div id="article_content" class="article_content tracking-ad" data-mod="popu_307" data-dsm="post">

最近接触了一款程序文档生成工具-Doxygen。在网上一搜索原来这么多人知道，打算把它的使用做一个总结，以及其注释的规则。
<h1><a name="t0" target="_blank"></a>概述：</h1>

 Doxygen是一种开源跨平台的，以类似JavaDoc风格描述的文档系统，完全支持C、C++、<a target="_blank" href="http://lib.csdn.net/base/javaee" class="replace_word" title="Java EE知识库" style="text-decoration:none; color:rgb(223,52,52); font-weight:bold">Java</a>、<a target="_blank" href="http://baike.baidu.com/view/459423.htm" style="text-decoration:none; color:rgb(19,110,194); font-family:arial,宋体,sans-serif; line-height:24px; text-indent:28px"></a><a target="_blank" href="http://lib.csdn.net/base/objective-c" class="replace_word" title="Objective-C知识库" style="text-decoration:none; color:rgb(223,52,52); font-weight:bold">Objective-C</a>和IDL语言，部分支持<a target="_blank" href="http://lib.csdn.net/base/php" class="replace_word" title="PHP知识库" style="text-decoration:none; color:rgb(223,52,52); font-weight:bold">PHP</a>、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档<a target="_blank" href="http://baike.baidu.com/view/385166.htm" style="text-decoration:none; color:rgb(19,110,194); font-family:arial,宋体,sans-serif; line-height:24px; text-indent:28px">源文件</a>开始，生成HTML格式的在线类<a target="_blank" href="http://baike.baidu.com/view/7718.htm" style="text-decoration:none; color:rgb(19,110,194); font-family:arial,宋体,sans-serif; line-height:24px; text-indent:28px">浏览器</a>，或离线的LATEX、RTF参考手册。Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。通常我们在写程序时，或多或少都会写上批注，但是对于其它人而言，要直接探索程序里的批注，与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式，类别等等的说明。所以，如果能依据程序本身的结构，将批注经过处理重新整理成为一个纯粹的参考手册，对于后面利用您的程序代码的人而言将会减少许多的负担。不过，反过来说，整理文件的工作对于您来说，就是沉重的负担。

Doxygen 就是在您写批注时，稍微按照一些它所制订的规则。接着，他就可以帮您产生出漂亮的文档了。因此，Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写，第二便是利用Doxygen的工具来产生文档。
<h1 style="margin-top:0px; margin-bottom:0px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); font-family:Arial; line-height:26px"><a name="t1" target="_blank"></a>
工具的准备 </h1>
<div>本人已经下载了这三个软件，打包后放在：<a target="_blank" href="http://download.csdn.net/detail/andy_93/9679898">点击打开链接</a> 
</div>

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t2" target="_blank"></a>
Doxygen下载</h2>


下载地址：<a target="_blank" href="http://www.onlinedown.net/soft/117010.htm" style="text-decoration:none; color:rgb(0,103,96); font-family:'Microsoft YaHei','Helvetica Neue',SimSun; line-height:21px">http://www.onlinedown.net/soft/117010.htm</a> 

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t3" target="_blank"></a>
htmlhelp下载</h2>

如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll。 下载地址：  <a target="_blank" href="http://msdn.microsoft.com/en-us/library/ms669985.aspx" style="font-family:'Microsoft YaHei','Helvetica Neue',SimSun; line-height:21px">http://msdn.microsoft.com/en-us/library/ms669985.aspx</a>
<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t4" target="_blank"></a>
Graphviz的下载</h2>



graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。

下载地址：<a target="_blank" href="http://www.skycn.com/soft/appid/6971.html" style="color:rgb(0,103,96); text-decoration:none; font-family:'Microsoft YaHei','Helvetica Neue',SimSun; line-height:21px">http://www.skycn.com/soft/appid/6971.html</a> 

<h1 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t5" target="_blank"></a>
Doxygen工具的配置</h1>

在安装好开始配置Doxygen工具，运行Doxywizard。会出现以下界面

<img src="http://img.blog.csdn.net/20161111110948949?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t6" target="_blank"></a>
配置工作目录</h2>

点击Select选择自己的Doxygen的安装目录

<img src="" alt=""><img src="" alt=""><img src="http://img.blog.csdn.net/20161111110715868?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t7" target="_blank"></a>
配置Wizard选项卡</h2>
<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t8" target="_blank"></a>
配置Project</h3>

首先修改Project name，选择扫描源代码的目录，Source code directory：，勾选Scan recursively  （递归扫描），之后选择输出目录。

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110720356?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t9" target="_blank"></a>
配置Model</h3>

在Wizard的Topics下的Mode，选择All Entities，可以输出相对完整的功能，是否包含源代码看你自身情况，在下面选择好你的语言。这里作者使用的是C++

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110725915?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3><a name="t10" target="_blank"></a>配置Output</h3>


在Output中，如果你需要输出chm格式，请勾选。

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110730794?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3><a name="t11" target="_blank"></a>配置Diagrams</h3>


在Diagrams中选择使用GraphViz包，来输出UML 


<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110735571?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t12" target="_blank"></a>
配置expert选项卡</h2>
<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t13" target="_blank"></a>
配置project</h3>



说明：编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312. 


TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110739763?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t14" target="_blank"></a>
配置Build</h3>



Build页面，这个页面是生成帮助信息中比较关键的配置页面：

EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。

EXTRACT_PRIVATE 表示：输出private函数。

EXTRACT_STATIC 表示：输出static函数。同时还有几个EXTRACT，相应查看文档即可。

SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列

表。

INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显

示。
<img src="http://img.blog.csdn.net/20161111110744353?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t15" target="_blank"></a>
配置Input</h3>



说明：INPUT_ENCODING (输入的源文件的编码)，要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

总结：我查看到我的代码文件是utf-8的（vs2013中打开文件选另存为可看到编码格式）（（VS2012的话）：文件->高级保存选项)。

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110748638?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t16" target="_blank"></a>
配置HTML</h3>



在Expert的HTML中，首先要看HHC_LOCATION选项，添加安装目录（注：作者目录为C:/Program Files (x86)/HTML Help Workshop/hhc.exe）

勾选CHM_INDEX_ENCODING，在你源代码中的字符集是什么就填写什么，

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110755275?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h3 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t17" target="_blank"></a>
配置dot</h3>



之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK 

<div style="color:rgb(85,85,85); font-family:'microsoft yahei'; line-height:35px">

为了减少chm体积，在DOT_IMAGE_FORMAT中选择gif或者jpg，均可。

最后选择好DOT_PATH所输出的位置。
</div>

<img src="http://img.blog.csdn.net/20161121104950944?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 

<h2 style="margin-top:8px; margin-bottom:8px; padding-top:0px; padding-bottom:0px; color:rgb(51,51,51); line-height:22.5px; letter-spacing:0.5px; font-family:微软雅黑,Verdana,sans-serif,宋体"><a name="t18" target="_blank"></a>
Run选项卡</h2>

点击点击 Run doxygen 按钮， Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110815076?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 


假如运行时遇到这个错误



Error: When enabling GENERATE_HTMLHELP the search engine (SEARCHENGINE) should be disabled. I'll do it for you.

warning: The selected output language "chinese" has not been updated

since release 1.8.2. As a result some sentences may appear in English.

解决：把HTML里面的SEARCHENGINE设置为NO

<img src="" alt=""><img src="http://img.blog.csdn.net/20161111110832854?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 


到此chm文件生产完毕，为了下次代码调整后再次生产chm文件此时我们可以将目前所做的工作进行保存，点击File->Save,如下图： 


<img src="" alt=""><img src="http://img.blog.csdn.net/20161111111215281?watermark/2/text/aHR0cDovL2Jsb2cuY3Nkbi5uZXQv/font/5a6L5L2T/fontsize/400/fill/I0JBQkFCMA==/dissolve/70/gravity/Center" alt=""> 



<div style="color:rgb(50,62,50); font-family:'Microsoft YaHei','Helvetica Neue',SimSun; line-height:21px">
后期使用可以通过步骤2中的file下的open菜单打开重新调整设置生产新的chm文件。好了Doxygen的安装与配置就讲到这里！</div>
<div style="background-color:rgb(255,255,255)"> 
</div>
<h1 style="background-color:rgb(255,255,255)"><a name="t19" target="_blank"></a>注释规范</h1>
<div>以下是想使用doxygen工具生成程序文档需要在代码中遵守的注释规范(不全)： 

<h2><a name="t20" target="_blank"></a>头文件模板:</h2>
/** @brief 这里写你的摘要 
 *  @file 你的文件名 
 *  @author 谁tmd的搞的 
 *  @version 版本了 
 *  @date  你啥时候搞的 
 *  @note       注解. 例如: 本文件有什么具体功能啊,使用时要注意什么啊….. 
 *  @since    自从  例如: 自从2012年地球爆炸后这个文件就从地球上消失了….. 
 */ 
 
几句费话: 
 美中不足的是它没有修改历史记录. 我只能用@since来暂时代替它了. 
 除开始和结尾中间 @前的*不是必须的,这里只是为了美观. 
 

<h2><a name="t21" target="_blank"></a>函数的注释:</h2>
/**  这里写这个函数是干什么用的 
 @param[in]  输入参数1 
 @param[in]  输入参数2 
 @param[out]  输出参数1 
 @return    返回值解释一下 
 @warning 警告: 例如: 参数不能为空啊,内存要外部释放之类的费话 
 @note 注解  随便你了 
 @see                相当于是请参考xxoo函数之类的 
*/ 
 
费话: 
这些东西并不是固定的你要哪几个就写哪几个. 
 
 
关于返回值也可以这样搞 
@retval 1 成功 
@retval 0 失败 
 
 
有时我们可能会写段示例代码在注释中这样搞: 
在你的注释中加入这样的代码 
@par 示例: 
@code 
extern  IThread *pThread; 
HANDLE hEvent = pThread->GetEventHandle(); 
while(WaitForSingleObject(hEvent,0) != WAIT_OBJECT_0) 
{ 
//Do something 
} 
@endcode 
 
 
还有几个你可能用上的东东: 
@todo       //我觉得这个描述算法比较好 
@exception   // 这个应该是用来说明你这个函数会抛出什么异常 
@deprecated  //这个函数可能在以后的版本中取消所谓的什么过时列表 
 
 
eg: 
/**  构造函数  
 @param[in]  pConfig 指向 TASKCONFIG 结构体的指针 
 @param[in]  strWndName 目标窗口的名称, 如果此参数为空则不和任何窗口交互 
 @param[in]  hRes 欲使用的资源句柄,如果参数为空则不使用资源 
 @warning    pConfig 不能为空  
 @note     申请 pConfig 内存 
 @see     IThread 
*/ 
CThread_Plug(TASKCONFIG *pConfig,LPCTSTR strWndName,HINSTANCE hRes); 
 
 
变量或者只有一行注解的东东,不超过一行的注释: 
 /**< 在这里写你要加的东西 */ 
OR 
///< 在这里写你要加的东西 
 
 
eg: 
HINSTANCE m_hRes; ///< 要使用的资源句柄 
CString  _strWndName; ///< 目标接收消息的窗口名称 
 

<h2><a name="t22" target="_blank"></a>常用指令介绍</h2>
@file 档案的批注说明。 
@author 作者的信息 
@brief 用于class 或function的简易说明 eg：@brief 本函数负责打印错误信息串 
@param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明 
@return 描述该函数的返回值情况eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE 
@retval 描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。 
@note 注解 
@attention 注意 
@warning 警告信息 
@enum 引用了某个枚举，Doxygen会在该枚举处产生一个链接 eg：@enum CTest::MyEnum 
@var 引用了某个变量，Doxygen会在该枚举处产生一个链接 eg：@var CTest::m_FileKey  
@class 引用某个类，格式：@class <name> [<header-file>] [<header-name>] eg:@class CTest "inc/class.h" 
@exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常 
@todo 对将要做的事情进行注释 
@see 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。 
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。 
@since 通常用来说明从什么版本、时间写此部分代码。 
@code  在注释中开始说明一段代码，直到@endcode命令。 
@endcode  在注释中代码段的结束。 
@pre 用来说明代码项的前提条件。 
@post 用来说明代码项之后的使用条件。 
@deprecated 这个函数可能会在将来的版本中取消。 
@defgroup 模块名 
@class 声明一个类  
@fn 声明一个函数 
</div>

doxygen的安装与注释规范就写到这里了，赶紧去试试吧！


</div>

阅读全文

0 0