最近好几个朋友问我,项目代码越写越多,接口文档全靠手写,改一处代码就得回头翻半天文档,累得够呛。其实这事有现成的工具能解决,就是Doxygen。它能把代码里的注释自动抽出来,生成一整套网页版文档,类、函数、参数、返回值都给你列得明明白白。我自己用了两三年,从一开始瞎配到后来摸清门道,中间踩的坑不算少,今天就把Doxygen代码文档生成的完整流程和实用技巧聊一聊,不管你是写C++、JAVA还是Python,照着做基本都能跑通。
安装这一步没啥难度,官网下对应系统的包,Windows直接下一步到底,Linux用包管理器装就行。装完之后很多人第一反应是打开GUI乱点,我当初也是,结果生成出来的文档一堆乱码,目录结构也看不懂。后来才明白,关键是那个Doxyfile配置文件。命令行敲doxygen -g就能生成一份默认配置,里面几百个选项别慌,常用的就那么十几个。比如INPUT填你的源码目录,RECURSIVE设成YES让它自己往里找,OUTPUT_DIRECTORY指定文档输出位置,这三个先搞定,剩下的默认值够用。想省事的话,GUI里改完直接保存,效果一样。
有一点要提醒,路径里尽量别带中文和空格,我有个项目放在“我的文档”下面,生成的时候各种报错,挪到纯英文路径立马就好了。这种小细节看着不起眼,卡起人来是真难受。
Doxygen认的是特定格式的注释,不是随便写两行汉字就行。C++里常用/** ... */或者///,Java用/** */,Python则是##加特定标记。函数说明里用@param写参数、@return写返回值、@brief写一句话简介,这几个是最常用的。Doxygen注释规范其实不难记,写两遍就顺手了,难的是坚持。我的建议是别想着回头补,新写的函数当场就把注释带上,不然攒到后面根本不想动。
还有个坑得说,中文注释生成出来乱码,十有八九是编码没对上。在Doxyfile里把DOXYFILE_ENCODING和INPUT_ENCODING都设成UTF-8,再把OUTPUT_LANGUAGE改成Chinese,基本就正常了。要是还乱,检查一下源文件本身是不是UTF-8,有些老项目是GBK的,转一下再生成。
配置跑通之后,想让Doxygen生成的文档真正好用,还有几招。第一,善用@mainpage写个首页说明,把项目简介、编译方法放进去,别人打开文档第一眼就知道这是干啥的。第二,EXTRACT_ALL设成YES能把没写注释的也列出来,但我不太推荐,文档里一堆空白条目反而乱,不如老老实实写注释。第三,生成HTML就够了,CHM那套老格式现在没必要折腾,HTML直接丢到内网服务器或者GitHub Pages上,团队随时能看。
另外Doxygen还能顺手画+调用关系图,前提是你装了Graphviz,把HAVE_DOT打开,函数之间谁调谁一目了然,排查逻辑挺方便。不过大项目图会特别大,加载慢,按需开就行。最后提一句,可以把生成命令挂到CI里,代码一提交文档自动更新,省得老是手动跑,这才是代码文档自动生成最舒服的用法。
总的来说,Doxygen这工具上手门槛不高,配置一次后面基本不用管,关键是注释习惯得养起来。花个把小时把项目配好,以后省下的时间绝对划算。