Doxygen心得(转)

最新推荐文章于 2024-02-19 16:47:54 发布

暴熊

最新推荐文章于 2024-02-19 16:47:54 发布

阅读量4.4k

点赞数

分类专栏： C/C++ VS.NET 文章标签： chm html 文档 graph output encoding

C/C++ 同时被 2 个专栏收录

82 篇文章 0 订阅

订阅专栏

VS.NET

24 篇文章 0 订阅

订阅专栏

doxygen是一款源代码帮助文档生成工具。依靠源代码中的注释，doxygen可以轻松的生成多种格式的帮助文档，供开发者阅读。

doxygen的使用方法很简单：

第一步，需要修改源代码文件，规范现有注释。为了使注释轻松智能的变成可读的文档。doxygen规定了自己的注释格式，这样太才可以解析。最常用的注释格式是：

/**
there is comment.
*/

或
/*!
there is comment.
*/

同时，为了区分注释的用途，doxygen定义了很多关键字，用来标识注释描述的代码段或者用途。常用@后面跟用途关键字来标识，关键字在doxygen附带的帮助文件中有很详细的解析(在Special Commands这一节中)，这里就不在累赘了。这里有一个地方需要注意一下，描述的各个分段之间最好用tab空开，用空格有的时候会出现问题。
如：

/**
* @brief 这是一个函数
* @param a 参数一
* @param b 参数二
* @return 无返回值
*/
void fooFun(int a, int b);

第二步，建立doxygen配置文件。doxygen执行的时候需要一个配置文件，即每生成一个chm都会有一个配置文件来进行生成工程具体信息的描述。手工编写那个配置文件比较繁琐，还好doxygen随身附带了一个DoxyWizard，利用这个向导。你可以方便的配置想要的信息。注意DoxyWizard仅仅是一个界面，他最终编译的时候还是执行了doxygen.exe，传输时不要只拷贝这一个文件。

       打开DoxyWizard，会发现DoxyWizard分成了三个区域。
       在step1中有三个按钮。
             按钮[Wizard...]里面配置项目的一些基本信息
             按钮[Expert...]包含高级配置信息
             按钮[Load...]加载一个doxygen配置文件

在step1中，有个最重要的设置就是在[Wizard...]的Project页面中的Source code directory选项。把这个指向你的源代码文件路径。Scan recursively表示是否递归遍历。

       step1完成之后，你必须要保存一下doxygen配置文件。只需要点击step2的保存按钮即可。
       step3中的工作目录，也就是doxygen最终生成的帮助文档(chm)的存放路径。
       最后，点击step4中的[Start]按钮即可。

在Output列表中。是doxygen生成编译时生成的信息。注意上面已经提到过，DoxyWizard和doxygen是两个不同的进程，所以在DoxyWizard输出日志的时候可能会有停顿。具体显示时候的通信机制我没有看，但这和机器或者doxygen本身的代码没有关系。

我在这里主要讲一些基本常用的属性，很多我觉得意义不大的，请自行研究，这里就不过多解释了。
在[Wizard...]中没有特别复杂的地方，稍微看一眼便知。

在[Expert...]按钮中，有一个tab页，下面来逐一解释：

         Project页面，主要包括项目的基本配置。
             TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议符合习惯，设置成4。
             OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。
             SUBGROUPING这个选项选择后，输出将会按类型分组。

         Build页面，这个页面是生成帮助信息中比较关键的配置页面
             EXTRACT_ALL 表示输出所有的函数，但是private和static函数不属于其管制。
             EXTRACT_PRIVATE 表示输出private函数。
             EXTRACT_STATIC 表示输出static函数。同时还有几个EXTRACT，相应查看文档即可。
             HIDE_UNDOC_MEMBERS 表示那些没有使用doxygen格式描述的文档（函数或类等）就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被忽略的。
             INTERNAL_DOCS 主要指是否输出注解中的@internal部分。如果没有被启动，那么注解中所有的@internal部分都将在目标帮助中不可见。
             CASE_SENSE_NAMES 是否关注大小写名称，注意，如果开启了，那么所有的名称都将被小写。对于C/C++这种字母相关的语言来说，建议永远不要开启。
             HIDE_SCOPE_NAMES 域隐藏，建议永远不要开启。
             SHOW_INCLUDE_FILES 是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
             INLINE_INFO 如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
             SORT_MEMBER_DOCS 如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
             GENERATE_TODOLIST 是否生成TODOLIST页面，如果开启，那么包含在@todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。
             SHOW_USED_FILES 是否在函数或类等的帮助中，最下面显示函数或类的来源文件。
             SHOW_FILES 是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。

         Messages页面主要用来设置编译时的输出信息选项。编译时的输出信息，主要可以用来提醒一些输入的错误语法。
             QUIET 如果开启，那么表示关闭编译时的输出信息。
             WARN_FORMAT 表示日志输出的格式，没必要修改。
             WARN_LOGFILE 表示信息是否输出到LOG文件，因为有DoxyWizard的存在，所以这个选项没有必要使用。

         HTML页面
             CHM_FILE 表示输出的chm文件路径
             GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
             TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
             这个页面关系到生成chm的问题，不过很多选项很简单，一看便知。

