几年前看过几个开源项目的文档发现每个开源都会有一

《几年前看过几个开源项目的文档发现每个开源都会有一》由会员分享，可在线阅读，更多相关《几年前看过几个开源项目的文档发现每个开源都会有一（7页珍藏版）》请在装配图网上搜索。

1、几年前，看过几个开源项目的文档，发现每个开源都会有一个帮助文件，感觉注释非常详细。 当时就感慨开源项目的人精力充沛。后发觉注释和代码有很多相似之处，经过研究，了解到 了 doxygen。正巧前段时间公司要程序生成文档，以前很多都是都是手工完成的。经过交 流，我们修改了部分源代码的注释，同时我写一个帮助，放到这里。doxygen是一款源代码帮助文档生成工具。依靠源代码中的注释，doxygen可以轻 松的生成多种格式的帮助文档，供开发者阅读。doxygen的使用方法很简单：第一步，需要修改源代码文件，规范现有注释。为了使注释轻松智能的变成可读的文 档。doxygen规定了自己的注释格式，这样太才可

2、以解析。最常用的注释格式是：/*there is comment.I*/或/*!there is comment.*/同时，为了区分注释的用途，doxygen定义了很多关键字，用来标识注释描述的代 码段或者用途。常用后面跟用途关键字来标识，关键字在doxygen附带的帮助文件中有 很详细的解析(在Special Commands这一节中)，这里就不在累赘了。这里有一个地方需 要注意一下，描述的各个分段之间最好用tab空开，用空格有的时候会出现问题。如：/* brief这是一个函数* param a 参数一* param b 参数二* return 无返回值*/void fooFun(int a

3、, int b);第二步，建立doxygen配置文件。doxygen执行的时候需要一个配置文件，即每生 成一个chm都会有一个配置文件来进行生成工程具体信息的描述。手工编写那个配置文件 比较繁琐，还好doxygen随身附带了一个DoxyWizard，利用这个向导。你可以方便的配 置想要的信息。注意DoxyWizard仅仅是一个界面，他最终编译的时候还是执行了 doxygen.exe，传输时不要只拷贝这一个文件。打开DoxyWizard，会发现DoxyWizard分成了三个区域。在step1中有三个按钮。按钮Wizard.里面配置项目的一些基本信息按钮Expert.包含高级配置信息按钮Load.

4、加载一个doxygen配置文件在stepl中，有个最重要的设置就是在Wizard.的Project页面中的Source code directory选项。把这个指向你的源代码文件路径。Scan recursively表示是否递归遍历。step1完成之后，你必须要保存一下doxygen配置文件。只需要点击step2的保存 按钮即可。step3中的工作目录，也就是doxygen最终生成的帮助文档(chm)的存放路径。最后，点击step4中的Start按钮即可。在Output列表中。是doxygen生成编译时生成的信息。注意上面已经提到过， DoxyWizard和doxygen是两个不同的进程，所以

5、在DoxyWizard输出日志的时候可能 会有停顿。具体显示时候的通信机制我没有看，但这和机器或者doxygen本身的代码没有 关系。我在这里主要讲一些基本常用的属性，很多我觉得意义不大的，请自行研究，这里就 不过多解释了。在Wizard.中没有特别复杂的地方，稍微看一眼便知。在Expert.按钮中，有一个tab页，下面来逐一解释：Project页面，主要包括项目的基本配置。TAB_SIZE主要是帮助文件中代码的缩进尺寸，譬如code和endcode段 中代码的排版，建议符合习惯，设置成4。OPTIMIZE_OUTPUT_FOR_C这个选项选择后，生成文档的一些描述性名 称会发生变化，主要是符

6、合C习惯。如果是纯C代码，建议选择。SUBGROUPING这个选项选择后，输出将会按类型分组。Build页面，这个页面是生成帮助信息中比较关键的配置页面EXTRACT_ALL表示输出所有的函数，但是private和static函数不属于其管 制。EXTRACT_PRIVATE 表示输出 private 函数。EXTRACT_STATIC表示输出static函数。同时还有几个EXTRACT，相应查 看文档即可。HIDE_UNDOC_MEMBERS表示那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然，如果EXTRACT_ALL被启用，那么这个标志其实是被 忽略的。INTERN

7、AL_DOCS主要指是否输出注解中的internal部分。如果没有被启 动，那么注解中所有的internal部分都将在目标帮助中不可见。CASE_SENSE_NAMES是否关注大小写名称，注意，如果开启了，那么所有 的名称都将被小写。对于C/C+这种字母相关的语言来说，建议永远不要开启。HIDE_SCOPE_NAMES域隐藏，建议永远不要开启。SHOW_INCLUDE_FILES是否显示包含文件，如果开启，帮助中会专门生 成一个页面，里面包含所有包含文件的列表。INLINE_INFO如果开启，那么在帮助文档中，inline函数前面会有一个inline 修饰词来标明。SORT_MEMBER_DO

