使用文档生成器Doxygen为c#项目生成文档
2018-08-24 17:47 xx-- 阅读(2802) 评论(0) 编辑 收藏 举报文档生成器——Doxygen
一、简介
Doxygen是一种开源跨平台的，以类似JavaDoc（java开发环境自带的API文档生成工具）风格描述的文档系统，完全支持C、C++、Java、Objective-C和IDL语言，部分支持PHP、C#。注释的语法与Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以从一套归档源文件（根据文件的形成规律和特点,保持文件之间的有机联系,区分不同价值,便于保管和利用的文件整理。）开始，生成HTML格式的在线类浏览器，或离线的LATEX、RTF参考手册。
二、功能及特点
Doxygen 是一个程序的文件产生工具，可将程序中的特定批注转换成为说明文件。减轻程序维护负担，添加文件整理负担。
三、安装相关程序
本文使用的为Doxygen 1.8.14
3.1、Doxygen
下载地址：http://sourceforge.net/projects/doxygen/?source=dlp
我们将在配置的时候使用doxywizard，Doxygen的GUI版本。
3.2、HTML Help Workshop
如果你希望你的Doxygen自动生成chm，那么请下载HTML Help Workshop，我们将要使用当中的hcc.exe文件以及相关dll下载地址：http://www.microsoft.com/en-us/download/details.aspx?id=21138
下载其中的htmlhelp.exe并安装，记住安装目录，我们将在Doxygen配置时使用。
3.3、 Graphviz
graphviz 是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图，如不需要此功能可不安装该工具包。
下载地址：https://graphviz.gitlab.io/download/
安装并记录安装目录，同样我们一会在配置Doxygen时使用。
添加系统环境变量：.建立变量名GRAPHVIZ_DOT值为安装的路径C:\Program Files (x86)\Graphviz2.34\bin\dot.exe，在用户环境变量添加以下一个变量，建立变量名 GRAPHVIZ_INSTALL_DIR, 值为如C:\Program Files (x86)\Graphviz2.34， 在系统环境变量中建立变量名PATH中添加Graphviz的bin目录路径，如C:\Program Files (x86)\Graphviz2.34\bin
四、使用（请勿包含中文路径）
Doxygen 产生文档可以分为三个步骤。一是在程序代码中加上符合Doxygen所定义批注格式。二是使用Doxywizard进行配置。三是使用Doxygen来产生批注文档。
4.1、wizard 标签下的 Project
Doxygen 目录，就是用来存放配置文件的目录（每生成一次文档退出时可选择保存本次配置）。
4.2、wizard 标签下的 Output
4.3、wizard 标签下的 Diagrams
选择这个选项之前需要先安装 Graphviz 工具包
4.4、expert 标签下的 Project
编码格式，UTF-8 是首选。如果需要显示中文则选择GB2312.（vs c#采用utf-8）
TAB_SIZE 主要是帮助文件中代码的缩进尺寸，譬如@code和@endcode段中代码的排版，建议设置成4。
OPTIMIZE_OUTPUT_FOR_C 这个选项选择后，生成文档的一些描述性名称会发生变化，主要是符合C习惯。如果是纯C代码，建议选择。
SUBGROUPING这个选项选择后，输出将会按类型分组。
4.5、expert 标签下的 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 ：是否显示文件列表页面，如果开启，那么帮助中会存在一个一个文件列表索引页面。
4.6、expert 标签下的 Input
4.7、expert 标签下的 HTML
若chm文件名为中文，生成的文档名会乱码。文件名在文档生成后可重命名。
CHM_FILE文件名需要加上后缀（xx.chm）。
如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项，此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。
为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码，CHM_INDEX_ENCODING中输入GB2312即可。
GENERATE_CHI 表示索引文件是否单独输出，建议关闭。否则每次生成两个文件，比较麻烦。
TOC_EXPAND 表示是否在索引中列举成员名称以及分组（譬如函数，枚举）名称。
4.8、选择 Run 标签
五、问题及解决方案
5.1、文档生成成功但无内置图片
原因： graphviz 安装配置错误
5.2、转码失败
原因及方案：确认并修改源文件编码格式