Preprocessor 页面是预处理页面，里面也有一些配置，但是个人感觉使用默认就行了。其他的几个页面，基本上都要依赖于某些其他第三方的模块，尽管有些doxygen自带了，但是其详细说明，还得考读者自行研究。

同时附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen自建命令，HTML命令方式和XML命令方式。所有的命令都是以'/'或者'@'字符开头，这表明如果你的注释中有'/'开头的单词，你必须要修改成'//'。

由于doxygen命令比较多，另外就是doxygen的帮助文档也是非常完善，所以，这里仅仅列举几个常用的命令，其他命令请自行参考帮助文件。

@addtogroup 添加到一个组。
@brief  概要信息
@deprecated 已废弃函数
@details 详细描述
@note  开始一个段落，用来描述一些注意事项
@par  开始一个段落，段落名称描述由你自己指定
@param  标记一个参数的意义
@code .. @endcode 包含一段代码
@fn  函数说明
@ingroup 加入到一个组
@return  描述返回意义
@retval  描述返回值意义
@include 包含文件

问题：

如何编译成CHM格式的帮助文件？
       1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。
       2. 首先在[Wizard...]的Output页面中，选择HTML，然后选择到prepare for compressed HTML(.chm)。
       3. 其次在[Expert...]的HTML页面中，将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。然后点击OK，保存，编译即可。

如何像MSDN那样在左边的树中显示函数列表？
打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。

如何去掉CHM附带的CHI文件？
注意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示的情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消GENERATE_CHI即可。

如何像MSDN那样右边每页显示一个函数？
这个问题其实比较棘手，在[Expert...]中的Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在memberlist.cpp的writeDocumentationPage函数中将container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。

如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？

这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽writeGroupIndexItem函数的Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。

如何修改或者去掉右下脚Generated at ...的文字？
打开[Expert...]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理，如果你要指定了HTML_HEADER，他至少包含<HTML><HEAD></HEAD><BODY>

如何生成组？
组就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就被放置在同一个组中。

如何生成中文帮助？

点击[Expert...]，在页Project 的OUTPUT_LANGUAGE，选择Chinese，这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。

如何彻底解决DoxyGen的输出中文chm的乱码问题？

DoxyGen的实现中大概有三处编码的设置。首先是，doxyfile，也就是配置文件。其次，INPUT_ENCODING，也就是DoxyGen需要解析的输入文件的编码。最后，就是输出的编码。譬如CHM左边的索引编码。

首先是chm的标题乱码，这个比较好解决，因为DoxyWizard使用QT做的界面，它内部做了转换，所以在DoxyWizard中输入中文，在保存的时候，他自己做了转码，导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件，输入相应中文即可。注意保存的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM，比较麻烦，没研究了。这个相应的编码设置在[Expert...]中，页Project 的 DOXYFILE_ENCODING，不输入或者默认为UTF-8都行。

其次是右边内容乱码，这个多半是因为你没有配置好输入的文件编码类型造成的。在[Expert...]的Input页面中，有一个INPUT_ENCODING，这个选项表示输入文件的编码方式，这要和你处理的源文件格式一致。对于我们来说（使用vs的人），一般设置为GB2312。当然，再次声明，编码方式取决于源文件的编码方式。如果文件编码已经是UTF-8了，然而你还将其设置成GB2312，那么DoxyGen会将UTF-8当成ANSI再进行一次UTF-8转换，自然会出错了。