8、CS如果开启，那么在帮助文档列表显示的时候，函数 名称会排序，否则按照解释的顺序显示。GENERATE_TODOLIST是否生成TODOLIST页面，如果开启，那么包含 在todo注解中的内容将会单独生成并显示在一个页面中，其他的GENERATE选项同。SHOW_USED_FILES是否在函数或类等的帮助中，最下面显示函数或类的 来源文件。SHOW_FILES是否显示文件列表页面，如果开启，那么帮助中会存在一个一 个文件列表索引页面。Messages页面主要用来设置编译时的输出信息选项。编译时的输出信息，主要可 以用来提醒一些输入的错误语法。QUIET如果开启，那么表示关闭编译时的输出信息。W

9、ARN_FORMAT表示日志输出的格式，没必要修改。WARN_LOGFILE表示信息是否输出到LOG文件，因为有DoxyWizard的 存在，所以这个选项没有必要使用。HTML页面CHM_FILE表示输出的chm文件路径GENERATE_CHI表示索引文件是否单独输出，建议关闭。否则每次生成两个 文件，比较麻烦。TOC_EXPAND表示是否在索引中列举成员名称以及分组（譬如函数，枚举） 名称。这个页面关系到生成chm的问题，不过很多选项很简单，一看便知。Preprocessor页面是预处理页面，里面也有一些配置，但是个人感觉使用默认就 行了。其他的几个页面，基本上都要依赖于某些其他第三方的模块

10、，尽管有些doxygen自 带了，但是其详细说明，还得考读者自行研究。同时附上常用的doxygen命令列表。注意doxygen的注解命令主要分成doxygen 自建命令，HTML命令方式和XML命令方式。所有的命令都是以或者字符开头，这 表明如果你的注释中有开头的单词，你必须要修改成。由于doxygen命令比较多，另外就是doxygen的帮助文档也是非常完善，所以， 这里仅仅列举几个常用的命令，其他命令请自行参考帮助文件。addtogroup添加到一个组。brief概要信息deprecated巳废弃函数details详细描述note开始一个段落，用来描述一些注意事项par开始一个段落，段落名称

11、描述由你自己指定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

12、/HTML Help Workshop/hhc.exe 然后点击 OK，保存，编译 即可。如何像MSDN那样在左边的树中显示函数列表？打开Expert.的HTML页面，然后选中TOC_EXPAND即可。如何去掉CHM附带的CHI文件？注意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇 到过很多用户仅仅上传了 CHM，而没有上传CHI文件，导致无法正常显示的情况。我不知 道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开Expert.的 HTML页面，取消GENERATE_CHI即可。如何像MSDN那样右边每页显示一个函数？这个问题其实比较棘手，在Exp

13、ert.中的Project页面，下面有一个选项叫做 SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有 一个问题，那就是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法 去掉。我的解决方法就是自己编译一下doxygen，在memberlist.cpp的 writeDocumentationPage 函数中将 container-writeQuickMemberLinks(ol,md); 连同附近几行屏蔽掉即可。如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？这个功能就是在chm的左边树中直接列出函数列表，而不用点击看右

14、边页面了。这 个功能需要修改源代码。在index.cpp中，屏蔽writeGroupIndexItem函数的Doxygen:indexList.addContentsItem, Doxygen:indexList.incContentsDepth 和 Doxygen:indexList.decContentsDepth();即可，具体不解释了，一看便知。如何修改或者去掉右下脚Generated at .的文字？打开Expert.的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件 即可。注意HTML_FOOTER中至少包含BODY和HTML结束标记。即一个最小的尾部 HTML至

15、少是这样。同理，如果你要指定了 HTML_HEADER，他至 少包含 如何生成组？组就是可以把同类的函数放到一个根下的显示方式o doxygen支持grouping，即你 可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是通过几个内置语法命令。 首先通过defgroup定义一个组，然后要把分组的函数或者类等，通过标志ingroup加 入相应的组。这样，相应的函数就被放置在同一个组中。如何生成中文帮助？点击Expert.，在页 Project 的 OUTPUT_LANGUAGE，选择Chinese，这样输 出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。如何彻底解决Doxy

16、Gen的输出中文chm的乱码问题？DoxyGen的实现中大概有三处编码的设置。首先是，doxyfile，也就是配置文件。 其次，INPUT_ENCODING，也就是DoxyGen需要解析的输入文件的编码。最后，就是 输出的编码。譬如CHM左边的索引编码。首先是chm的标题乱码，这个比较好解决，因为DoxyWizard使用QT做的界面， 它内部做了转换，所以在DoxyWizard中输入中文，在保存的时候，他自己做了转码，导 致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件， 输入相应中文即可。注意保存的时候保存成ANSI编码即可。保存成其他格式的话可

17、能需要 去掉BOM，比较麻烦，没研究了。这个相应的编码设置在Expert.中，页Project的 DOXYFILE_ENCODING，不输入或者默认为UTF-8都行。其次是右边内容乱码，这个多半是因为你没有配置好输入的文件编码类型造成的。在 Expert.的Input页面中，有一个INPUT_ENCODING，这个选项表示输入文件的编 码方式，这要和你处理的源文件格式一致。对于我们来说(使用vs的人)，一般设置为 GB2312o当然，再次声明，编码方式取决于源文件的编码方式。如果文件编码已经是UTF-8 了，然而你还将其设置成GB2312,那么DoxyGen会将UTF-8当成ANSI再进行一次

18、 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或者w

19、indows-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是一个开源项目，并且支持vs2005项目，这样一来，如果你觉得 哪里不顺手，完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是 perfect，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运