说实话,刚工作那会儿我特别烦写文档,项目一多,代码注释东一句西一句,回头自己都看不懂。后来被同事安利了Doxygen,才发现这玩意儿是真省事——只要注释按它的规范写,一份漂亮的HTML文档直接就生成了。今天就把我这两年踩坑攒下来的Doxygen注释规范和配置技巧全盘托出,不管你是学生做课设,还是公司里维护老项目,照着弄基本不会翻车。
先搞明白Doxygen到底认哪种注释
很多人第一次用Doxygen,文档生成出来一片空白,八成是注释格式没对上。它主要认两种:一种是Javadoc风格,就是/**开头、*/结尾那种;另一种是Qt风格的/*! */。我平时用前者多,顺手。关键点在于,普通注释//和/* */它是直接忽略的,你写得再详细也白搭。
还有个容易忽略的细节:注释必须紧挨着被描述的代码,中间隔个空行它就可能认不到。我之前就吃过这个亏,函数前面空了一行,结果文档里那个函数死活不出现,排查了半天才发现是空行惹的祸。所以记住,Doxygen注释要贴着代码写,别手贱加空行。
常用注释命令,记住这几个就够用
命令一大堆,但日常真正高频的就那么几个。@brief写一句话简介,@param描述参数,@return写返回值,@author和@date看情况加。别一上来就想把所有命令用全,反而显得乱。
举个我常用的写法:函数上方先@brief一句话说清楚干啥,然后每个参数一行@param,返回值一行@return。这样生成出来的文档结构清晰,别人看代码也舒服。另外@note和@warning挺实用,遇到有坑的地方标一下,比如参数不能传空之类的,能救后来人一命。想搜长尾词的话,Doxygen注释命令大全这类内容网上不少,但真正常用的就这些,别贪多。
Doxyfile配置文件,别被几百个选项吓到
第一次打开Doxyfile我人是懵的,几百行配置项,密密麻麻。其实Doxygen配置没那么玄乎,绝大多数保持默认就行,真正要动的就那么几个。
PROJECT_NAME填项目名,OUTPUT_DIRECTORY指定输出目录,INPUT写源码路径,RECURSIVE设成YES让它递归找子目录。这几个搞定,基本就能跑起来了。EXTRACT_ALL建议设YES,不然没注释的函数它不给生成,新手容易在这卡住。GENERATE_LATEX设NO,除非你真要出PDF,不然编译LaTeX能烦死人。还有HTML_OUTPUT可以自定义输出文件夹名,方便区分多个项目。
我一般还会把WARN_IF_UNDOCUMENTED打开,这样哪些函数没写注释,生成时会给你警告,逼着自己补全。这招对团队协作特别管用,谁偷懒一眼就看出来。
中文乱码和路径问题,两个高频坑
中文注释生成出来变乱码,这事太常见了。根源是编码没对上,Doxyfile里把DOXYFILE_ENCODING和INPUT_ENCODING都设成UTF-8,基本能解决大部分情况。要是还不行,检查下源文件本身是不是UTF-8,有些老项目是GBK的,得先转码。
路径问题也烦人,INPUT里写相对路径时,是相对于你运行doxygen命令的目录,不是Doxyfile所在目录。我习惯直接写绝对路径或者用$(PWD)变量,省得来回切目录搞混。另外排除目录用EXCLUDE,像第三方的库、测试代码这些没必要生成文档,排除掉能快不少。
生成之后怎么用,顺带说两句
配置好跑一遍doxygen,HTML文件夹里index.html打开就能看。搜索框、类列表、文件列表都有,比自己翻代码快多了。想集成到CI里也行,每次提交自动生成,部署到内网服务器,团队随时查。
最后唠叨一句,Doxygen注释规范这东西贵在坚持,别指望一次性全补完。可以先从公共接口、核心函数开始写,慢慢养成习惯。工具是死的,注释写得好不好还是看人,但至少Doxygen能帮你把写好的东西整理得像模像样,这点就值回票价了。
配置过程中要是遇到啥奇葩问题,多半是某个选项没设对,回头翻翻官方文档或者搜一下,基本都能找到答案。别怕折腾,弄通一次以后就是复制粘贴的事了。


喜欢
高兴
鬼脸
呵呵
无聊
伤心