最后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下，还有一个瑕疵之处，就是chm的搜索页的搜索结果中显示的中文文字却变成乱码了。这是因为DoxyGen默认开启了HTML Help Workshop的Full-text search全文搜索选项，他在进行全文搜索的时候，应该是打开文件然后按照ANSI进行搜索的，（资料表示HHW不支持UTF-8，仅支持ISO-8859-1或者windows-1252编码。）而Doxygen生成的右边界面统一是UTF-8，这自然出现了问题。而在这种情况下做全文搜索，理论上只能搜索英文。

无奈，我们的解决方案只能是重新编译DoxyGen代码，为了满足搜索，只要保证右边的页面文件不是UTF-8即可。我们首先修改writeDefaultHeaderFile这个函数的代码，将其charset=GB2312。然后在TranslatorDecoder的构造函数中修改m_toUtf8 = (void*)-1;即屏蔽文本写入时最终的转换函数。最后删除INPUT_ENCODING的设置或者输入UTF-8。这样会使DoxyGen认为我们的文本是UTF-8的，从而不用进行转换。生成替换原始的DoxyGen即可。

另外需要补充的是，还有一种方案是不用修改作者的源代码，但是需要将DoxyGen生成的右边的HTML文件使用工具（如iconv）手工转换成GB2312，然后再使用HTML Help Workshop生成，网上有篇文章介绍过，我测试一下，也是没有问题的。

Doxygen可以通过Graphviz开源工具的支持来画出各种图形插入文档中，包括文件include关系、对象继承关系等

更为强大的是，Doxygen生成的这些图形支持交互导航功能（在HTML格式下有效），文档用户只需点击即可切换到相应的页面，十分方便，而所有的这些只需要设置下面这几个简单的配置选项即可：

DOT_PATH = #Graphviz路径

DOT_IMAGE_FORMAT = #图片格式，默认是PNG

CLASS_DIAGRAMS = #是否画类图

COLLABORATION_GRAPH = #是否画协作图

UML_LOOK = #使用UML风格

INCLUDE_GRAPH = #include关系

CALL_GRAPH = # 调用图

GRAPHICAL_HIERARCHY = #继承关系图

配置选项可以被分成几类。下面给出的命令开关（或者说：配置选项）以字母顺序给出：

ABBREVIATE_BRIEF //简短摘要
ALIASES //别名
ALLEXTERNALS //所有外部文档
ALPHABETICAL_INDEX //字母顺序索引
ALWAYS_DETAILED_SEC //详细描述部分
BINARY_TOC //二进制操作
BRIEF_MEMBER_DESC //简短的成员描述
CALL_GRAPH //调用到的图
CASE_SENSE_NAMES //检测的范例的名字
CHM_FILE //CHM格式文件
CLASS_DIAGRAMS //类-表
CLASS_GRAPH //类-图
COLLABORATION_GRAPH //相互调用关系图
COLS_IN_ALPHA_INDEX //以列形式显示的字母顺序的索引
COMPACT_LATEX //压缩的LATEX文档
COMPACT_RTF //压缩的RTF文档
CREATE_SUBDIRS //创建一个"子目录"
DETAILS_AT_TOP //文档的详细头部
DIRECTORY_GRAPH //目录图
DISABLE_INDEX //禁用INDEX
DISTRIBUTE_GROUP_DOC //禁用文档成组显示
DOT_IMAGE_FORMAT //点阵图形
DOT_MULTI_TARGETS //多个DOT目标
DOT_PATH //DOT路径设置
DOT_TRANSPARENT //DOT转换设置
DOTFILE_DIRS //DOTFILE 列表显示
ENABLE_PREPROCESSING //允许"预处理"指令
ENUM_VALUES_PER_LINE //每行的枚举值
ENABLED_SECTIONS //允许分段显示
EXAMPLE_PATH //例子路径
EXAMPLE_PATTERNS //例子用的文件格式（*.cpp, *.h , *.java等）
EXAMPLE_RECURSIVE //例子递归
EXCLUDE //可执行文件
EXCLUDE_PATTERNS //可执行文件格式（*.exe, *.dll等）
EXCLUDE_SYMLINKS //可执行的SYMLINKS
EXPAND_AS_DEFINED //规定的扩展
EXPAND_ONLY_PREDEF //预定义扩展
EXTERNAL_GROUPS //使用到的外部的文件
EXTRA_PACKAGES //使用到的外部插件包
EXTRACT_ALL //提取所有
EXTRACT_LOCAL_CLASSES //提取所有本地类
EXTRACT_LOCAL_METHODS //提取所有本地方法
EXTRACT_PRIVATE //提取所有private
EXTRACT_STATIC //提取所有static
FILE_PATTERNS //文件路径
FILE_VERSION_FILTER //文件版本控制
FILTER_PATTERNS //控制格式（主版本：第1次版本：第2次版本号）
FILTER_SOURCE_FILES //原文件的版本控制
FULL_PATH_NAMES //全路径名
GENERATE_AUTOGEN_DEF //生成自动定义文件形式
GENERATE_BUGLIST //生成BUG列表
GENERATE_CHI //生成"希腊字母"
GENERATE_DEPRECIATEDLIST //生成"评估"列表
GENERATE_HTML //生成HTML
GENERATE_HTMLHELP //生成HTMLHELP
GENERATE_LATEX //生成LATEX
GENERATE_LEGEND //生成图例
GENERATE_MAN //生成MAN文件
GENERATE_PERLMOD //生成Perl脚本
GENERATE_RTF //生成RTF
GENERATE_TAGFILE //生成标志文件
GENERATE_TESTLIST //生成TESTLIST
GENERATE_TODOLIST //生成TODOLIST
GENERATE_TREEVIEW //生成树状视图显示
GENERATE_XML //生成XML
GRAPHICAL_HIERARCHY //继承图表
GROUP_GRAPHS //组-图
HAVE_DOT //隐藏DOT
HHC_LOCATION //隐藏位置
HIDE_FRIEND_COMPOUNDS //隐藏"复合的"友员类型
HIDE_IN_BODY_DOCS //隐藏文档的主体
HIDE_SCOPE_NAMES //隐藏"作用域"名
HIDE_UNDOC_CLASSES //隐藏"未归档"的所有CLASS
HIDE_UNDOC_MEMBERS //隐藏"未归档"的所有的成员
HIDE_UNDOC_RELATIONS //隐藏"未归档"的关系
HTML_ALIGN_MEMBERS //HTML文档中成员对齐方式
HTML_FOOTER //HTML脚注设置
HTML_HEADER //HTML头部设置
HTML_OUTPUT //HTML输出设置
HTML_STYLESHEET //HTML样式设置
IGNORE_PREFIX //忽略哪些前缀
IMAGE_PATH //图片的路径设置
INCLUDE_GRAPH //包含-图
INCLUDE_PATH //头文件包含的路径
INHERIT_DOCS //文档的继承关系
INLINE_INFO //内联信息
INLINE_INHERITED_MEMB //通过"继承"得到的内联成员
INLINE_SOURCES //内联部分的源代码
INPUT //输入设置
INPUT_FILTER //能够接受的输入文件的扩展名格式设置（重要）
INTERNAL_DOCS //内部文档
JAVADOC_AUTOBRIEF //JAVADOC工具生成的文档的"自动摘要"
LATEX_BATCHMODE //LATEX匹配方式
LATEX_CMD_NAME //LATEX 命令名
LATEX_HEADER //LATEX 头部
LATEX_HIDE_INDICES //LATEX内部隐藏的包含
LATEX_OUTPUT //LATEX输出
MACRO_EXPANSION //宏展开设置（重要）
MAKEINDEX_CMD_NAME //MAKEINDEX命令索引
MAN_EXTENSION //MAN扩展
MAN_LINKS //MAN 链接设置
MAN_OUTPUT //MAN输出设置
MAX_DOT_GRAPH_DEPTH //DOT图的最大深度
MAX_DOT_GRAPH_HEIGHT //DOT图的最大高度
MAX_DOT_GRAPH_WIDTH //DOT图的最大宽度
MAX_INITIALIZER_LINES //最大初始化行
MULTILINE_CPP_IS_BRIEF //多个CPP文件的简短描述
OPTIMIZE_OUTPUT_FOR_C //对C采用的优化设置
OPTIMIZE_OUTPUT_JAVA //对JAVA采用的优化设置
OUTPUT_DIRECTORY //输出路径设置（重要）
OUTPUT_LANGUAGE //输出语言设置（重要）
PAPER_TYPE //纸张类型
PDF_HYPERLINKS //PDF格式超链接设置（重要）
PERL_PATH //perl路径设置
PERLMOD_LATEX //perlmod LATEX
PERLMOD_PRETTY // perlmod PRETTY（漂亮/相当）
PERLMOD_MAKEVAR_PREFIX //perlmod MAKE文件版本 PREFIX
PREDEFINED //预先定义（重要）
PROJECT_NAME //工程名（重要）
PROJECT_NUMBER //工程的组成成员（重要）
QUIET //静态量设置（重要）
RECURSIVE //递归和循环
REFERENCED_BY_RELATION //交叉参考（重要）
REFERENCES_RELATION //交叉参考的关系
REPEAT_BRIEF //重新设置"简短说明"为打开状态
RTF_EXTENSIONS_FILE //RTF展开文件
RTF_HYPERLINKS //RTF超链接
RTF_OUTPUT //RTF输出设置
RTF_STYLESHEET_FILE //RTF样式文件
SEARCH_INCLUDES //搜索时需要包含什么（重要）
SEARCHENGINE //搜索引擎设定（重要）
SHORT_NAMES //使短文件名生效
SHOW_DIRECTORIES //显示目录
SHOW_INCLUDE_FILES //显示包含文件（一般NO，否则太大）
SHOW_USED_FILES //显示被用到的文件（一般YES）
SKIP_FUNCTION_MACROS //跳过函数中的宏（重要），菜鸟最好别跳
SORT_BRIEF_DOCS //文档的简短摘要
SORT_MEMBER_DOCS //成员的简短描述
SOURCE_BROWSER //原文件浏览路径
STRIP_CODE_COMMENTS //排除哪些条码形式注释（重要）
STRIP_FROM_INC_PATH //排除哪些头文件包含的注释（重要）
STRIP_FROM_PATH //排除哪些条码路径设置
SUBGROUPING //子组设置（重要）
TAB_SIZE //TAB符SIZE设置（重要）
TAGFILES //标志文件
TEMPLATE_RELATIONS //模板关系设置（重要）
TOC_EXPAND //TOC扩展
TREEVIEW_WIDTH //树状图显示的宽度设置（重要）
UML_LOOK //UML外观设置（重要）
USE_WINDOWS_ENCODING //使用windows系统的编码形式（重要）
VERBATIM_HEADERS //VERBATIM头部（头文件）
WARN_FORMAT //警告格式指定（重要）
WARN_IF_DOC_ERROR //如果文档出错则显示警告
WARN_IF_UNDOCUMENTED //如果是未归档文件则显示警告
WARN_LOGFILE //警告日志文件设置
WARN_NO_PARAMDOC //无参数文档警告形式设定
WARNINGS //警告设置（重要）
XML_DTD //XML文件类型定义（重要）
XML_OUTPUT //XML输出设置（重要）
XML_PROGRAMLISTING //XML程序列表（重要）
XML_SCHEMA //XML模式设置（重要）

本文基于DoxyGen1.5.6及1.5.7。

转自http://madmanahong.blog.163.com/blog/static/488509620089842454971/

暴熊

关注

0
点赞
踩
6

收藏

觉得还不错? 一键收藏
0
评论
Doxygen心得(转)

doxygen是一款源代码帮助文档生成工具。依靠源代码中的注释，doxygen可以轻松的生成多种格式的帮助文档，供开发者阅读。 doxygen的使用方法很简单：第一步，需要修改源代码文件，规范现有注释。为了使注释轻松智能的变成可读的文档。doxygen规定了自己的注释格式，这样太才可以解析。最常用的注释格式是：/** there is com
复制链接

扫一扫